主题
定时任务与 /loop
用 /loop 和 cron 调度工具在一个 Claude Code 会话内按间隔重复运行 prompt、轮询状态或设置一次性提醒。
对你意味着什么
你装了 ralph-loop，正是循环/定时这一类的工具。三种调度按"要不要开机/开会话"分：
| 方式 | 跑在哪 | 前提 | 最小间隔 |
|---|---|---|---|
/loop（会话内） | 本机 | 开机 + 会话开着 | 1 分钟 |
| Desktop 定时任务 | 本机 | 开机（不用开会话） | 1 分钟 |
Routines（/schedule，云端） | Anthropic 云 | 都不用 | 1 小时 |
对你对口的用法
- 你那些耗时技能（
/qa、/cso、/health）想定期跑：本机用/loop，要关机也跑就用云端/schedule。 - 注意 TTL：
/loop间隔别卡 5 分钟边缘——<270s保缓存，或1200s+接受重算（见「提示词缓存」节）。 - 关掉本机 cron：
CLAUDE_CODE_DISABLE_CRON=1。
官方文档要点
以下为按官方文档整理的系统性参考。
是什么
Scheduled tasks（定时任务）让 Claude 在一个会话内自动按间隔重复运行某个 prompt，典型用途包括轮询部署、盯 PR、回看长时间构建、或在会话内稍后提醒自己。它是 session-scoped（会话级）的：任务只活在当前对话里，开新对话即停止。核心入口是 /loop 这个 bundled skill，底层调度由 CronCreate / CronList / CronDelete 三个工具实现。要求 Claude Code v2.1.72 或更高版本（用 claude --version 查看）。
怎么工作
- 调度器每秒检查一次到期任务，并以 low priority（低优先级）入队。
- 定时 prompt 在你的两个 turn 之间触发（fires between your turns），不会在 Claude 正在回复时打断；若到期时 Claude 正忙，prompt 等到当前 turn 结束再执行。
- /loop 的行为由你提供的内容决定：给『间隔+prompt』则按固定 cron 调度；只给『prompt』则每轮由 Claude 动态选间隔；只给间隔或什么都不给，则运行内置 maintenance prompt 或你的 loop.md。
- 给固定间隔时，Claude 把它转成 cron 表达式，调度任务，并回报节奏和 job ID。
- 动态间隔（self-paced）模式：每轮后 Claude 在 1 分钟到 1 小时之间挑一个延迟——构建/PR 活跃时等得短，没事时等得长——并在每轮末尾打印所选延迟及原因。动态调度时 Claude 可能直接用 Monitor tool（后台跑脚本、逐行回流输出），比按间隔重跑 prompt 更省 token、更灵敏。
- 所有时间按本地时区（local timezone）解释，例如 0 9 * * * 指运行机器所在地的 9am，不是 UTC。
- Jitter（抖动）：调度器按任务 ID 派生一个确定性偏移，避免所有会话同一墙钟时刻打 API。同一任务总得到同一偏移。
- Seven-day expiry（7 天过期）：recurring 任务创建 7 天后自动过期，最后触发一次再自删。
- 会话级恢复：用 claude --resume / --continue 可恢复未过期的任务（创建在 7 天内的 recurring 任务、触发时间未到的 one-shot 任务）；但 background Bash 和 monitor 任务永不在 resume 时恢复。
怎么配置 / 用法
命令与语法示例：
固定间隔：/loop 5m check if the deployment finished and tell me what happened（间隔可在前作裸 token 如 30m，也可在后作子句如 every 2 hours；单位 s/m/h/d）。 动态间隔：/loop check whether CI passed and address any review comments。 内置 maintenance prompt：裸 /loop（动态间隔运行）；/loop 15m 固定间隔运行。 把另一个命令当 prompt：/loop 20m /review-pr 1234。 一次性提醒（自然语言，不用 /loop）：remind me at 3pm to push the release branch 或 in 45 minutes, check whether the integration tests passed。 管理任务（自然语言）：what scheduled tasks do I have? / cancel the deploy check job。
loop.md 默认 prompt 文件（替换内置 maintenance prompt，仅作为裸 /loop 的单一默认 prompt；命令行带 prompt 时被忽略）：
- 项目级
.claude/loop.md（两者都存在时优先） - 用户级
~/.claude/loop.md（适用于未自定义的任意项目） 纯 Markdown，无固定结构，像直接键入 /loop prompt 那样写。编辑下一轮生效。超过 25,000 bytes 的内容会被截断。
底层工具：CronCreate（接受 5 字段 cron 表达式 + 要跑的 prompt + 是否 recurs/fires once）、CronList、CronDelete（按 ID 取消）。
cron 示例：*/5 * * * *（每 5 分钟）、0 9 * * 1-5（工作日 9am 本地）、30 14 15 3 *（3月15日 2:30pm 本地）。
禁用：环境变量 CLAUDE_CODE_DISABLE_CRON=1。
什么时候用
- 用 /loop 做会话内的快速轮询：盯部署、babysit 一个 PR、回看长时间构建、会话内稍后提醒自己。
- 给固定间隔（/loop 5m ...）当你要稳定可预测的节奏。
- 省略间隔（/loop <prompt>）当任务忙闲不均、想让 Claude 自适应等待——活跃时勤查、安静时少查。
- 用一次性自然语言提醒（remind me at 3pm ...）做单次定时，任务运行后自删。
- 别用 /loop 当机器/会话不能一直开着：它只在 Claude Code 运行且 idle 时触发——改用 Routines（Anthropic 云端，不需机器开机/会话打开）、Desktop scheduled tasks（本机但不需会话打开）、或 GitHub Actions 的 schedule trigger。
- 想对事件即时反应而非轮询，用 Channels（CI 直接把失败推进会话）；想一直工作到满足条件而非按间隔，用 /goal。
- Routines 最小间隔 1 小时；Desktop 与 /loop 最小间隔 1 分钟。需要更短或本地文件访问时据此选择。
限制 / 坑
- 要求 Claude Code v2.1.72 或更高版本。
- 任务只在 Claude Code 运行且 idle 时触发；关闭终端或会话退出即停止触发。
- 无 catch-up 补跑：如果到期时 Claude 正忙于长请求，变 idle 后只补触发一次，不会按错过的间隔逐次补。
- 开新对话会清空所有会话级任务；只有 --resume/--continue 能恢复未过期的任务。background Bash 和 monitor 任务永不在 resume 时恢复。
- recurring 任务创建 7 天后自动过期（最后触发一次再自删）；要更久需在过期前 cancel 并重建，或改用 Routines/Desktop scheduled tasks。
- 一个会话最多同时持有 50 个 scheduled tasks。
- loop.md 超过 25,000 bytes 的内容被截断。
- Jitter 偏差：recurring 任务最多在计划时间后 30 分钟触发（对高于每小时频率的任务，最多为间隔的一半）；one-shot 排在整点/半点的最多提前 90 秒。要精确计时请避开 :00 和 :30，例如用 3 9 * * * 而非 0 9 * * *。
- cron 不支持扩展语法 L、W、?，以及 MON/JAN 这类名称别名；只支持标准 5 字段。
- Esc 只停正在等待下一轮的 /loop（清掉待触发的 wakeup）；通过『直接让 Claude 调度』创建的任务不受 Esc 影响，需删除才停。
- 在 Bedrock、Vertex AI、Microsoft Foundry 上：无间隔的 prompt 改为固定 10 分钟调度；/loop 无 prompt 时打印 usage message 而非运行 maintenance prompt；loop.md 不被读取。
- Seconds 单位向上取整到最近的分钟（cron 只有 1 分钟粒度）；不能整除成干净 cron 步长的间隔（如 7m、90m）会被取整到最近可行间隔，Claude 会告知所选值。
硬事实速查（29 条）
- 最低版本要求：Claude Code v2.1.72 或更高（claude --version 查看）。
- 任务是 session-scoped：开新对话即停止；--resume/--continue 恢复未过期任务。
- /loop 是一个 bundled skill。
- /loop 间隔单位：s（秒）、m（分）、h（小时）、d（天）。
- 间隔位置：可前置裸 token（如 30m）或后置子句（如 every 2 hours）。
- 动态间隔范围：每轮在 1 分钟到 1 小时之间选延迟。
- 动态调度可能直接使用 Monitor tool（后台跑脚本逐行回流）。
- loop.md 路径：项目级 .claude/loop.md（优先）、用户级 ~/.claude/loop.md。
- loop.md 截断阈值：25,000 bytes。
- loop.md 编辑下一轮生效。
- 底层三工具：CronCreate、CronList、CronDelete。
- CronCreate 接受标准 5 字段 cron：minute hour day-of-month month day-of-week。
- cron 字段支持：通配 *、单值 5、步进 */15、范围 1-5、逗号列表 1,15,30。
- day-of-week：0 或 7 表示周日，6 表示周六。
- 不支持的 cron 扩展：L、W、?、名称别名 MON/JAN 等。
- day-of-month 与 day-of-week 同时受限时，任一匹配即匹配（vixie-cron 语义）。
- 每个 scheduled task 有 8 字符 ID，传给 CronDelete。
- 单会话上限：最多 50 个 scheduled tasks。
- 调度器每秒检查一次到期任务，low priority 入队。
- 时间按本地时区解释，0 9 * * * 指本地 9am 非 UTC。
- Jitter：recurring 最多延后 30 分钟（高于每小时频率则为间隔一半）；one-shot 整点/半点最多提前 90 秒；偏移由 task ID 派生且确定性。
- Seven-day expiry：recurring 任务创建 7 天后过期，最后触发一次再自删；动态 /loop 同样 7 天后结束（但不适用 jitter 规则）。
- 停 /loop：Esc 清待触发 wakeup；自然语言创建的任务不受 Esc 影响。
- 一次性提醒用自然语言（如 remind me at 3pm ...），单次触发后自删。
- 禁用调度器：环境变量 CLAUDE_CODE_DISABLE_CRON=1（cron 工具与 /loop 不可用，已排程任务停止触发）。
- 三种调度方式最小间隔：Cloud/Routines 1 小时、Desktop 1 分钟、/loop 1 分钟。
- Bedrock/Vertex AI/Microsoft Foundry 特例：无间隔 prompt 改 10 分钟固定调度；/loop 无 prompt 打印 usage；loop.md 不读取。
- 无 catch-up：错过的触发只在变 idle 后补一次，不逐次补。
- background Bash 和 monitor 任务永不在 resume 时恢复。