Skip to main content

​
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 list

​
手动运行作业

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"
配置 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>

​
相关文档