{/* TRANSLATED — 已翻译为中文 */}

> ## 文档索引
> 在以下地址获取完整文档索引：https://code.claude.com/docs/llms.txt
> 使用此文件发现所有可用页面，然后再进一步探索。

# 按计划运行提示

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

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

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

任务是会话范围的：它们存在于当前对话中，当您开始新对话时停止。使用 `--resume` 或 `--continue` 恢复会带回任何未[过期](#七天过期)的任务：过去 7 天内创建的循环任务，或计划时间尚未到达的一次性任务。要获得独立于任何会话的持久调度，请使用[例程](/cn/routines)在 Anthropic 管理的基础设施上创建例程，设置[桌面计划任务](/cn/desktop-scheduled-tasks)，或使用 [GitHub Actions](/cn/github-actions)。

## 比较调度选项

Claude Code 提供三种调度循环或一次性工作的方式：

|                              | [云端](/cn/routines)           | [桌面](/cn/desktop-scheduled-tasks) | [`/loop`](/cn/scheduled-tasks)      |
| :--------------------------- | :----------------------------- | :----------------------------------- | :---------------------------------- |
| 运行在                       | Anthropic 云端                 | 您的机器                             | 您的机器                            |
| 需要机器开启                 | 否                             | 是                                   | 是                                  |
| 需要打开会话                 | 否                             | 否                                   | 是                                  |
| 跨重启持久                   | 是                             | 是                                   | 未过期时通过 `--resume` 恢复        |
| 访问本地文件                 | 否（全新克隆）                 | 是                                   | 是                                  |
| MCP 服务器                   | 按任务配置的连接器             | [配置文件](/cn/mcp) 和连接器         | 从会话继承                          |
| 权限提示                     | 否（自主运行）                 | 按任务可配置                         | 从会话继承                          |
| 可自定义调度                 | 通过 CLI 中的 `/schedule`      | 是                                   | 是                                  |
| 最小间隔                     | 1 小时                         | 1 分钟                               | 1 分钟                              |

<Tip>
  使用**云端任务**处理应该在没有您的机器的情况下可靠运行的工作。使用**桌面任务**当您需要访问本地文件和工具时。使用 **`/loop`** 进行会话期间的快速轮询。
</Tip>

## 使用 /loop 重复运行提示

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

| 您提供的内容            | 示例                        | 发生的事情                                                                                                  |
| :---------------------- | :-------------------------- | :---------------------------------------------------------------------------------------------------------- |
| 间隔和提示              | `/loop 5m check the deploy` | 您的提示按[固定计划](#按固定间隔运行)运行                                                                  |
| 仅提示                  | `/loop check the deploy`    | 您的提示在每次迭代时按 [Claude 选择的间隔](#让-claude-选择间隔)运行                                        |
| 仅间隔，或什么都不提供  | `/loop`                     | [内置维护提示](#运行内置维护提示)运行，或者您的 `loop.md`（如果存在）                                      |

您也可以传递另一个命令作为提示，例如 `/loop 20m /review-pr 1234`，以在每次迭代时重新运行打包的工作流。

### 按固定间隔运行

当您提供间隔时，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 会告诉您它选择了什么。

### 让 Claude 选择间隔

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

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

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

当您请求动态 `/loop` 调度时，Claude 可能直接使用[监控工具](/cn/tools-reference#monitor-tool)。监控运行后台脚本并将每行输出流式传回，这完全避免了轮询，通常比按间隔重新运行提示更节省令牌且更响应。

动态调度的循环与其他任务一样出现在您的[计划任务列表](#管理计划任务)中，因此您可以相同的方式列出或取消它。[抖动规则](#抖动)不适用，但[七天过期](#七天过期)适用：循环在启动七天后自动结束。

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

### 运行内置维护提示

当您省略提示时，Claude 使用内置维护提示代替您提供的提示。在每次迭代中，它按顺序执行以下操作：

* 继续对话中的任何未完成工作
* 维护当前分支的拉取请求：审查评论、失败的 CI 运行、合并冲突
* 在没有其他待处理事项时运行清理过程，如 bug 修复或简化

Claude 不会在该范围之外启动新的工作，推送或删除等不可逆操作只有在继续对话记录中已授权的操作时才会进行。

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

裸 `/loop` 按[动态选择的间隔](#让-claude-选择间隔)运行此提示。添加间隔，例如 `/loop 15m`，改为按固定计划运行。要用您自己的默认值替换内置提示，请参阅[使用 loop.md 自定义默认提示](#使用-loopmd-自定义默认提示)。

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

### 使用 loop.md 自定义默认提示

`loop.md` 文件用您自己的指令替换内置维护提示。它为裸 `/loop` 定义单个默认提示，而不是单独计划任务的列表，当您在命令行上提供提示时会被忽略。要在其旁边调度额外的提示，请使用 `/loop <prompt>` 或[直接询问 Claude](#管理计划任务)。

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>

### 停止循环

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

在[自定步调模式](#让-claude-选择间隔)中，Claude 也可以自行结束循环，一旦任务可证明完成就不再调度下次唤醒。固定间隔的循环会持续运行直到您停止它们或[七天过去](#七天过期)。

## 设置一次性提醒

对于一次性提醒，用自然语言描述您想要的内容而不是使用 `/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 表达式将触发时间固定到特定的分钟和小时，并确认何时触发。

## 管理计划任务

用自然语言询问 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 个计划任务。

## 计划任务如何运行

调度器每秒检查到期的任务并以低优先级入队。计划提示在您的轮次之间触发，而不是在 Claude 响应期间。如果 Claude 在任务到期时正忙，提示会等到当前轮次结束。

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

### 抖动

为避免每个会话在同一时刻命中 API，调度器为触发时间添加确定性偏移：

* 循环任务在计划时间后最多 30 分钟触发（对于每小时运行多次的任务，最多为间隔的一半）。计划在 `:00` 的每小时任务可能在 `:30` 之前的任何时间触发。
* 计划在整点或半点的一次性任务最多提前 90 秒触发。

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

### 七天过期

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

## 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` 表示星期六。不支持扩展语法如 `L`、`W`、`?` 和名称别名如 `MON` 或 `JAN`。

当 day-of-month 和 day-of-week 都受约束时，如果任一字段匹配则日期匹配。这遵循标准 vixie-cron 语义。

## 禁用计划任务

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

## 限制

会话范围的调度有固有的约束：

* 任务仅在 Claude Code 运行且空闲时触发。关闭终端或让会话退出会停止它们触发。
* 没有对错过触发的补发。如果任务的计划时间在 Claude 忙于长时间运行的请求时过去，它会在 Claude 变为空闲时触发一次，而不是每个错过的时间间隔触发一次。
* 开始新对话会清除所有会话范围的任务。使用 `claude --resume` 或 `claude --continue` 恢复会带回未过期的任务：创建后七天内的循环任务，以及计划时间尚未到达的一次性任务。后台 Bash 和监控任务在恢复时永远不会被恢复。

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

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