6.17 心跳机制

Heartbeat(心跳)是 OpenClaw 的周期性 Agent 回合机制,用于在无外部消息时主动浮现紧急事项,避免信息过载。

概述

Heartbeat 与传统 Cron 任务不同:

• 智能触发 - 根据上下文判断是否需要行动
• 避免骚扰 - 无紧急事项时不发送消息
• 上下文感知 - 访问完整的 Agent 状态和历史
• 灵活控制 - 可配置触发条件和频率

Heartbeat vs Cron

传统 Cron

• 固定时间执行,不考虑上下文
• 总是产生输出(即使无意义)
• 无法访问 Agent 状态
• 容易造成消息骚扰

OpenClaw Heartbeat

• 周期性检查,智能决策是否行动
• 仅在必要时发送消息
• 完整访问工具、记忆、文件
• 用户可控制触发频率

配置 Heartbeat

基本配置

{
  "agents": {
    "list": [{
      "id": "main",
      "heartbeat": {
        "enabled": true,
        "interval": "30m",        // 默认 30 分钟
        "onlyWhenIdle": true      // 仅在空闲时触发
      }
    }]
  }
}

间隔配置

支持的时间格式:

{
  "heartbeat": {
    "interval": "15m"   // 15 分钟
  }
}

{
  "heartbeat": {
    "interval": "1h"    // 1 小时
  }
}

{
  "heartbeat": {
    "interval": "30s"   // 30 秒(调试用)
  }
}

Prompt 行为

默认 Prompt

Heartbeat 触发时,Agent 会收到特殊 prompt,包含:

• 当前时间和上次活动时间
• 待办事项列表
• 最近的对话上下文
• 可用工具列表

自定义 Prompt

通过工作区的 HEARTBEAT.md 自定义:

# HEARTBEAT.md

## 心跳检查指南

在每次心跳时,请检查:

1. 是否有未完成的待办事项
2. 是否有紧急通知需要处理
3. 是否需要更新项目状态
4. 是否有定时任务需要执行

**重要**: 如果没有紧急事项,请回复 HEARTBEAT_OK。

HEARTBEAT_OK 响应

静默机制

Agent 可以通过返回 HEARTBEAT_OK 表示无需行动:

# Agent 判断无紧急事项时
HEARTBEAT_OK

# 或带简短说明
HEARTBEAT_OK - 所有任务进行中,无需干预

规则

• HEARTBEAT_OK 不会发送给用户
• Agent 仍会记录本次心跳
• 计数器会重置,等待下次间隔
• 不影响正常消息流

交付控制

频道设置

可以为不同频道配置不同的心跳行为:

{
  "channels": {
    "whatsapp": {
      "heartbeat": {
        "enabled": true,
        "deliverTo": ["dm"],    // 仅私聊
        "suppressIn": ["groups"] // 群组中不发送
      }
    },
    "telegram": {
      "heartbeat": {
        "enabled": true,
        "deliverTo": ["all"]    // 所有对话
      }
    }
  }
}

静音时段

{
  "agents": {
    "list": [{
      "heartbeat": {
        "enabled": true,
        "quietHours": {
          "enabled": true,
          "start": "22:00",
          "end": "08:00",
          "timezone": "Asia/Shanghai"
        }
      }
    }]
  }
}

可见性控制

隐藏心跳消息

{
  "agents": {
    "list": [{
      "heartbeat": {
        "visibility": {
          "showInChat": false,      // 不在聊天中显示
          "showInLogs": true,       // 仍记录到日志
          "notifyOnAction": true    // 有行动时才通知
        }
      }
    }]
  }
}

手动触发

CLI 命令

# 手动触发心跳
openclaw agent heartbeat main

# 强制触发(忽略间隔)
openclaw agent heartbeat main --force

# 查看上次心跳时间
openclaw agent status main --heartbeat

聊天命令

在对话中手动唤醒:

/heartbeat        # 立即触发心跳
/wake             # 同上
/check            # 检查待办事项

推理输出

推理日志

Heartbeat 触发时的推理过程会被记录:

{
  "agents": {
    "list": [{
      "heartbeat": {
        "reasoning": {
          "enabled": true,
          "deliverToUser": false,    // 不发送给用户
          "logToFile": true,         // 记录到文件
          "includeInContext": true   // 包含在上下文中
        }
      }
    }]
  }
}

查看推理日志

# 查看最近的心跳推理
openclaw logs --filter heartbeat

# 查看特定 Agent
openclaw logs --agent main --filter heartbeat

# 导出推理历史
openclaw agent export main --include heartbeat-reasoning

成本控制

Token 使用

Heartbeat 会消耗 API tokens:

• 每次心跳 = 1 次 LLM 调用
• 包含完整上下文和工具列表
• 推荐使用较长间隔(≥30分钟)
• 高频心跳会快速消耗配额

成本优化

{
  "agents": {
    "list": [{
      "heartbeat": {
        "enabled": true,
        "interval": "1h",             // 较长间隔
        "model": "gpt-4o-mini",       // 使用更便宜的模型
        "maxTokens": 500,             // 限制输出长度
        "includeFullContext": false   // 简化上下文
      }
    }]
  }
}

使用场景

任务提醒

# HEARTBEAT.md
检查是否有即将到期的任务:
- 扫描 TODO.md 中标记了 deadline 的项目
- 如果有 24 小时内到期的任务,提醒用户
- 否则返回 HEARTBEAT_OK

状态同步

# HEARTBEAT.md
定期同步项目状态:
- 检查 Git 仓库是否有未提交更改
- 检查是否有新的 PR 评论
- 检查 CI/CD 是否失败
- 有问题时通知,否则 HEARTBEAT_OK

监控告警

# HEARTBEAT.md
监控系统指标:
- 检查服务器健康状态
- 检查错误日志
- 检查资源使用率
- 发现异常时立即报告

调试 Heartbeat

启用详细日志

# 查看心跳日志
DEBUG=openclaw:heartbeat openclaw gateway start

# 或在配置中启用
{
  "logging": {
    "components": {
      "heartbeat": "debug"
    }
  }
}

测试配置

# 使用短间隔测试
{
  "heartbeat": {
    "interval": "1m"  // 仅用于测试
  }
}

# 测试完成后改回正常值
{
  "heartbeat": {
    "interval": "30m"
  }
}