Cron vs 心跳 - 调度策略对比
OpenClaw 提供两种不同的调度机制：Cron（定时任务调度器）和 Heartbeat（心跳脉冲）。理解它们的区别和适用场景，是设计可靠自动化工作流的关键。
核心区别
Cron - 精确定时调度
Cron 由 Gateway（网关）管理，在精确的时间点触发 Agent（智能体）执行任务。
- 触发方式：精确时间点或固定间隔
- 管理者：Gateway 进程
- 精度：秒级（6 字段表达式）或分钟级（5 字段表达式）
- 持久化：任务配置持久化存储在
~/.openclaw/cron/ - 独立性：不依赖 Agent 是否在线
Heartbeat - 周期性脉冲
Heartbeat 是 Agent 运行时的周期性脉冲信号，Agent 在每次心跳时检查是否有待处理的事件。
- 触发方式：周期性脉冲，间隔由 Agent 配置决定
- 管理者：Agent 进程自身
- 精度：取决于心跳间隔（通常 5s - 60s）
- 持久化：脉冲本身不持久化，事件队列持久化
- 依赖性：需要 Agent 进程在线运行
对比详表
| 特性 | Cron | Heartbeat |
|---|---|---|
| 调度精度 | 高（精确到秒/分） | 低（取决于心跳间隔） |
| 触发时间 | 精确指定时间 | 下一次心跳时处理 |
| 离线行为 | Gateway 记录，Agent 上线后补执行 | Agent 离线期间不触发 |
| 管理方式 | CLI / 配置文件 | Agent 内部逻辑 |
| 适合场景 | 定时报告、周期同步 | 事件响应、状态检查 |
| 资源消耗 | 低（仅触发时消耗） | 持续消耗（每次心跳） |
| 任务类型 | 独立任务 | 队列中的待处理事件 |
| 重试机制 | 内置指数退避 | 依赖事件队列重投 |
| 最大任务数 | 无限制 | N/A（事件驱动） |
| 时区支持 | 支持 IANA 时区 | 跟随系统时区 |
工作流程对比
Cron 工作流
时间到达 → Gateway 触发 → 创建 Agent Turn → 执行任务 → 记录结果
↓
可选：主会话 / 隔离会话Heartbeat 工作流
心跳脉冲 → Agent 检查事件队列 → 有事件? → 处理事件 → 下一次心跳
↓
无事件 → 跳过选择指南
使用 Cron 的场景
推荐使用 Cron
- ✅ 每天固定时间生成日报/周报
- ✅ 每小时同步外部数据
- ✅ 每周一自动发送会议提醒
- ✅ 月底自动生成月度报表
- ✅ 需要精确到分钟或秒的调度
- ✅ Agent 可能不在线，但任务不能遗漏
bash
# 示例：每天早上 7 点生成晨报
openclaw cron add \
--name "morning-report" \
--cron "0 7 * * *" \
--timezone "Asia/Shanghai" \
--session isolated \
--message "生成今日晨报"使用 Heartbeat 的场景
推荐使用 Heartbeat
- ✅ 响应 Webhook 推送的事件
- ✅ 处理 Polls 检测到的数据变更
- ✅ 执行用户交互式命令
- ✅ 低优先级的后台状态检查
- ✅ Agent 始终在线的实时响应场景
json
{
"agent": {
"heartbeat": {
"interval": 15000,
"onBeat": "check-pending-events"
}
}
}组合使用
在复杂工作流中，Cron 和 Heartbeat 可以协同工作：
Cron (每小时) Heartbeat (每15秒)
│ │
▼ ▼
生成同步指令 ──入队──> Agent 处理队列事件
│
▼
执行数据同步
│
▼
结果通知/存储组合示例：定时数据同步 + 实时通知
json
{
"cron": {
"entries": {
"data-sync-trigger": {
"cron": "0 */2 * * *",
"session": "main",
"message": "启动数据同步流程"
}
}
},
"agent": {
"heartbeat": {
"interval": 10000,
"onBeat": "process-sync-queue"
}
}
}协同工作模式
- Cron 每 2 小时触发一次，将 "数据同步" 事件入队
- Heartbeat 每 10 秒检查队列，发现事件后执行实际的同步操作
- 同步完成后，通过 Webhook 或 Announce 通知用户
性能与资源考量
| 指标 | Cron | Heartbeat |
|---|---|---|
| CPU 开销 | 仅触发时 | 每次心跳 |
| 内存占用 | 任务列表常驻 | 事件队列常驻 |
| 网络 I/O | 仅执行时 | 每次心跳可能检查 |
| 适合任务量 | 大量定时任务 | 少量实时事件 |
决策流程图
需要自动化调度?
│
├── 精确时间触发? ──── Yes ──> 使用 Cron
│
├── 响应外部事件? ──── Yes ──> 使用 Heartbeat
│
├── 两者都需要? ──── Yes ──> 组合使用
│
└── 不确定? ──── 从 Cron 开始，需要时加入 Heartbeat🇨🇳 中国用户须知
- Cron 时区务必设置为
Asia/Shanghai，避免因服务器部署在海外导致时间偏差 - 心跳间隔不建议设置过小（<5s），以免在低配服务器上造成性能压力
- 国内云服务器（如阿里云 ECS）的定时任务与 OpenClaw Cron 不冲突，但建议统一由 OpenClaw 管理以减少维护成本