OpenClaw 自动化调度实战：Cron 定时任务与 Heartbeat 心跳机制的工程化应用

自动化调度是 OpenClaw 的核心能力之一，它让 AI 助手能够在无人值守的情况下定期执行任务、监控状态并主动汇报。OpenClaw 提供了 Cron 定时任务与 Heartbeat 心跳两种互补的调度机制。本文从两者的设计差异出发，系统梳理在工程场景中的选型与最佳实践。

一、Cron 与 Heartbeat 的设计差异

两种机制看似都能触发任务，但设计目标截然不同：

Cron      -- 精确时刻触发，隔离执行，适合定期一次性任务
Heartbeat -- 批量检查，复用会话上下文，适合需要记忆的巡逻任务

Cron 用于”在某个精确时间做一件事”（如每天 23:00 发布文章、每周五备份数据），它拥有独立会话、可指定不同模型与思考强度，执行结果独立汇报。Heartbeat 则用于”定期看看有没有需要处理的事”，它复用主会话上下文，能读取历史记忆做出判断。

二、Cron 定时任务的配置

OpenClaw 的 Cron 调度使用标准 cron 表达式，并支持丰富的调度属性。一个典型的定时发布任务如下：

{
  "kind": "cron",
  "expr": "0 23 * * *",
  "tz": "Asia/Shanghai",
  "payload": {
    "kind": "agentTurn",
    "timeoutSeconds": 1800
  }
}

关键点在于 expr（cron 表达式）、tz（时区，避免跨时区错乱）与 timeoutSeconds（超时上限）。对于耗时的多步骤任务（如发布多篇文章），务必设置足够的超时时间，否则会因默认超时而连续失败。

三、Heartbeat 心跳机制的应用

Heartbeat 通过周期性的轮询让助手检查是否有待办事项。它适合”需要记忆与判断”的场景，例如：

# HEARTBEAT.md 中定义待检查事项
1. 检查是否有未处理的邮件
2. 检查服务器磁盘空间是否告警
3. 检查待办任务列表

心跳触发时，助手读取 HEARTBEAT.md 按清单逐项检查。若无事项需要处理，则返回 HEARTBEAT_OK；若有则主动执行并汇报。这种模式让助手具备”主动巡逻”能力，而非被动等待指令。

四、选型决策矩阵

面对具体场景，如何选择调度机制？参考以下决策矩阵：

实际项目中两者常配合使用：Cron 负责”定时必做”的任务，Heartbeat 负责”定期巡查”的监控。

五、工程化最佳实践

在落地自动化调度时，有几个容易被忽略的关键点：

1. 超时设置：耗时任务务必调大 timeoutSeconds
2. 时区统一：显式指定 tz 避免跨时区错乱
3. 幂等设计：任务可重复执行而不产生副作用
4. 错误汇报：失败时以 AUTOMATION_FAILED 开头并说明原因
5. 依赖检查：任务前先确认前置条件是否满足

尤其是幂等设计与错误汇报，直接决定了无人值守场景下的可靠性。一个会重复发布内容的任务，若缺乏幂等保护，会在调度重试时产生数据混乱。

六、监控与故障排查

自动化任务运行后应建立监控手段。OpenClaw 提供任务状态查询与运行历史，帮助定位失败原因。常见故障包括：

超时失败   -- timeoutSeconds 不足
凭据缺失   -- 任务依赖的密钥未配置
依赖未就绪 -- 前置服务或条件未满足

通过查看任务运行日志，能快速定位是哪一类问题，进而针对性修复。

七、小结

Cron 与 Heartbeat 是 OpenClaw 自动化调度的两大支柱：Cron 负责精确、隔离、可指定模型的定时任务；Heartbeat 负责带记忆、带判断的巡逻检查。合理选型加上超时、幂等、错误汇报等工程化实践，能让 AI 助手在无人值守下可靠地完成大量重复性工作，真正实现”自动化运维”的价值。