OpenClaw Cron Setup — OpenClaw 定时任务设置

OpenClaw Cron Jobs 配置指南 Cron 是 Gateway 内置的调度器，持久化存储任务，在指定时间唤醒 agent 执行，并可选择将结果投递到聊天频道。

核心概念 两种执行模式 模式 | 用途 | payload 类型 ---|---|--- main (主会话) | 系统事件，融入正常心跳流程 | systemEvent isolated (独立会话) | 后台任务，不污染主会话历史 | agentTurn

三种调度类型 类型 | 字段 | 示例 ---|---|--- 一次性 | schedule.kind: "at" | 2026-03-04T10:00:00Z 或 20m (相对时间) 固定间隔 | schedule.kind: "every" | everyMs: 3600000 (1 小时) Cron 表达式 | schedule.kind: "cron" | expr: "0 7 " (每天 7 点)

快速开始

• 创建一次性提醒（主会话）

openclaw cron add \
  --name "提醒事项" \
  --at "20m" \
  --session main \
  --system-event "20 分钟后检查日历" \
  --wake now \
  --delete-after-run

openclaw cron add \
  --name "晨间简报" \
  --cron "0 7   " \
  --tz "Asia/Shanghai" \
  --session isolated \
  --message "总结昨晚的邮件和日历事件" \
  --announce \
  --channel telegram \
  --to "+8613800138000"

• 创建带模型覆盖的深度任务

openclaw cron add \
  --name "周报分析" \
  --cron "0 9   1" \
  --tz "Asia/Shanghai" \
  --session isolated \
  --message "分析本周项目进展" \
  --model "opus" \
  --thinking high \
  --announce \
  --channel whatsapp \
  --to "+8613800138000"

常用命令 # 查看任务列表 openclaw cron list # 手动运行任务 openclaw cron run # 查看运行历史 openclaw cron runs --id --limit 10 # 编辑任务 openclaw cron edit --message "新提示词" # 删除任务 openclaw cron remove

JSON Schema（工具调用） 一次性主会话任务

{
  "name": "提醒",
  "schedule": {
    "kind": "at",
    "at": "2026-03-04T10:00:00Z"
  },
  "sessionTarget": "main",
  "wakeMode": "now",
  "payload": {
    "kind": "systemEvent",
    "text": "提醒内容"
  },
  "deleteAfterRun": true
}

{
  "name": "晨间简报",
  "schedule": {
    "kind": "cron",
    "expr": "0 7   ",
    "tz": "Asia/Shanghai"
  },
  "sessionTarget": "isolated",
  "wakeMode": "next-heartbeat",
  "payload": {
    "kind": "agentTurn",
    "message": "总结隔夜更新"
  },
  "delivery": {
    "mode": "announce",
    "channel": "telegram",
    "to": "+8613800138000",
    "bestEffort": true
  }
}

投递模式（Delivery） 仅适用于 isolated 任务： 模式 | 说明 ---|--- announce | 投递到指定频道，并在主会话发送简短摘要 webhook | POST 到 HTTP 端点 none | 仅内部执行，无投递

省略 delivery 时默认行为：announce 模式

Telegram 话题投递 支持论坛话题（topic）：--to "-1001234567890:topic:123" 推荐：显式话题标记 --to "-1001234567890:123" 简写：数字后缀

配置示例（参考） 当前工作配置示例（~/.openclaw/cron/jobs.json）：

{
  "name": "daily-health-summary",
  "schedule": {
    "kind": "cron",
    "expr": "0 10   ",
    "tz": "Asia/Shanghai"
  },
  "sessionTarget": "isolated",
  "payload": {
    "kind": "agentTurn",
    "message": "从 Bitable 查询健康数据并生成总结"
  },
  "delivery": {
    "mode": "none",
    "channel": "last"
  }
}

故障排查 任务不执行 检查 cron 是否启用：cron.enabled: true（配置中） 检查 Gateway 是否持续运行（cron 在 Gateway 进程内执行） 确认时区设置正确（--tz 参数）

任务反复延迟 连续失败会触发指数退避：30s → 1m → 5m → 15m → 60m 成功执行后退避重置

查看存储位置 任务存储：~/.openclaw/cron/jobs.json 运行历史：~/.openclaw/cron/runs/.jsonl

高级配置 在 ~/.openclaw/config.json 中：

{
  cron: {
    enabled: true,
    sessionRetention: "24h", // 独立会话保留时长
    runLog: {
      maxBytes: "2mb", // 运行日志最大大小
      keepLines: 2000, // 保留行数
    },
  }
}

Cron vs Heartbeat 场景 推荐 精确时间（如"每周一 9 点"） | cron 批量检查（邮箱 + 日历 + 天气） | heartbeat 一次性提醒 | cron 后台自动化（频繁/嘈杂） | cron (isolated) 主会话上下文相关任务 | heartbeat

文档来源：https://docs.openclaw.ai/automation/cron-jobs