# 按计划运行 Prompt

> 定时任务允许 Qwen Code 按固定间隔自动重新运行 prompt。你可以使用它们来轮询部署状态、看护 PR、检查长时间运行的构建，或者提醒自己在会话的稍后时间做某事。

- 网址：https://funcoding.ai/agents/qwen-code/users/features/scheduled-tasks/
- 来源：Qwen Code 官方文档原文（中文），Apache-2.0 许可，同步于 2026-10-11
- 官方原文：https://qwenlm.github.io/qwen-code-docs/zh/users/features/scheduled-tasks

---
> 在 Qwen Code 会话中，使用 `/loop` 和 cron 调度工具来重复运行 prompt、轮询状态或设置一次性提醒。

定时任务允许 Qwen Code 按固定间隔自动重新运行 prompt。你可以使用它们来轮询部署状态、看护 PR、检查长时间运行的构建，或者提醒自己在会话的稍后时间做某事。

任务的作用域限定在当前会话：它们存在于当前的 Qwen Code 进程中，退出时即被销毁。不会向磁盘写入任何内容。

消息通道使用独立的持久调度器，以便在当前轮次之后将结果推送回发起聊天的通道。请参阅[定时通道循环](https://funcoding.ai/agents/qwen-code/users/features/channels/overview/#scheduled-channel-loops)了解通道命令、持久化行为和投递约束。

> **提示：** 定时任务默认启用。要禁用它们，请在[设置](https://funcoding.ai/agents/qwen-code/users/configuration/settings/)中设置 `experimental.cron: false`，或在环境变量中设置 `QWEN_CODE_DISABLE_CRON=1`。

## 使用 /loop 安排循环 prompt

`/loop` [内置 skill](https://funcoding.ai/agents/qwen-code/users/features/skills/) 是安排循环 prompt 的最快方法。传入一个可选的间隔和 prompt，Qwen Code 就会设置一个 cron 任务，在会话保持打开期间于后台触发。

```text
/loop 5m check if the deployment finished and tell me what happened
```

Qwen Code 会解析间隔，将其转换为 cron 表达式，安排任务，并确认执行频率和任务 ID。然后它会立即执行一次该 prompt——你无需等待第一次 cron 触发。

### 间隔语法

间隔是可选的。你可以将其放在开头、放在结尾，或者完全省略。

| 形式 | 示例 | 解析后的间隔 |
| :--- | :--- | :--- |
| 前导 token | `/loop 30m check the build` | 每 30 分钟 |
| 尾部 `every` 子句 | `/loop check the build every 2 hours` | 每 2 小时 |
| 无间隔 | `/loop check the build` | 默认为每 10 分钟 |

支持的单位有 `s`（秒）、`m`（分钟）、`h`（小时）和 `d`（天）。由于 cron 的最小粒度为分钟，秒会被向上取整到最近的分钟。不能整除其单位的间隔（如 `7m` 或 `90m`）会被四舍五入到最近的整数间隔，Qwen Code 会告诉你它选择了哪个。

### 循环执行其他命令

调度的 prompt 本身可以是一个命令或 skill 调用。这对于重新运行你已经打包好的工作流非常有用。

```text
/loop 20m /review-pr 1234
```

每次任务触发时，Qwen Code 都会运行 `/review-pr 1234`，就像你亲自输入的一样。

### 自主模式

运行 `/loop` 时**不提供 prompt** 会启动一个自主循环，而不是重复固定的 prompt。Qwen Code 会作为对话中已建立工作的管理者——在你离开时推动工作继续：

```text
/loop
```

单独的 `/loop`（无 prompt，无间隔）会运行一个自定步调的自主循环；不带 prompt 的 `/loop <interval>` 会以固定频率运行相同的自主循环（例如 `/loop 10m`）。每次触发时，它都会推进对话中已经设置好的工作——完成你开始的事情、维护进行中的 PR（处理 review 线程、修复失败的 CI、解决冲突），并履行后续承诺。它仅对对话记录中已经确立的工作采取行动：在没有明确授权的情况下，它绝不会凭空创造新工作或进行不可逆的更改（push、delete、send），并且一旦所有事情都处理完毕，它就会停止。

### 管理循环

`/loop` 还支持两个用于管理现有任务的子命令：

```text
/loop list
```

列出所有已调度的任务及其 ID 和 cron 表达式。

```text
/loop clear
```

一次性取消所有已调度的任务。

## 设置一次性提醒

对于一次性提醒，请使用自然语言描述你的需求，而不是使用 `/loop`。Qwen Code 会安排一个单次触发的任务，该任务在运行后会自动删除自身。

```text
remind me at 3pm to push the release branch
```

```text
in 45 minutes, check whether the integration tests passed
```

Qwen Code 使用 cron 表达式将触发时间固定到具体的分钟和小时，并确认其触发时间。

## 管理定时任务

使用自然语言要求 Qwen Code 列出或取消任务，或者直接引用底层工具。

```text
what scheduled tasks do I have?
```

```text
cancel the deploy check job
```

在底层，Qwen Code 使用以下工具：

| 工具 | 用途 |
| :--- | :--- |
| `CronCreate` | 安排新任务。接受 5 字段的 cron 表达式、要运行的 prompt，以及是循环执行还是单次执行。 |
| `CronList` | 列出所有已调度的任务及其 ID、计划和 prompt。 |
| `CronDelete` | 按 ID 取消任务。 |

每个定时任务都有一个 8 字符的 ID，你可以将其传递给 `CronDelete`。一个会话最多可以同时容纳 50 个定时任务。

## 定时任务的运行机制

调度器每秒检查一次到期任务，并在会话空闲时将其加入队列。调度的 prompt 会在你的回合之间触发，而不是在 Qwen Code 响应过程中触发。如果任务到期时 Qwen Code 正忙，prompt 会等待直到当前回合结束。

所有时间均按你的本地时区解释。像 `0 9 * * *` 这样的 cron 表达式表示在你运行 Qwen Code 的本地时间早上 9 点，而不是 UTC 时间。

### 抖动

为了避免所有会话在同一物理时间点击中 API，调度器会为触发时间添加一个小的确定性偏移量：

- **循环任务** 最多会延迟其周期的 10% 触发，上限为 15 分钟。一个每小时执行的任务可能会在 `:00` 到 `:06` 之间的任何时间触发。
- 安排在整点或半点（分钟为 `:00` 或 `:30`）的**一次性任务** 最多会提前 90 秒触发。

偏移量由任务 ID 派生，因此同一个任务总是获得相同的偏移量。如果精确的时间很重要，请选择不是 `:00` 或 `:30` 的分钟，例如使用 `3 9 * * *` 而不是 `0 9 * * *`，这样一次性任务的抖动就不会生效。

### 循环任务过期

默认情况下，循环任务在创建 7 天后自动过期。任务会最后一次触发，然后删除自身。这限制了被遗忘的循环可以运行的时间。

要更改此限制，请在[设置](https://funcoding.ai/agents/qwen-code/users/configuration/settings/)中设置 `experimental.cronRecurringMaxAgeDays`，或设置 `QWEN_CODE_CRON_MAX_AGE_DAYS` 环境变量（环境变量优先——这在编辑 `settings.json` 不切实际的云或容器部署中非常方便）。值为 `0` 会完全禁用过期，因此任务会一直运行直到你删除它们——这对于托管每日报告、摘要或持续监控的长时间运行的守护进程部署非常有用。配置的限制也适用于重启后从磁盘恢复的持久化任务。

一次性任务不会按计时器过期——它们只是在触发一次后直接删除自身。

## Cron 表达式参考

`CronCreate` 接受标准的 5 字段 cron 表达式：`minute hour day-of-month month day-of-week`。所有字段都支持通配符（`*`）、单个值（`5`）、步长（`*/15`）、范围（`1-5`）和逗号分隔的列表（`1,15,30`）。

| 示例 | 含义 |
| :--- | :--- |
| `*/5 * * * *` | 每 5 分钟 |
| `0 * * * *` | 每小时整点 |
| `7 * * * *` | 每小时的第 7 分钟 |
| `0 9 * * *` | 每天本地时间上午 9 点 |
| `0 9 * * 1-5` | 工作日本地时间上午 9 点 |
| `30 14 15 3 *` | 3 月 15 日本地时间下午 2:30 |

星期字段使用 `0` 或 `7` 表示星期日，`6` 表示星期六。当月份中的日期和星期几都受到限制（两者都不是 `*`）时，只要其中一个字段匹配，该日期就会匹配——这遵循标准的 vixie-cron 语义。

不支持扩展语法，如 `L`、`W`、`?`，以及 `MON` 或 `JAN` 等名称别名。

## 限制

会话作用域的调度具有固有的限制：

- 任务仅在 Qwen Code 运行且空闲时触发。关闭终端或让会话退出会取消所有任务。
- 不会补执行错过的触发。如果任务的调度时间在 Qwen Code 忙于处理长时间运行的请求时过去，它只会在 Qwen Code 变为空闲时触发一次，而不是按错过的间隔触发多次。
- 重启后不持久化。重启 Qwen Code 会清除所有会话作用域的任务。