OpenClaw 自动化学习笔记：Cron Jobs 与 Heartbeat

在学习 OpenClaw 的过程中，自动化任务的调度是核心功能之一。OpenClaw 提供了两种主要的调度机制：Cron Jobs 和 Heartbeat。

1. Cron Jobs (Gateway 调度器)

OpenClaw 的 Cron 系统是一个内置在 Gateway 中的调度器，用于自动化 Agent 任务。它负责持久化任务、在预定时间唤醒 Agent。

核心特性

运行位置: 在 Gateway 进程内部运行。
持久化:
- 任务库: 存储在 ~/.openclaw/cron/jobs.json，重启不会丢失计划。
- 运行历史 (History): 存储在 ~/.openclaw/cron/runs/<jobId>.jsonl，会自动清理。
唤醒模式: 支持立即唤醒 (wake now) 或随心跳唤醒 (next heartbeat)。

📝 立即唤醒 (wake now) 的具体含义：

触发机制：触发一个立即执行的心跳运行 (immediate heartbeat run)，无需等待正常的 30 分钟间隔。
主会话任务：强制启动心跳逻辑以立即处理该系统事件。
隔离会话任务：决定任务完成后的“摘要消息”何时发送给用户（立即触发心跳发送，而非等待）。
核心作用：让事件立即触发心跳运行，而不是排队等待。

两种执行风格

主会话 (Main session):
- 机制: 排队一个系统事件 (systemEvent)。
- 特点: 在下一次心跳时结合主上下文运行。适合需要感知当前聊天背景的提醒。
隔离会话 (Isolated):
- 机制: 运行专用的 Agent 轮次 (agentTurn)。
- 特点: 全新的会话 ID，不干扰主聊天记录。支持将结果交付（Announce）到 Slack、Telegram 等外部频道。

调度类型 (Schedules)

at: 一次性时间戳 (ISO 8601)。
every: 固定毫秒间隔。
cron: 5 字段 Cron 表达式（支持 IANA 时区）。

📝 容错机制 (指数退避)：如果循环任务连续失败，系统会应用指数退避策略，重试间隔依次为：30s -> 1m -> 5m -> 15m -> 60m。一旦任务运行成功，退避计数器会自动重置。注意，一次性任务 (at) 运行失败后不会自动重试。

使用cli管理cron

📝 小技巧：其实大部分时候不用亲自敲命令行，直接“吩咐” Agent 帮你搞定 Cron 管理就行了。

底层原理：Agent 并不是在后台敲 CLI 命令，而是通过发送规范的 JSON 数据调用 OpenClaw 的 cron.* 工具接口。
格式差异：CLI 支持 20m 这种人类友好格式，但 Agent 工具调用必须使用 ISO 8601 字符串（针对 at）或毫秒数（针对 every）。

cli示例：

创建一个一次性提醒，验证是否存在，并立即运行：

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>

调度一个带有交付功能的循环隔离任务：

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"

Agent工具调用和JSON Schema

Agent 内部工具 (cron.*)： Agent 拥有诸如 cron.add、cron.update、cron.list 等“技能”。当它决定帮你操作 Cron 时，它会构造一个符合 JSON Schema 的对象。例如：它会发出一个 cron.add 调用，参数里包含 schedule、payload 等字段。
RPC/API 调用：对于开发者或高级用户，这些 JSON 结构也是通过远程过程调用 (RPC) 或直接与 Gateway 交互时使用的标准格式。

JSON Schema示例:

cron.add 参数 (一次性、主会话)

{
  "name": "Reminder",
  "schedule": { "kind": "at", "at": "2026-02-01T16:00:00Z" },
  "sessionTarget": "main",
  "wakeMode": "now",
  "payload": { "kind": "systemEvent", "text": "Reminder text" },
  "deleteAfterRun": true
}

cron.add 参数 (循环、隔离)

{
  "name": "Morning brief",
  "schedule": { "kind": "cron", "expr": "0 7 * * *", "tz": "America/Los_Angeles" },
  "sessionTarget": "isolated",
  "payload": { "kind": "agentTurn", "message": "Summarize updates." },
  "delivery": { "mode": "announce", "channel": "slack", "to": "channel:C1234567890" }
}

Gateway 系统配置

Cron 的全局行为通过 Gateway 的配置文件（如 ~/.openclaw/config.json5）进行管理：

{
  cron: {
    enabled: true,           // 是否启用 Cron 系统 (默认 true)
    store: "~/.openclaw/cron/jobs.json", // 任务持久化路径
    maxConcurrentRuns: 1,    // 最大并发运行任务数 (默认 1)
  },
}

除了修改配置文件，也可以通过环境变量 OPENCLAW_SKIP_CRON=1 快速禁用整个 Cron 系统。

2. Heartbeat (心跳)：周期性感知

Heartbeat 在主会话中以固定间隔（默认 30 分钟）运行。它专为 Agent 检查事项并发现重要信息而设计。

何时使用 Heartbeat

多个周期性检查：与其使用 5 个独立的 Cron 任务分别检查收件箱、日历、天气、通知和项目状态，不如通过单个 Heartbeat 批量处理。
上下文感知决策：Agent 拥有完整的主会话上下文，因此可以智能判断哪些事项紧急，哪些可以稍后处理。
对话连续性：Heartbeat 共享同一个会话，Agent 记得最近的对话并能自然地跟进。
低开销监控：一个 Heartbeat 即可替代许多细小的轮询任务。

优势

批量检查: 可以在一轮对话中同时检查邮件、日历和通知。
上下文感知: Agent 了解你当前的工作背景，能智能判断优先级。
成本优化: 无论检查多少项，通常只消耗一次 Agent 轮次。减少了 API 调用：单个 Heartbeat 比 5 个隔离的 Cron 任务更便宜。
智能抑制: 如果没有重要事项，Agent 响应 HEARTBEAT_OK，不发送任何消息，不干扰用户。
自然时序：执行时间会根据队列负载略有漂移，这对大多数监控任务来说是可以接受的。

实践：HEARTBEAT.md

文件路径： ~/.openclaw/workspace/HEARTBEAT.md

创建一个 HEARTBEAT.md 任务清单，Agent 每次心跳都会读取：

- 检查邮件中的紧急消息
- 查看未来 2 小时的日历事件
- 如果闲置超过 8 小时，发送简短问候

系统配置 (Heartbeat)

Heartbeat 的行为同样在 ~/.openclaw/config.json5 中配置：

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m", // 执行间隔
        target: "last", // 警报发送位置 (last 表示最后一次交流的频道)
        activeHours: { start: "08:00", end: "22:00" }, // 可选：仅在活跃时间运行
      },
    },
  },
}

3. Cron vs Heartbeat: 深度对比

快速决策指南

使用场景	推荐方式	原因
每 30 分钟检查一次收件箱	Heartbeat	与其他检查合并，具备上下文感知能力
每天早上 9 点准时发送报告	Cron (隔离)	需要精确的时间点
监控日历中的即将发生的事件	Heartbeat	自然契合周期性感知需求
运行每周深度分析	Cron (隔离)	独立任务，可使用不同的模型
20 分钟后提醒我	Cron (主会话, `--at`)	具备精确时间的一次性提醒
后台项目健康检查	Heartbeat	附加在现有的周期中运行

决策流程

需要精确时间吗？ -> 是：使用 Cron。
需要与主会话隔离吗？ -> 是：使用 Cron (隔离)。
可以批量合并吗？ -> 是：使用 Heartbeat。
需要不同的模型吗？ -> 是：使用 Cron (隔离)。

成本对比

Heartbeat: 每次运行按一次轮次计费，建议合并同类项。
Cron (主会话): 附加到现有心跳，无额外轮次开销。
Cron (隔离): 每个任务都是一次完整的 Agent 轮次开销。

4. 补充：Lobster 与确定性工作流

Lobster 是 OpenClaw 的工作流引擎，用于处理复杂的、需要多步执行的任务。

定位：调度器（Cron/Heartbeat）决定**“何时”开始，Lobster 决定开始后“具体怎么做”**。
两大功能：
- 人工审批 (Approval Gates)：敏感操作（如发邮件、删数据）会暂停执行，并生成一个唯一的恢复令牌 (resumeToken)。任务进入挂起状态，直到用户通过该令牌输入 approve 指令后，系统才会根据令牌找回先前的状态并继续执行下一步。
- 断点续传 (Resumable)：任务中断后可从当前步骤恢复，无需从头开始。
与调度器的协作：
- Heartbeat/Cron = 闹钟（唤醒系统）。
- Lobster = 标准操作程序（SOP），引导 Agent 按照 1、2、3 步确定性地完成工作。

1. Cron Jobs (Gateway 调度器)

核心特性

两种执行风格

调度类型 (Schedules)

使用cli管理cron

Agent工具调用和JSON Schema

Gateway 系统配置

2. Heartbeat (心跳)：周期性感知

何时使用 Heartbeat

优势

实践：HEARTBEAT.md

系统配置 (Heartbeat)

3. Cron vs Heartbeat: 深度对比

快速决策指南

决策流程

成本对比

4. 补充：Lobster 与确定性工作流

参考资料