OpenClaw实战教程系列第08篇 - 心跳机制：AI 主动巡检

AI 不是只有你叫它才会动——心跳让它主动检查你的世界。

---

开篇：从“被动响应”到“主动感知”

到目前为止，你的 AI 一直是“被动”的：你说话，它回答；你不说，它沉默。

但真正的 AI 管家不应该这样。你的私人助理不会等你开口才去看邮件——它应该主动巡查，有情况立刻汇报，没事就安静待命。

这就是 Heartbeat（心跳机制）的价值：让 AI 每隔 30 分钟自动醒来，检查你的世界，有问题通知你，没问题安静回去睡觉。

---

Heartbeat vs Cron：怎么选？

上一篇学了 Cron（精确定时任务），现在学 Heartbeat（周期性巡检）。两者经常被混淆，一张表说清楚：

特性	Cron	Heartbeat
触发时机	精确时间点（如 06:00）	周期性（如每 30 分钟）
运行环境	独立 session（推荐）或主 session	主 session
任务类型	执行具体操作（采集、发布）	检查状态（有没有新邮件）
典型场景	发日报、定时提醒、月度报告	邮件巡检、日历提醒、系统健康
一次性任务	✅ 支持	❌ 不支持
资源占用	每次启动新 session	复用主 session，更轻量

选择原则（记住这两句话）：

• 要执行某个操作（采集数据、发消息、生成报告）→ 用 Cron

• 要检查某个状态（有没有新邮件、系统是否正常）→ 用 Heartbeat

💡 经验法则：能合并的检查放心跳，需要精确时间的用 Cron。不要给心跳太重的任务——它是“巡逻员”，不是“搬运工”。

---

Heartbeat 工作原理

时间线：

09:00 ─── 09:30 ─── 10:00 ─── 10:30 ──►
   │          │          │          │
   ▼          ▼          ▼          ▼
Gateway    Gateway    Gateway    Gateway
唤醒 AI    唤醒 AI    唤醒 AI    唤醒 AI
   │          │          │          │
   ▼          ▼          ▼          ▼
读取         读取         读取         读取
HEARTBEAT.md HEARTBEAT.md HEARTBEAT.md HEARTBEAT.md
   │          │          │          │
   ▼          ▼          ▼          ▼
执行检查     执行检查     执行检查     执行检查
   │          │          │          │
   ▼          ▼          ▼          ▼
无异常       有异常！     无异常       无异常
   │          │          │          │
   ▼          ▼          ▼          ▼
HEARTBEAT_OK 发送通知   HEARTBEAT_OK HEARTBEAT_OK
（静默）    到 Telegram  （静默）    （静默）

关键机制：

1. 在主 session 中运行：心跳复用主会话上下文，AI 知道你最近在做什么

2. 读取 HEARTBEAT.md：这个文件就是你的“巡检清单”，告诉 AI 每次要检查什么

3. 智能静默：无异常时回复 HEARTBEAT_OK，OpenClaw 自动过滤，不会打扰你

4. 空文件跳过：如果 HEARTBEAT.md 只有空行和标题，OpenClaw 直接跳过本次心跳，不消耗 API 调用

---

HEARTBEAT.md：定义你的巡检清单

HEARTBEAT.md 是心跳机制的核心配置文件，位于：

~/.openclaw/workspace/HEARTBEAT.md

每次心跳触发时，AI 会读取这个文件，按照清单逐项检查。

基础结构

心跳巡检清单

检查项

邮件检查
- [ ] 检查未读邮件（himalaya list -s unread）
- [ ] 如果有紧急邮件（标记为 important），立即通知
- [ ] 普通邮件：只在数量 > 5 时汇总通知

日历检查
- [ ] 检查未来 2 小时内是否有会议（icalBuddy）
- [ ] 如果有，提前 15 分钟提醒
- [ ] 检查是否有冲突的会议

系统健康
- [ ] 浏览器 tab 数量 > 15 时提醒关闭
- [ ] 内存使用率 > 80% 时警告

通知规则
- 紧急：立即发送到 Telegram
- 普通：只在有变化时报告
- 无异常：回复 HEARTBEAT_OK（静默）

⚠️ 安全提醒：不要把 API Key、密码、手机号等敏感信息放进 HEARTBEAT.md——这个文件会成为每次心跳的 prompt 上下文，会被发送到 LLM 提供商。

实战示例：完整巡检清单

# HEARTBEAT.md

## 邮件（himalaya）
```bash
himalaya list -s unread | head -20

• 未读 > 0：通知数量和发件人

• 未读 > 5：提醒“需要处理邮件了”

• 有来自 boss/client 的邮件：高优先级通知

日历（icalBuddy）

icalBuddy eventsToday+1 | head -10

• 2 小时内有会议：提前提醒

• 会议冲突：立即警告

GitHub（gh CLI）

gh issue list -a @me --json number,title,labels | head -10

• 有 P0/P1 issue：立即通知

• 有需要 review 的 PR：提醒

系统健康

• 内存 > 80%：警告

• 浏览器 tab > 15：提醒关闭一些

• 磁盘 < 20GB：紧急警告

静默规则

以下情况只回复 HEARTBEAT_OK：

• 邮件 < 5 封且无紧急邮件

• 2 小时内无会议

• GitHub 无新事项

• 系统健康正常

实际效果示例

有异常时：

⚠️ 心跳提醒（10:30）

📧 邮件：3 封未读

• AWS 账单提醒（重要）

• GitHub PR #123 需要 review

• 来自 John 的项目更新

📅 日历：14:00 有产品评审会议（1.5 小时后）

💻 系统：浏览器 18 个 tab，建议清理

无异常时：

HEARTBEAT_OK

（这条消息会被 OpenClaw 自动过滤，不会出现在你的聊天界面）

---

配置心跳频率

心跳频率在 `openclaw.json` 中配置：

```json
{
  "heartbeat": {
    "every": "30m"
  }
}

时间格式： 30m（30 分钟）、1h（1 小时）、2h30m（2 小时 30 分）、0m（禁用）

💡 官方默认值： 30 分钟（使用 Anthropic OAuth/setup-token 时默认 1 小时）

推荐频率配置

场景	频率	说明
标准配置	30m	平衡及时性和成本
高频需求	15m	需要快速响应的场景
省钱/低频	1h	只在必要时检查
禁用	0m	完全关闭心跳

⚠️ 踩坑实录：心跳不要太频繁！

我曾经设置成 5 分钟一次：

{
  "heartbeat": {
    "every": "5m"
  }
}

结果：

• 每小时 12 次心跳，每次都调用 LLM

• API 成本飙升 6 倍

• 更糟糕：心跳处理超时导致 Gateway 异常重启

正确配置（30 分钟 + 深夜降频）：

{
  "heartbeat": {
    "every": "30m"
  }
}

深夜静默可以在 HEARTBEAT.md 中用条件语句实现：

## 深夜模式（23:00 - 08:00）

如果当前时间在 23:00 到 08:00 之间：
- 只检查：紧急邮件（监控系统报警）、生产环境故障
- 跳过：普通邮件、日历、GitHub、系统健康、天气

---

四大巡检场景详解

场景 1：邮件巡检

目标：有紧急邮件立刻通知，普通邮件批量汇报，不打扰正常工作。

## 邮件检查（himalaya）

检查命令：himalaya list -s unread

通知规则：
- 有来自 boss/client 的邮件 → 立即通知，附发件人和主题
- 有 AWS/阿里云账单邮件 → 标记为重要，通知金额
- 未读 > 5 封 → 汇总通知："有 X 封未读邮件"
- 未读 1-5 封且无紧急 → HEARTBEAT_OK（静默）

场景 2：日历提醒

目标：会议前 15 分钟提醒，有冲突立刻警告。

## 日历检查（icalBuddy）

检查命令：icalBuddy eventsToday+1

通知规则：
- 2 小时内有会议 → 提醒："X 分钟后有 [会议名称]"
- 会议冲突 → 立即警告，列出冲突的会议
- 无近期会议 → HEARTBEAT_OK（静默）

场景 3：GitHub 巡检

目标：有新 P0 issue 或需要 review 的 PR 时通知。

## GitHub 检查（gh CLI）

检查命令：
- gh issue list -a @me --json number,title,labels
- gh pr list --review-requested @me

通知规则：
- 有 P0/P1 issue → 立即通知，附 issue 编号和标题
- 有需要 review 的 PR → 提醒，附 PR 编号
- 你提交的 PR 被合并 → 通知 ✅
- 无新事项 → HEARTBEAT_OK（静默）

场景 4：系统健康检查

目标：防止系统资源耗尽导致崩溃。

## 系统健康检查

检查项：
- 内存使用率：> 80% 警告，> 90% 紧急警告
- 磁盘空间：< 50GB 提醒，< 20GB 紧急警告
- 浏览器 tab：> 15 提醒，> 30 警告（严重影响性能）

检查命令：
- 内存：vm_stat | grep "Pages active"（macOS）
- 磁盘：df -h / | tail -1
- Tab 数：osascript -e 'tell application "Chrome" to count tabs of every window'

---

智能状态跟踪：避免重复通知

心跳会维护状态，避免同一件事反复打扰你。AI 会自动记住“已通知过”的事项：

09:30 心跳：发现 3 封未读邮件 → 通知用户
10:00 心跳：还是 3 封（用户没看）→ 不再重复通知
10:30 心跳：变成 5 封（新增 2 封）→ 通知"新增 2 封"

你也可以在 HEARTBEAT.md 中明确要求这种行为：

## 去重规则
- 已通知过的邮件不再重复提醒
- 已提醒过的会议不再重复提醒
- 只报告"新增"和"变化"，不报告"已知"状态

---

渠道投递配置

心跳结果可以发送到不同渠道，在 openclaw.json 中配置：

{
  "channels": {
    "defaults": {
      "heartbeat": {
        "showOk": false,
        "showAlerts": true,
        "useIndicator": true
      }
    },
    "telegram": {
      "heartbeat": {
        "showOk": false
      }
    }
  }
}

配置说明：

• showOk: false：HEARTBEAT_OK 不显示在聊天界面（推荐）

• showAlerts: true：有异常时发送通知

• useIndicator: true：使用状态指示符（如 💓）

💡 最新版本（v2026.2.25+）：心跳 DM 投递策略改为 agents.defaults.heartbeat.directPolicy: "allow" 控制，默认允许直接消息投递。如需禁用，设置为 "block"。

---

管理和调试心跳

# 手动立即触发一次心跳（测试用）
openclaw heartbeat --now

# 干跑（显示会做什么，但不实际执行）
openclaw heartbeat --dry-run

# 查看心跳日志（实时）
openclaw logs --filter heartbeat --follow

# 查看心跳统计（成本、执行次数）
openclaw stats heartbeat

💡 调试技巧：修改 HEARTBEAT.md 后，用 openclaw heartbeat --now 立刻测试效果，不用等下一个 30 分钟。

---

故障排除

Q1：心跳太频繁导致 Gateway 重启

症状： Gateway 经常自动重启，日志显示心跳处理超时。

原因：心跳间隔太短（< 15 分钟）或每次检查项太多。

解决：

1. 增加心跳间隔到 30m 以上

2. 减少每次心跳的检查项（用轮换机制）

3. 在 HEARTBEAT.md 中指定用更快的模型处理心跳

Q2：心跳没有执行？

# 1. 确认 HEARTBEAT.md 存在且有内容
cat ~/.openclaw/workspace/HEARTBEAT.md

# 2. 检查心跳配置
cat ~/.openclaw/openclaw.json | grep -A3 heartbeat

# 3. 查看日志
openclaw logs --filter heartbeat --follow

# 4. 手动触发测试
openclaw heartbeat --now

常见原因：

• HEARTBEAT.md 只有空行和标题 → OpenClaw 会自动跳过（这是正常行为，节省 API 调用）

• every: "0m" → 心跳被禁用

• Gateway 没有运行

Q3：心跳报告太啰嗦，一直打扰我

在 HEARTBEAT.md 中加入严格的静默规则：

## 静默规则（重要）

以下情况只回复 HEARTBEAT_OK，不发送任何消息：
- 邮件 < 5 封且无紧急邮件
- 2 小时内无会议
- GitHub 无新 P0/P1 事项
- 系统健康正常（内存 < 80%，磁盘 > 50GB）

只报告异常和有变化的事项。绝对不要重复报告已通知过的内容。

Q4：心跳成本太高？

问题：每次心跳都发送完整工作区上下文（AGENTS.md、SOUL.md、MEMORY.md、HEARTBEAT.md 等）给主模型，如果主模型是 Opus，成本很高。

解决方案：

• 精简工作区文件，删除不必要的内容

• 在 HEARTBEAT.md 中明确要求“用最简单的方式回答”

• 关注官方即将推出的“心跳专用模型”配置功能（GitHub Issue #23254 中已提出）

---

高级技巧

技巧 1：轮换检查（减轻每次心跳负担）

如果检查项很多，不必每次全查。在 HEARTBEAT.md 中设置轮换：

## 轮换检查规则

奇数次心跳（1、3、5...）：
- 邮件检查
- 日历检查

偶数次心跳（2、4、6...）：
- GitHub 检查
- 系统健康检查

每 4 次心跳（约 2 小时）：
- 天气检查
- 磁盘空间检查

技巧 2：触发即时心跳

需要 AI 立刻检查一下？不用等下一个 30 分钟：

# 触发即时心跳（命令行）
openclaw heartbeat --now

# 或者直接告诉 AI
你："帮我检查一下现在有没有紧急邮件"

技巧 3：心跳 + Cron 协作

心跳和 Cron 不是对立的，可以协作：

Heartbeat（每 30 分钟）：
- 检查有没有新邮件
- 如果有，通知你

Cron（每天 09:00）：
- 生成邮件汇总报告
- 标记已读/归档

心跳负责“发现问题”，Cron 负责“处理问题”，分工明确。

---

验证清单

确认心跳系统正常工作：

• 创建了 ~/.openclaw/workspace/HEARTBEAT.md，内容不为空

• 文件中定义了至少 3 个检查项

• 配置了合理的心跳频率（推荐 30m）

• 用 openclaw heartbeat --now 手动触发测试成功

• 验证了 HEARTBEAT_OK 不会出现在聊天界面（showOk: false）

• 设置了静默规则（无异常时不打扰）

• 测试了有异常时能收到通知

---

本篇小结

核心要点：

1. Heartbeat = 主动巡检：AI 每 30 分钟自动醒来，检查你的世界，有问题通知你

2. HEARTBEAT.md 是核心：这个文件定义了 AI 每次心跳要检查什么，放在 ~/.openclaw/workspace/

3. HEARTBEAT_OK 是静默信号：无异常时 AI 回复这个，OpenClaw 自动过滤，不打扰你

4. 频率 30 分钟是黄金标准：太频繁会烧钱还可能导致 Gateway 重启

5. 心跳 vs Cron 分工明确：心跳检查状态，Cron 执行操作

---

下一步

现在你的 AI 能定时执行任务（Cron）、能主动巡检（Heartbeat）。但面对复杂任务，一个 AI 可能不够用。下一篇教你如何让多个 AI 协作：

→ 第 09 篇 | 多 Agent 协作 — 主 AI 当监工，派活给多个子 AI 并行执行，效率翻倍。

---

💬 读者讨论

你最想让 AI 主动帮你检查什么？
邮件？日历？还是服务器状态？
欢迎在评论区分享！

---

📚 本系列目录

• 第 01 篇：OpenClaw 是什么？

• 第 02 篇：5 分钟安装指南

• 第 03 篇：连接你的第一个聊天渠道

• 第 04 篇：个性化你的 AI

• 第 05 篇：记忆系统

• 第 06 篇：工具调用与 Skills

• 第 07 篇：定时任务 Cron

• 第 08 篇：心跳机制 Heartbeat（你在这里）

• 第 09 篇：多 Agent 协作

• 查看完整目录

---

下一篇预告：Sub-agents（子代理）——让主 AI 当监工，派活给多个子 AI 并行干活，编码、翻译、数据采集都能并行加速。