OpenClaw Cron 系统详解与 Unix Cron 对比

基于配置提醒系统的实践经验整理。

---

一、本质定位不同

	Unix Cron	OpenClaw Cron
定位	操作系统级任务调度	AI 助手环境任务调度
执行对象	Shell 命令	AI 会话 / 系统事件
使用者	系统管理员、开发者	AI 助手、终端用户
通知方式	邮件 / 日志	Telegram、Discord 等即时消息

Unix Cron 是"让机器定时做事"；OpenClaw Cron 是"让 AI 助手定时思考并通知你"。

---

二、调度类型对比

Unix Cron 只有一种：cron 表达式，时区跟随系统。

OpenClaw Cron 支持三种：

kind: "cron"   → 标准 cron 表达式，支持指定时区
kind: "at"     → 一次性执行，ISO 时间戳
kind: "every"  → 按毫秒间隔重复

实际例子：

// 每周一至周五 CST 早上 9 点
{ "kind": "cron", "expr": "0 9 * * 1-5", "tz": "America/Chicago" }

// 一次性：2026-03-10 下午 11 点 UTC
{ "kind": "at", "at": "2026-03-10T17:00:00.000Z" }

---

三、执行模式：最核心的区别

Unix Cron 执行的是 shell 命令，OpenClaw 执行的是 payload，有两种：

agentTurn — 启动独立 AI 会话处理任务

{
  "sessionTarget": "isolated",
  "payload": {
    "kind": "agentTurn",
    "message": "检查项目进度并发送提醒"
  }
}

• AI 会真正"思考"这条消息并生成回复
• 适合需要智能判断、动态生成内容的场景
• 结果通过 delivery 发送出去

systemEvent — 在主会话注入系统消息

{
  "sessionTarget": "main",
  "payload": {
    "kind": "systemEvent",
    "text": "提醒：现在是早上 9 点，检查今日计划"
  }
}

• 直接往主会话塞一条系统消息，不启动独立 AI
• 适合简单通知，无需 AI 处理

---

四、交付系统

Unix Cron 的"交付"就是邮件或标准输出。

OpenClaw 的 delivery 更灵活：

"delivery": {
  "mode": "announce",      // announce | webhook | none
  "channel": "telegram",
  "to": "7650307948"
}

mode	作用
announce	发消息到指定频道/用户
webhook	HTTP POST 到指定 URL
none	静默执行，不发任何通知

---

五、任务生命周期管理

Unix Cron 无状态——任务永远在那，要删就编辑 crontab。

OpenClaw 是有状态的：

{
  "enabled": true,           // 可随时启用/禁用，不用删除
  "deleteAfterRun": true,    // 一次性任务执行后自动删除
  "state": {
    "nextRunAtMs": 1773064800000  // 记录下次执行时间
  }
}

管理命令：

cron(action="list")               // 查看所有任务
cron(action="status")             // 查看调度器状态
cron(action="run", jobId="xxx")   // 手动立即触发
cron(action="update", jobId, patch)  // 修改任务
cron(action="remove", jobId)      // 删除任务
cron(action="runs", jobId)        // 查看历史执行记录

---

六、实战案例：项目提醒系统

Unix Cron 做同样的事，需要：

1. 写多个 shell 脚本（调用 Telegram Bot API）
2. 处理时区转换逻辑
3. 手动实现一次性任务后自动删除

OpenClaw Cron 实际配置（多个任务，全部 JSON 声明式）：

1. 每日提醒     → cron "0 9 * * 1-5"，长期运行
2. Prelim 邮件  → at 今天 20:00 UTC，执行后自动删除
3. 紧急任务提醒 → at 指定时间 UTC，执行后自动删除

所有提醒通过 Telegram 推送，AI 生成提醒文本，无需写任何脚本。

---

七、适用场景选择

用 OpenClaw Cron 当：

• 需要推送到 Telegram / Discord
• 提醒内容需要 AI 动态生成
• 一次性提醒（比如项目节点）
• 个人时间管理、项目进度跟踪

继续用 Unix Cron 当：

• 系统级任务（日志轮转、备份、服务重启）
• 大批量、高频率任务
• 不需要任何通知，只是跑脚本
• 离线环境，不依赖网络

---

八、存储位置

/home/node/.openclaw/cron/jobs.json

持久化 JSON，网关重启后任务不丢失。