Documentation Index
Fetch the complete documentation index at: https://mintlify.com/zhcndoc/openclaw/llms.txt
Use this file to discover all available pages before exploring further.
Cron 作业（网关调度器）
Cron 与心跳的区别？ 请参见 Cron vs Heartbeat 以获取何时使用的指导。
Cron 是网关内置的调度器。它会持久化作业，准时唤醒代理，并且可以选择将输出发送回聊天。
如果你想要实现“每天早上运行”或“20 分钟后唤醒代理”，cron 是实现的机制。
快速开始
创建一次性提醒
openclaw cron add \
--name "Reminder" \
--at "2026-02-01T16:00:00Z" \
--session main \
--system-event "Reminder: check the cron docs draft" \
--wake now \
--delete-after-run
查看作业列表
手动运行作业
openclaw cron run <job-id>
查看运行历史
openclaw cron runs --id <job-id> --limit 20
周期性作业示例
每天早上 7 点运行
openclaw cron add \
--name "Morning brief" \
--cron "0 7 * * *" \
--tz "America/Los_Angeles" \
--session isolated \
--message "Summarize overnight updates." \
--announce \
--channel slack \
--to "channel:C1234567890"
每小时运行
openclaw cron add \
--name "Hourly check" \
--every "1h" \
--session isolated \
--message "Check system status" \
--announce
作业类型
Cron 支持两种作业类型：
- 主会话作业 (
sessionTarget: "main"): 在主会话上下文中运行，使用心跳提示
- 隔离作业 (
sessionTarget: "isolated"): 在独立的 cron:<jobId> 会话中运行
调度方式
Cron 支持三种调度方式：
-
at: 一次性时间点，使用 ISO 8601 格式
--at "2026-02-01T16:00:00Z"
--at "20m" # 20 分钟后
-
every: 固定间隔
--every "1h" # 每小时
--every "30m" # 每 30 分钟
-
cron: Cron 表达式 (5 字段或 6 字段)
--cron "0 7 * * *" # 每天 7:00
--cron "0 */2 * * *" # 每 2 小时
--cron "0 0 * * 1" # 每周一午夜
负载类型
- 系统事件 (
payload.kind: "systemEvent"): 仅主会话，路由到心跳提示
- 代理回合 (
payload.kind: "agentTurn"): 仅隔离会话，运行专用代理回合
交付模式
隔离作业支持三种交付模式：
announce (公告)
将摘要发送至目标频道，并同时向主会话发布简要摘要。
openclaw cron add \
--name "Daily report" \
--cron "0 9 * * *" \
--session isolated \
--message "Generate daily report" \
--announce \
--channel whatsapp \
--to "+15551234567"
webhook
将完成事件 POST 到指定 URL。
openclaw cron add \
--name "API callback" \
--every "5m" \
--session isolated \
--message "Check status" \
--webhook "https://example.com/webhook"
{
cron: {
webhookToken: "your-secret-token"
}
}
none
仅内部运行，无交付，无主会话摘要。
openclaw cron add \
--name "Background task" \
--every "10m" \
--session isolated \
--message "Background processing" \
--no-announce
模型和思考级别覆盖
隔离作业可以覆盖模型和思考级别：
openclaw cron add \
--name "Deep analysis" \
--cron "0 6 * * 1" \
--session isolated \
--message "Weekly deep analysis" \
--model "opus" \
--thinking high \
--announce
代理选择
在多代理环境中，可以将作业绑定给特定代理：
openclaw cron add \
--name "Ops sweep" \
--cron "0 6 * * *" \
--session isolated \
--message "Check ops queue" \
--agent ops
轻量级引导上下文
适用于不需要工作区引导文件注入的定时杂务：
openclaw cron add \
--name "Simple check" \
--every "5m" \
--session isolated \
--message "Quick status check" \
--light-context
{
cron: {
enabled: true,
store: "~/.openclaw/cron/jobs.json",
maxConcurrentRuns: 1,
retry: {
maxAttempts: 3,
backoffMs: [60000, 120000, 300000]
},
webhookToken: "your-secret-token",
sessionRetention: "24h",
runLog: {
maxBytes: "2mb",
keepLines: 2000
}
}
}
重试策略
一次性作业
- 临时错误：最多重试 3 次，使用指数退避
- 永久错误：立即禁用作业
- 成功或跳过：禁用作业（如果
deleteAfterRun: true 则删除）
周期性作业
- 任何错误：应用指数退避后再执行下次计划
- 作业保持启用状态
- 下次成功执行后重置退避计数
存储与历史
- 作业存储：
~/.openclaw/cron/jobs.json
- 运行历史：
~/.openclaw/cron/runs/<jobId>.jsonl
- 隔离 cron 运行会话：存储于
sessions.json，由 cron.sessionRetention 配置修剪
CLI 命令参考
列出作业
openclaw cron list
openclaw cron list --json
添加作业
openclaw cron add --name <name> [options]
--at <time>: 一次性时间点--every <duration>: 固定间隔--cron <expression>: Cron 表达式--tz <timezone>: 时区--session <main|isolated>: 会话类型--system-event <text>: 系统事件文本--message <text>: 代理消息--announce: 启用公告交付--channel <channel>: 目标频道--to <target>: 目标接收者--webhook <url>: Webhook URL--model <model>: 模型覆盖--thinking <level>: 思考级别--agent <id>: 代理 ID--delete-after-run: 成功后删除
编辑作业
openclaw cron edit <jobId> [options]
运行作业
openclaw cron run <jobId>
openclaw cron run <jobId> --due # 仅在到期时运行
启用/禁用作业
openclaw cron enable <jobId>
openclaw cron disable <jobId>
删除作业
openclaw cron remove <jobId>
查看运行历史
openclaw cron runs --id <jobId> --limit 20
故障排查
作业不运行
- 检查 cron 是否启用：
cron.enabled 配置和环境变量 OPENCLAW_SKIP_CRON
- 确认网关持续运行
- 对
cron 计划，确认时区设置正确
周期性作业失败后持续延迟
- OpenClaw 对周期性作业连续错误应用指数退避重试
- 下次成功运行后重置退避
Telegram 发送到错误位置
- 论坛主题推荐使用明确格式：
-100…:topic:<id>
相关文档
