OpenClaw 心跳机制原理与实现详解

OpenClaw 心跳是周期性触发、AI 自主巡检、静默过滤、分层决策的主动式 Agent 运行机制，核心是让 AI 定期 "醒来" 执行任务并只在异常时通知用户。

一、核心定位与设计理念

• 定位 ：不是简单的网络存活检测，而是AI Agent 的自主巡检与任务调度引擎，实现 "无人触发、主动执行、有事才报"。
• 理念 ：静默优先、分层决策、低成本优先，避免空转与无效通知。
• 核心文件 ：heartbeat.md（定义巡检任务）、heartbeat-state.json（状态持久化）。

二、完整实现流程（5 步闭环）

1. 调度触发（Scheduler）

   • 后台守护进程按配置周期（默认 30 分钟）触发心跳。
   • 支持 cron 精确时间调度与 wakeMode: now/next-heartbeat 立即唤醒。
   • 队列繁忙时自动跳过并重试。

2. **前置检查（五层跳过）**任何一层不满足则直接跳过，不调用模型：

   • 全局开关 heartbeatsEnabled 关闭
   • 无有效 target 渠道
   • 所有可见性标志（showOk/showAlerts/useIndicator）均为 false
   • 主会话已过期
   • 上次心跳异常未恢复

3. AI 执行（Agent Run）

   • 读取 heartbeat.md 任务清单。

   • 执行内置提示词：

     read heartbeat.md if it exists. follow it strictly.
     if nothing needs attention, reply heartbeat_ok.

   • 自主判断并执行任务（如监控、提醒、修复）。

4. 响应过滤（静默机制）

   • 正常：返回 HEARTBEAT_OK → 系统静默丢弃，不通知用户。
   • 异常 / 有任务：返回非 OK 内容 → 转发给用户 / 指定渠道。
   • 长度控制：回复超 300 字符视为有实质内容，强制上报。

5. 状态与通知（Escalation）

   • 结果持久化到 heartbeat-state.json。
   • 按 target/to 发送到指定渠道（如 Slack、邮件）。
   • 可见性控制：showOk/showAlerts/useIndicator 开关。

三、关键技术特性

• 分层决策（Cheap Checks First）
  1. 快速确定性检查（进程、文件、队列、API 状态，毫秒级）
  2. 规则引擎阈值判断
  3. 仅模糊时才调用 LLM，大幅降低成本
• 模型降级（Fallback Chain）
  • 支持 primary/fallbacks 模型链
  • 两种降级模式：immediate（同轮重试）、next_heartbeat（下轮轮换）
• 与 Cron 互补
  • Cron：固定时间执行固定命令，无判断
  • Heartbeat：定期唤醒、自主决策、可修复 Cron 失败任务

四、典型 heartbeat.md 示例

# 定时巡检任务
- [] 每天 9:00 提醒喝水
- [] 检查 GitHub Issues，有新 PR 则通知
- [] API 余额 < $10 时告警
- [] 监控服务器磁盘使用率 > 85% 时提醒
- [] 每小时同步笔记到云端

五、配置与可见性（关键参数）

heartbeat:
  enabled: true
  interval: 30m  # 周期
  model: gpt-4o
  primary: gpt-4o
  fallbacks: [claude-3, gemini]
  fallbackMode: next_heartbeat
  showOk: false    # 不显示 OK
  showAlerts: true # 显示告警
  target: last     # 发送到最后使用的渠道

六、架构简图

调度器 → 五层检查 → 读取 heartbeat.md → AI 执行 → 响应过滤 → 通知/静默
       ↓（异常）        ↓（正常）
     模型降级       丢弃回复