Cron 定时任务

Gateway 内置调度器，让 Agent 按计划自动执行任务。任务持久化存储，Gateway 重启不丢失。

核心概念

每个 Cron 任务 = 何时运行 + 怎么运行：

配置项	选项	说明
调度类型	at（一次性）、every（固定间隔）、cron（表达式）	何时运行
执行模式	main（主会话）、isolated（独立会话）	在哪个 Session 里运行
负载类型	systemEvent（系统事件）、agentTurn（Agent 对话）	运行什么
投递方式	announce（频道推送）、webhook（HTTP POST）、none（仅内部）	结果去哪里

快速上手

一次性提醒（20 分钟后提醒）：

openclaw cron add \
  --name "提交报告提醒" \
  --at "20m" \
  --session main \
  --system-event "提醒：提交费用报告" \
  --wake now

每日定时摘要：

openclaw cron add \
  --name "每日早报" \
  --cron "0 7 * * *" \
  --tz "Asia/Shanghai" \
  --session isolated \
  --message "总结今天的重要信息和待办事项。" \
  --announce \
  --channel telegram \
  --to "+15551234567"

查询和管理：

openclaw cron list              # 列出所有任务
openclaw cron runs --id <id>    # 查看运行历史
openclaw cron run <id>          # 立即手动触发
openclaw cron edit <id> --enabled false  # 禁用任务

调度类型详解

一次性（at）

--at "2026-03-15T10:00:00Z"   # ISO 8601，无时区时按 UTC
--at "20m"                    # 从现在起 20 分钟后
--delete-after-run            # 成功后自动删除（一次性默认如此）

固定间隔（every）

以毫秒为单位，适合精确间隔：

{ "schedule": { "kind": "every", "everyMs": 3600000 } }  // 每小时

Cron 表达式（cron）

支持 5 字段（分 时 日 月 周）或 6 字段（含秒）：

--cron "0 7 * * *"              # 每天 7:00
--cron "0 9 * * 1"              # 每周一 9:00
--cron "*/30 * * * *"           # 每 30 分钟
--tz "Asia/Shanghai"            # 指定时区（否则用 Gateway 主机时区）

提示：每整点触发的任务（如 0 * * * *）会被自动随机错开最多 5 分钟，避免大量 Gateway 同时负载。用 --exact 强制精确时间。

执行模式

主会话（main session）

任务触发一个系统事件，由下次心跳处理，运行在主对话上下文中：

• 最适合：需要访问当天主会话上下文的任务
• 负载类型：必须用 systemEvent

--session main --system-event "提醒：检查日历"

独立会话（isolated session）

在独立 Session（cron:<jobId>）中运行专属 Agent 轮次：

• 每次运行都是全新 Session（无历史延续）
• 适合：定期报告、后台检查、不需要主会话历史的任务
• 负载类型：必须用 agentTurn

--session isolated --message "今日任务摘要"

结果投递

投递到渠道（announce）

--announce \
--channel telegram \
--to "+15551234567"

投递目标格式：

• Slack/Discord：channel:<id>、user:<id>
• Telegram 话题：-1001234567890:topic:123

投递到 Webhook（webhook）

{
  "delivery": {
    "mode": "webhook",
    "to": "https://your-server.com/cron-result"
  }
}

若设置 cron.webhookToken，请求头会加 Authorization: Bearer <token>。

不投递（none）

仅 Gateway 内部运行，不推送给任何渠道：

--announce  # 去掉此参数，或在 JSON 中设置 delivery.mode: "none"

模型与思考模式覆盖

孤立任务可以指定专用模型：

openclaw cron add \
  --name "周报分析" \
  --cron "0 6 * * 1" \
  --session isolated \
  --message "生成本周项目进展周报。" \
  --model "opus" \
  --thinking high \
  --announce

JSON 工具调用格式

Agent 可通过 cron 工具直接创建任务：

{
  "name": "每日提醒",
  "schedule": { "kind": "at", "at": "2026-03-15T10:00:00Z" },
  "sessionTarget": "main",
  "wakeMode": "now",
  "payload": { "kind": "systemEvent", "text": "提醒文字" },
  "deleteAfterRun": true
}

{
  "name": "早报",
  "schedule": { "kind": "cron", "expr": "0 7 * * *", "tz": "Asia/Shanghai" },
  "sessionTarget": "isolated",
  "payload": { "kind": "agentTurn", "message": "今日摘要", "lightContext": true },
  "delivery": { "mode": "announce", "channel": "telegram", "to": "+15551234567", "bestEffort": true }
}

重试策略

任务类型	瞬时错误（速率限制、网络超时等）	永久错误（认证失败等）
一次性（at）	重试 3 次，指数退避（30s→1m→5m）	立即禁用
周期性（cron/every）	指数退避（30s→1m→5m→15m→60m）	保持启用，退避后重试

存储与维护

• 任务存储：~/.openclaw/cron/jobs.json
• 运行历史：~/.openclaw/cron/runs/<jobId>.jsonl
• 独立运行会话默认保留 24 小时（cron.sessionRetention）

{
  cron: {
    enabled: true,
    sessionRetention: "24h",     // 运行会话保留时长
    runLog: {
      maxBytes: "2mb",           // 日志文件大小上限
      keepLines: 2000,           // 修剪时保留最近 N 行
    },
    maxConcurrentRuns: 1,        // 最大并发运行数
  },
}

常见问题

任务没有运行：

• 检查 cron.enabled 是否为 true
• 确认 Gateway 持续运行（Cron 在 Gateway 进程内运行）
• 检查时区配置是否正确

任务重复失败后越来越晚：

• 这是正常的指数退避行为，下次成功后自动重置