> ## Documentation Index
> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 按计划运行提示词

> 使用 /loop 和 cron 调度工具在 Claude Code 会话中重复运行提示词、轮询状态或设置一次性提醒。

<Note>
  计划任务需要 Claude Code v2.1.72 或更高版本。使用 `claude --version` 检查您的版本。
</Note>

计划任务让 Claude 按间隔自动重新运行提示词。使用它们来轮询部署、监督 PR、检查长时间运行的构建，或在会话中稍后提醒自己做某事。要对事件进行实时反应而不是轮询，请参阅 [Channels](/zh-CN/channels)：您的 CI 可以直接将失败推送到会话中。要保持会话工作转向转向直到满足条件而不是按间隔，请参阅 [`/goal`](/zh-CN/goal)。

任务是会话范围的：它们存在于当前对话中，当您启动新对话时就会停止。使用 `--resume` 或 `--continue` 恢复会带回任何尚未[过期](#seven-day-expiry)的任务：在过去 7 天内创建的重复任务，或计划时间尚未到达的一次性任务。对于独立于任何会话而存在的调度，请使用 [Routines](/zh-CN/routines) 在 Anthropic 管理的基础设施上创建例程、设置 [Desktop 计划任务](/zh-CN/desktop-scheduled-tasks)，或使用 [GitHub Actions](/zh-CN/github-actions)。

<h2 id="compare-scheduling-options">
  比较调度选项
</h2>

Claude Code offers three ways to schedule recurring or one-off work:

|                            | [Cloud](/en/routines)          | [Desktop](/en/desktop-scheduled-tasks) | [`/loop`](/en/scheduled-tasks)      |
| :------------------------- | :----------------------------- | :------------------------------------- | :---------------------------------- |
| Runs on                    | Anthropic cloud                | Your machine                           | Your machine                        |
| Requires machine on        | No                             | Yes                                    | Yes                                 |
| Requires open session      | No                             | No                                     | Yes                                 |
| Persistent across restarts | Yes                            | Yes                                    | Restored on `--resume` if unexpired |
| Access to local files      | No (fresh clone)               | Yes                                    | Yes                                 |
| MCP servers                | Connectors configured per task | [Config files](/en/mcp) and connectors | Inherits from session               |
| Permission prompts         | No (runs autonomously)         | Configurable per task                  | Inherits from session               |
| Customizable schedule      | Via `/schedule` in the CLI     | Yes                                    | Yes                                 |
| Minimum interval           | 1 hour                         | 1 minute                               | 1 minute                            |

<Tip>
  Use **cloud tasks** for work that should run reliably without your machine. Use **Desktop tasks** when you need access to local files and tools. Use **`/loop`** for quick polling during a session.
</Tip>

<h2 id="run-a-prompt-repeatedly-with-/loop">
  使用 /loop 重复运行提示词
</h2>

`/loop` [bundled skill](/zh-CN/commands) 是在会话保持打开时重复运行提示词的最快方式。间隔和提示词都是可选的，您提供的内容决定了循环的行为方式。

| 您提供的内容 | 示例                          | 发生的情况                                                                 |
| :----- | :-------------------------- | :-------------------------------------------------------------------- |
| 间隔和提示词 | `/loop 5m check the deploy` | 您的提示词在[固定计划](#run-on-a-fixed-interval)上运行                             |
| 仅提示词   | `/loop check the deploy`    | 您的提示词在 Claude 选择的[间隔](#let-claude-choose-the-interval)上运行，每次迭代        |
| 仅间隔或无  | `/loop`                     | [内置维护提示词](#run-the-built-in-maintenance-prompt)运行，或您的 `loop.md`（如果存在） |

您也可以将 skill 作为提示词传递，例如 `/loop 20m /review-pr 1234`，以在每次迭代时重新运行该 skill。{/* min-version: 2.1.196 */}从 v2.1.196 开始，计划的触发仅运行 Claude [允许自己调用](/zh-CN/skills#control-who-invokes-a-skill)的 skill。以下内容作为纯文本到达 Claude，而不是执行：

* 内置命令，例如 `/permissions`、`/model` 或 `/clear`
* 标记为 [`disable-model-invocation: true`](/zh-CN/skills#frontmatter-reference) 的 skill
* 由 [`skillOverrides`](/zh-CN/skills#override-skill-visibility-from-settings) 设置或 `Skill` [deny rule](/zh-CN/skills#restrict-claude’s-skill-access) 从 Claude 扣留的 skill
* [MCP prompts](/zh-CN/mcp#use-mcp-prompts-as-commands)，例如 `/mcp__github__list_prs`；MCP 服务器公开的 skill 仍然运行

<h3 id="run-on-a-fixed-interval">
  在固定间隔上运行
</h3>

当您提供间隔时，Claude 将其转换为 cron 表达式，计划作业，并确认频率和作业 ID。

```text theme={null}
/loop 5m check if the deployment finished and tell me what happened
```

间隔可以作为裸令牌（如 `30m`）在提示词前面，或作为子句（如 `every 2 hours`）在后面。支持的单位是 `s` 表示秒、`m` 表示分钟、`h` 表示小时、`d` 表示天。

秒数向上舍入到最近的分钟，因为 cron 的粒度为一分钟。不能均匀映射到干净 cron 步长的间隔，例如 `7m` 或 `90m`，会舍入到最近的间隔，Claude 会告诉您它选择了什么。

<h3 id="let-claude-choose-the-interval">
  让 Claude 选择间隔
</h3>

当您省略间隔时，Claude 会动态选择一个，而不是在固定 cron 计划上运行。在每次迭代后，它会根据观察到的情况选择一个一分钟到一小时之间的延迟：在构建完成或 PR 活跃时等待较短时间，当没有待处理项时等待较长时间。选择的延迟和原因会在每次迭代结束时打印。

下面的示例检查 CI 和审查评论，Claude 在 PR 变得安静后在迭代之间等待更长时间：

```text theme={null}
/loop check whether CI passed and address any review comments
```

当您要求动态 `/loop` 计划时，Claude 可能会直接使用 [Monitor tool](/zh-CN/tools-reference#monitor-tool)。Monitor 运行后台脚本并流式传输每个输出行，这完全避免了轮询，通常比在间隔上重新运行提示词更节省令牌且响应更快。

动态计划的循环出现在您的[计划任务列表](#manage-scheduled-tasks)中，就像任何其他任务一样，所以您可以以相同的方式列出或取消它。[抖动规则](#jitter)不适用于它，但[七天过期](#seven-day-expiry)适用：循环在您启动它七天后自动结束。

<Note>
  在 Bedrock、Vertex AI 和 Microsoft Foundry 上，没有间隔的提示词在固定的 10 分钟计划上运行。
</Note>

<h3 id="run-the-built-in-maintenance-prompt">
  运行内置维护提示词
</h3>

当您省略提示词时，Claude 使用内置维护提示词而不是您提供的提示词。在每次迭代中，它按顺序处理以下内容：

* 继续对话中的任何未完成工作
* 照顾当前分支的拉取请求：审查评论、失败的 CI 运行、合并冲突
* 运行清理通过，例如当没有其他待处理项时的错误搜索或简化

Claude 不会启动该范围之外的新举措，不可逆的操作（如推送或删除）仅在继续转录已授权的内容时进行。

```text theme={null}
/loop
```

裸 `/loop` 在[动态选择的间隔](#let-claude-choose-the-interval)上运行此提示词。添加间隔，例如 `/loop 15m`，以在固定计划上运行它。要用您自己的默认值替换内置提示词，请参阅[使用 loop.md 自定义默认提示词](#customize-the-default-prompt-with-loop-md)。

<Note>
  在 Bedrock、Vertex AI 和 Microsoft Foundry 上，没有提示词的 `/loop` 会打印使用消息而不是运行维护提示词。
</Note>

<h3 id="customize-the-default-prompt-with-loop-md">
  使用 loop.md 自定义默认提示词
</h3>

`loop.md` 文件用您自己的说明替换内置维护提示词。它为裸 `/loop` 定义单个默认提示词，而不是单独计划任务的列表，并且在您在命令行上提供提示词时被忽略。要在其旁边计划其他提示词，请使用 `/loop <prompt>` 或[直接询问 Claude](#manage-scheduled-tasks)。

Claude 在两个位置查找文件，并使用它找到的第一个。

| 路径                  | 范围                  |
| :------------------ | :------------------ |
| `.claude/loop.md`   | 项目级别。当两个文件都存在时优先。   |
| `~/.claude/loop.md` | 用户级别。适用于任何未定义自己的项目。 |

该文件是纯 Markdown，没有必需的结构。像您直接输入 `/loop` 提示词一样编写它。以下示例保持发布分支健康：

```markdown title=".claude/loop.md" theme={null}
Check the `release/next` PR. If CI is red, pull the failing job log,
diagnose, and push a minimal fix. If new review comments have arrived,
address each one and resolve the thread. If everything is green and
quiet, say so in one line.
```

对 `loop.md` 的编辑在下一次迭代时生效，所以您可以在循环运行时优化说明。当任一位置都不存在 `loop.md` 时，循环回退到内置维护提示词。保持文件简洁：超过 25,000 字节的内容会被截断。

<Note>
  在 Bedrock、Vertex AI 和 Microsoft Foundry 上，`loop.md` 不被读取，没有提示词的 `/loop` 会打印使用消息。
</Note>

<h3 id="stop-a-loop">
  停止循环
</h3>

要在 `/loop` 等待下一次迭代时停止它，请按 `Esc`。这会清除待处理的唤醒，所以循环不会再次触发。您通过[直接询问 Claude](#manage-scheduled-tasks)计划的任务不受 `Esc` 影响，会保留在原位，直到您删除它们。

在[自主进行模式](#let-claude-choose-the-interval)中，Claude 也可以在任务可证明完成后通过不计划下一次唤醒来自己结束循环。固定间隔上的循环会一直运行，直到您停止它们或[七天过去](#seven-day-expiry)。

<h2 id="set-a-one-time-reminder">
  设置一次性提醒
</h2>

对于一次性提醒，用自然语言描述您想要的内容，而不是使用 `/loop`。Claude 计划一个单次触发的任务，该任务在运行后删除自己。

```text theme={null}
remind me at 3pm to push the release branch
```

```text theme={null}
in 45 minutes, check whether the integration tests passed
```

Claude 使用 cron 表达式将触发时间固定到特定的分钟和小时，并确认何时触发。

<h2 id="manage-scheduled-tasks">
  管理计划任务
</h2>

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

```text theme={null}
what scheduled tasks do I have?
```

```text theme={null}
cancel the deploy check job
```

在幕后，Claude 使用这些工具：

| 工具           | 目的                                          |
| :----------- | :------------------------------------------ |
| `CronCreate` | 计划新任务。接受 5 字段 cron 表达式、要运行的提示词以及是否重复或仅触发一次。 |
| `CronList`   | 列出所有计划任务及其 ID、计划和提示词。                       |
| `CronDelete` | 按 ID 取消任务。                                  |

每个计划任务都有一个 8 字符的 ID，您可以将其传递给 `CronDelete`。一个会话最多可以同时保存 50 个计划任务。

<h2 id="how-scheduled-tasks-run">
  计划任务如何运行
</h2>

调度程序每秒检查一次到期的任务，并以低优先级将其加入队列。计划的提示词在您的回合之间触发，而不是在 Claude 正在响应时。如果 Claude 在任务到期时忙碌，提示词会等到当前回合结束。

所有时间都在您的本地时区中解释。像 `0 9 * * *` 这样的 cron 表达式意味着 9am 在您运行 Claude Code 的任何地方，而不是 UTC。

<h3 id="jitter">
  抖动
</h3>

为了避免每个会话在同一个挂钟时刻击中 API，调度程序会向触发时间添加一个确定性偏移：

* 重复任务最多在计划时间之后 30 分钟触发（或对于运行频率超过每小时的任务，最多为间隔的一半）。为 `:00` 计划的每小时作业可能在 `:00` 到 `:30` 之间的任何时间触发。
* 为小时顶部或底部计划的一次性任务最多提前 90 秒触发。

偏移是从任务 ID 派生的，所以相同的任务总是获得相同的偏移。如果精确的时间很重要，选择不是 `:00` 或 `:30` 的分钟，例如 `3 9 * * *` 而不是 `0 9 * * *`，一次性抖动将不适用。

<h3 id="seven-day-expiry">
  七天过期
</h3>

重复任务在创建后 7 天自动过期。任务最后触发一次，然后删除自己。这限制了被遗忘的循环可以运行多长时间。如果您需要重复任务持续更长时间，请在过期前取消并重新创建它，或使用 [Routines](/zh-CN/routines) 或 [Desktop 计划任务](/zh-CN/desktop-scheduled-tasks) 进行持久调度。

<h2 id="cron-expression-reference">
  Cron 表达式参考
</h2>

`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 * * *`    | 每天本地时间 9am          |
| `0 9 * * 1-5`  | 工作日本地时间 9am         |
| `30 14 15 3 *` | 3 月 15 日本地时间下午 2:30 |

星期几使用 `0` 或 `7` 表示星期日，`6` 表示星期六。不支持扩展语法如 `L`、`W`、`?` 和名称别名如 `MON` 或 `JAN`。

当月份日期和星期几都受到限制时，如果任一字段匹配，日期就匹配。这遵循标准的 vixie-cron 语义。

<h2 id="disable-scheduled-tasks">
  禁用计划任务
</h2>

在您的环境中设置 `CLAUDE_CODE_DISABLE_CRON=1` 以完全禁用调度程序。cron 工具和 `/loop` 变得不可用，任何已计划的任务都停止触发。有关禁用标志的完整列表，请参阅[环境变量](/zh-CN/env-vars)。

<h2 id="limitations">
  限制
</h2>

会话范围的调度有固有的限制：

* 任务仅在 Claude Code 运行且空闲时触发。关闭终端或让会话退出会停止它们触发。[将会话放在后台](/zh-CN/agent-view#from-inside-a-session)会将 `/loop` 任务转移到后台会话，该会话继续运行而无需终端。
* 没有错过触发的追赶。如果任务的计划时间在 Claude 忙于长时间运行的请求时经过，它会在 Claude 变为空闲时触发一次，而不是每个错过的间隔触发一次。
* 启动新对话会清除所有会话范围的任务。使用 `claude --resume` 或 `claude --continue` 恢复会恢复尚未过期的任务：创建后七天内的重复任务，以及计划时间尚未到达的一次性任务。后台 Bash 和监视器任务在恢复时永远不会被恢复。

对于需要无人值守运行的 cron 驱动自动化：

* [Routines](/zh-CN/routines)：在 Anthropic 管理的基础设施上按计划运行、通过 API 调用或在 GitHub 事件上运行
* [GitHub Actions](/zh-CN/github-actions)：在 CI 中使用 `schedule` 触发器
* [Desktop 计划任务](/zh-CN/desktop-scheduled-tasks)：在您的机器上本地运行