Claude Code 定时调度 (Cron) 功能

官方文档: https://code.claude.com/docs/en/scheduled-tasks.md 工具参考: https://code.claude.com/docs/en/tools-reference.md 文档索引: https://code.claude.com/docs/en/claude_code_docs_map.md

概述

Claude Code 原生支持定时调度，通过 CronCreate / CronList / CronDelete 三个原生工具实现。

核心工具

工具	用途
CronCreate	创建定时任务。接受 5-field cron 表达式 + prompt + 是否循环
CronList	列出当前所有定时任务及其 ID、调度、prompt
CronDelete	通过 8 位 ID 取消指定任务

Cron 表达式格式

标准 5-field: minute hour day-of-month month day-of-week

表达式	含义
*/5 * * * *	每 5 分钟
*/3 * * * *	每 3 分钟
*/30 * * * *	每 30 分钟
0 * * * *	每小时整点
0 9 * * *	每天早 9 点
0 9 * * 1-5	工作日早 9 点

调度方式对比

	Cloud	Desktop /schedule	/loop (CLI)
运行在	Anthropic 云端	本地机器	本地机器
需要机器开启	否	是	是
需要打开会话	否	否	是
跨重启持久化	是	是	否 (session-scoped)
访问本地文件	否	是	是
最小间隔	1 小时	1 分钟	1 分钟

关键限制

1. Session-scoped: /loop 和 CronCreate 创建的任务仅在 Claude Code 运行且空闲时触发。关闭终端或退出会话后，所有任务取消。
2. 3 天过期: 循环任务自动在 3 天后过期，防止无限运行。
3. 最多 50 个: 每个会话最多 50 个并发定时任务。
4. 不补发: 如果任务触发时 Claude 正在忙，等空闲后只触发一次，不补发错过的。
5. Jitter: 循环任务有最多 10% 的延迟抖动（上限 15 分钟）。

LemonBoss 持久化方案

由于 CronCreate 是 session-scoped，我们使用 cron.json + 会话启动自动注入 来实现持久化：

cron.json 格式

[
  {
    "schedule": "*/5 * * * *",
    "prompt": "读取 plan.md 检查已分发任务进度",
    "recurring": true,
    "enabled": true
  }
]

工作流程

1. Agent 目录下有 cron.json 定义期望的定时任务
2. 每次新建 ACP 会话时，后端自动读取 cron.json
3. 在第一条 system prompt 中注入 CronCreate 恢复指令
4. Agent 调用 CronCreate 重建所有定时任务

文件位置

• 文档: docs/claude-code-cron.md (本文件)
• 模板: packages/agent-core/AgentScaffold.js (_defaultCronJson)
• 注入点: server/routes/agent-chat.js (buildPrompt)
• Agent 配置: data/agents/{agent-id}/cron.json