第 9 章 心跳机制：智能体的周期性自检与主动服务

🎯 本章特色：在《OpenClaw 实战指南》的系列章节中，本章深入讲解 OpenClaw 内置的 Heartbeat（心跳） 机制，这是让智能体从"被动应答"进化为"主动服务"的关键能力。不同于上一章介绍的精确定时任务，心跳机制赋予智能体"感知当下、判断是否值得打扰"的智慧。掌握心跳，你的 AI 就不再只是一个等指令的工具，而是一个懂得什么时候该说话、什么时候该沉默的数字管家。

本章目录：

1. 为什么需要心跳机制

1.1 从被动到主动：智能体的进化需求

在传统的 AI 交互模式中，智能体是"被动的"。你问它问题，它回答；你给它指令，它执行。这种模式在大多数场景下运行良好，但有一类需求它无法满足：在没有用户触发的情况下，主动发现问题并报告。

想象以下几种典型场景：

信息聚合监控。 你希望智能体每 30 分钟检查一次邮箱、日历和待办事项，如果有紧急邮件或即将开始的会议，立即通知你。但如果一切正常，就不需要发任何消息。这不是一个简单的定时任务，因为它需要根据检查结果决定是否通知你。

轻量级关怀。 白天工作时段，如果长时间没有交互，智能体可以发送一句"需要帮忙吗？"但绝不在深夜打扰你。这需要智能体理解当前的时间段，并结合上次交互的时间做出判断。

多任务批处理。 与其为每个监控项设置独立的定时任务（查邮件、看日历、盯 API 状态），不如合并为一次综合检查，节省资源和 Token 消耗。这种"打包处理"的思路天然适合心跳机制。

这些需求的共同点是：不需要精确到秒的触发时间，但需要结合当前上下文做智能判断。这正是 Heartbeat（心跳机制） 的用武之地。

1.2 心跳与定时任务的本质区别

要理解心跳机制的价值，先要和上一章介绍的定时任务（Automations）做个对比。

定时任务的特点是"到点就执行"。你设置了每天早上 8 点发天气，到了 8 点它就会执行，不管外面是晴天还是暴雨，不管你是不是已经出门了。它是忠实的闹钟，但不会判断"现在这个提醒还有没有意义"。

心跳机制的特点是"到点了，先看看有没有事"。它被唤醒后，会读取当前的上下文信息，检查各种条件，自行判断是否需要通知用户。如果有紧急事项，它会主动发消息；如果没有，它返回一个静默标记，系统什么都不做，不打扰你。

简单来说，定时任务是"闹钟"，到了时间就响。心跳机制是"管家"，隔一会儿看看有没有需要你关心的事，有就说，没有就不吭声。两者不是替代关系，而是互补关系。

下表总结了典型场景的选择建议：

理解了心跳机制的定位和价值后，接下来我们深入它的内部运作，看看每次心跳被触发时，系统到底做了什么。

2. 心跳机制的工作原理

心跳机制的核心思想是：定期唤醒智能体，让它自己判断"此刻是否值得打扰用户"。这个过程看似简单，但涉及上下文加载、检查清单解析、响应判断和消息投递等多个环节。理解这些细节，有助于你编写高效的心跳检查清单，避免不必要的 Token 浪费。

2.1 执行流程

每次心跳被触发时，系统会按照以下流程执行：

┌─────────────────────────────────────────────┐
│          心跳机制的执行流程                      │
│                                               │
│  Gateway 定时器                                │
│     │                                         │
│     ▼                                         │
│  检查：当前时间是否在活跃时间段内？              │
│     │                                         │
│     ├── 否 → 跳过本次心跳，不消耗 Token         │
│     │                                         │
│     ▼ 是                                      │
│  加载上下文（会话历史 + HEARTBEAT.md）           │
│     │                                         │
│     ▼                                         │
│  向智能体发送心跳提示词                         │
│     │                                         │
│     ▼                                         │
│  智能体执行检查，生成响应                       │
│     │                                         │
│     ├── 响应为 HEARTBEAT_OK → 静默丢弃          │
│     │                                         │
│     ▼ 响应为具体内容                            │
│  投递消息到目标渠道（微信、Telegram 等）         │
└─────────────────────────────────────────────┘

具体步骤如下：

1. 定时触发：按照配置的间隔（比如每 30 分钟）启动一次心跳轮次。系统首先检查当前时间是否在配置的活跃时间段内，如果不在，直接跳过，不消耗任何 Token。
2. 加载上下文：智能体加载当前的会话历史和心跳检查清单（HEARTBEAT.md）。如果启用了轻量上下文模式，则只加载检查清单，不加载完整的会话历史，从而大幅降低 Token 消耗。
3. 执行检查：向智能体发送预设的心跳提示词（prompt），让它按照清单逐项检查。智能体会根据当前的会话状态、时间、上下文等信息做出判断。
4. 生成响应：如果没有需要报告的事情，返回 HEARTBEAT_OK。系统识别到这个标记后，将消息静默丢弃，不打扰用户。如果有需要报告的事情，返回具体内容，系统将其发送给用户。
5. 投递消息：根据配置决定消息发送到哪个渠道（微信、Telegram 等），也可以配置为不发送。

2.2 HEARTBEAT.md：你的周期性检查清单

HEARTBEAT.md 是心跳机制的核心文件，位于工作区根目录。它定义了每次心跳时智能体应该检查什么。你可以把它理解为给管家的一张"巡检清单"，上面列着所有需要定期关注的事项。

以本书作者的电脑为例，文件路径为：

C:\Users\zhang\.openclaw\workspace\HEARTBEAT.md

文件内容示例：

# Heartbeat checklist

- 扫描收件箱：是否有标记为"紧急"的邮件？
- 检查未来 2 小时内是否有日历事件？
- 若过去 8 小时无用户交互，发送一句："一切顺利吗？"

💡 最佳实践：保持文件简短，建议 200 字以内。避免大段文本拖慢推理速度、增加 Token 消耗。如果暂时不需要心跳检查，可以保持文件为空或只写注释，系统会自动跳过心跳检查。

编写 HEARTBEAT.md 时，建议遵循以下原则：

具体且可执行。 每一条检查项都应该是智能体能够明确执行的动作。"关注一下系统状况"太模糊，"检查 CPU 使用率是否超过 80%"就足够具体。

有条件判断。 好的检查项包含"如果...则..."的逻辑。"检查邮件"不如"检查邮件，如果有标记为紧急的未读邮件，则报告"。这样智能体就知道什么时候该报告，什么时候该沉默。

按优先级排列。 把最重要的检查项放在前面。如果智能体在执行过程中遇到 Token 限制或超时，至少最重要的检查已经完成。

2.3 静默机制：HEARTBEAT_OK

智能体检查完后，如果没有需要报告的内容，会返回 HEARTBEAT_OK。系统识别到这个标记后，会将消息静默丢弃，不会发送给用户。这就是心跳机制"不打扰"的关键：无事不报。

识别规则如下：

• 当智能体的响应开头或结尾出现 HEARTBEAT_OK，且其余内容很短（不超过 300 个字符）时，系统认为这是"无事可报"，消息被丢弃。
• 如果 HEARTBEAT_OK 出现在响应中间，或者伴随很长的文本，系统会将其视为有效内容，正常发送。

⚠️ 注意：不要在有警报的内容中包含 HEARTBEAT_OK，否则系统可能误判为无事可报，把重要消息丢弃了。这是一个容易犯的错误，尤其在智能体生成较长的分析报告时。

2.4 节省成本的技巧

心跳检查会消耗 Token，尤其当每次都加载完整的会话历史和系统提示时，成本会比较高。以下是几种经过验证的成本优化方法：

轻量上下文模式（lightContext）。 只注入 HEARTBEAT.md 的内容，不加载完整的会话历史和系统提示。这是最有效的优化手段，单次心跳的 Token 消耗可以降低 60% 以上。对于大多数心跳检查场景，智能体不需要知道你之前聊了什么，它只需要知道"现在要检查什么"。

设置活跃时间段（activeHours）。 比如只在早 8 点到晚 10 点之间执行心跳，深夜时段自动跳过。这不仅能避免无意义的 Token 消耗，还能防止深夜收到不必要的通知。

使用轻量模型。 如果心跳任务比较简单（只是检查几个布尔条件），可以配置一个较轻量的模型来处理心跳检查，把昂贵的大模型留给需要深度推理的主对话。

精简检查清单。 HEARTBEAT.md 越长，每次心跳消耗的 Token 越多。定期检查清单，删除不再需要的检查项，保持文件精简。

这些优化手段可以叠加使用。在实际使用中，同时启用轻量上下文和活跃时间段限制，可以将心跳的月度 Token 开销控制在非常合理的范围内。

掌握了心跳机制的工作原理后，下一步就是动手配置。接下来我们看看如何在 openclaw.json 中启用心跳，并针对不同场景进行调优。

3. 配置心跳机制

心跳机制的配置在 openclaw.json 的 agents.defaults.heartbeat 字段中完成。配置结构清晰直观，几个关键字段就能定义完整的心跳行为。

3.1 基础配置

以下是一个基础的心跳配置示例，取自本书作者的实际运行环境：

{
  "agents": {
    "defaults": {
      "heartbeat": {
        "every": "40m",
        "target": "last",
        "to": "openclaw-weixin"
      }
    }
  }
}

各字段含义：

every 字段决定了心跳的触发频率。默认值为 30 分钟，你可以根据实际需求调整。间隔越短，智能体的"感知"越敏锐，但 Token 消耗也越高。一般来说，30 到 60 分钟是大多数场景的合理范围。

3.2 轻量上下文与活跃时间

如果你希望减少 Token 消耗，并且只在白天执行心跳检查，可以添加 lightContext 和 activeHours 配置：

{
  "agents": {
    "defaults": {
      "heartbeat": {
        "every": "40m",
        "activeHours": {
          "start": "08:00",
          "end": "22:00"
        },
        "target": "last",
        "to": "openclaw-weixin",
        "lightContext": true
      }
    }
  }
}

新增字段的含义：

这个配置的效果：

• 活跃时间：只在 08:00 到 22:00 之间执行心跳，其他时段自动跳过，不消耗任何 Token。
• lightContext: true：启用轻量上下文模式，减少历史记录携带，降低 Token 消耗，让智能体专注于当前检查任务。

两者结合使用，可以使单次心跳的 Token 消耗大幅降低。这也是本书作者实际使用的配置方案，经过长期运行验证，在成本和服务质量之间取得了良好的平衡。

3.3 多智能体差异化配置

如果你有多个智能体，可以为每个智能体配置不同的心跳策略。例如，你有一个日常助手 main 和一个运维机器人 ops，只想让 ops 执行更频繁的心跳检查：

{
  "agents": {
    "defaults": {
      "heartbeat": {
        "every": "40m",
        "activeHours": {
          "start": "08:00",
          "end": "22:00"
        },
        "target": "last",
        "lightContext": true
      }
    },
    "entries": {
      "main": {},
      "ops": {
        "heartbeat": {
          "every": "15m",
          "target": "telegram",
          "to": "123456789:topic:42",
          "prompt": "检查服务器健康状态。如果 CPU 超过 70% 或磁盘空间低于 10%，立即告警。否则回复 HEARTBEAT_OK。"
        }
      }
    }
  }
}

在这个配置中，main 智能体继承 defaults 中的心跳配置（每 40 分钟、轻量上下文），而 ops 智能体使用自己的配置（每 15 分钟、自定义提示词、投递到 Telegram 的特定话题）。

prompt 字段允许你为特定智能体定义专属的心跳提示词，覆盖默认的系统心跳提示。这对于运维监控类的智能体特别有用，可以让它在每次心跳时执行精确的检查逻辑。

⚠️ 注意：一旦在 agents.entries 中为某个智能体定义了 heartbeat，该智能体将完全使用自己的心跳配置，不会与 defaults 中的心跳配置合并。请确保自定义配置包含所有必要的字段。

3.4 可见性控制

你可以通过渠道配置，精细控制不同渠道的心跳消息显示行为：

这些配置可以根据不同渠道分别设置。比如你可以在 Telegram 上显示每次心跳的 OK 结果用于调试，在微信上只显示警报避免打扰。这种灵活性让你在不同场景下都能获得最合适的体验。

配置完成后，心跳机制就能独立运行了。但真正发挥威力的方式，是将心跳与上一章介绍的定时任务结合起来。接下来我们看看如何让两者协同工作。

4. 心跳与定时任务的协同

最高效的自动化系统往往同时使用心跳和定时任务，各司其职。理解两者的分工，是构建优雅自动化方案的关键。

4.1 感知层与执行层

一个成熟的自动化体系可以分为两个层次：

感知层（心跳）。 负责日常的"巡逻"和"感知"。它定期扫描各种信息源，判断是否有需要关注的事项。特点是批量检查、上下文感知、低频打扰。心跳就像一个尽职的门卫，每隔一段时间巡视一圈，只有发现异常才报告。

执行层（定时任务）。 负责准时执行具体的任务。它不需要判断，到点就做，做完就交付。特点是精确时间、独立运行、结果确定。定时任务就像一个可靠的闹钟加执行器，按时完成任务并汇报结果。

┌──────────────────────────────────────────────────┐
│          心跳 + 定时任务的协同架构                   │
│                                                    │
│  ┌──────────────────────┐  ┌────────────────────┐ │
│  │    感知层（心跳）      │  │  执行层（定时任务）   │ │
│  │                      │  │                    │ │
│  │  • 检查邮箱          │  │  • 每天7点发晨报    │ │
│  │  • 扫描日历          │  │  • 20分钟后提醒开会  │ │
│  │  • 监控服务器状态    │  │  • 每周五生成周报    │ │
│  │  • 判断是否需要通知  │  │  • 每天备份数据库    │ │
│  │                      │  │                    │ │
│  │  特点：智能判断       │  │  特点：准时执行      │ │
│  │  无事不报            │  │  到点就做            │ │
│  └──────────────────────┘  └────────────────────┘ │
│                                                    │
│  两者互补：心跳保持全局感知，定时任务确保准时交付    │
└──────────────────────────────────────────────────┘

4.2 实战组合方案

以下是一个经过实践验证的组合方案，适合大多数个人生产力场景：

心跳配置（每 40 分钟）：

# HEARTBEAT.md

- 检查邮箱是否有标记为"紧急"的未读邮件
- 查看未来 2 小时内是否有日历事件
- 如果空闲超过 8 小时，发送一句轻量问候

定时任务（精确执行）：

• 每天早上 7:00 生成一份晨报并发送到微信
• 每周一上午 9:00 生成上周工作回顾
• 用户说"20 分钟后提醒开会"时创建一次性 at 任务

这种组合的好处在于：心跳帮你保持对全局的感知，不会错过紧急邮件或即将到来的会议；定时任务确保重要事项准时完成，不会因为心跳间隔的漂移而延误。两者互补，覆盖了从"模糊感知"到"精确执行"的全部需求。

一个常见的反模式是把所有任务都塞进心跳检查清单。比如有人在 HEARTBEAT.md 中写了"生成每日报告并发送"，这是不合适的。报告生成是一个确定性的任务，应该用定时任务来实现。心跳只适合做"检查一下有没有什么需要注意的"这类判断型工作。

理解了协同方案后，我们来看看实际使用中可能遇到的问题和解决办法。

5. 常见问题与排查

心跳机制在使用过程中可能会遇到一些疑问和异常情况。本节汇总了最常见的问题及其解决方案。

5.1 心跳间隔设置多少合适

一般来说，30 到 60 分钟是比较合理的间隔。

间隔太短（比如 5 分钟）会显著增加 Token 消耗，也可能频繁打扰用户。更重要的是，大多数心跳检查项（查邮件、看日历）本身就不需要这么高的频率。

间隔太长（比如 4 小时）则可能错过重要信息。一封紧急邮件如果在心跳间隔的间隙到达，可能要等很久才被检测到。

根据使用场景的建议：

5.2 心跳会消耗很多 Token 吗

这是很多用户关心的问题。答案是：如果配置得当，Token 消耗完全可控。

以下是影响 Token 消耗的主要因素：

一个经过优化的心跳配置（lightContext: true、活跃时间段 08:00 到 22:00、间隔 40 分钟），每天大约执行 21 次心跳。每次心跳的 Token 消耗远低于一次正常对话，月度总开销在可接受范围内。

5.3 心跳检查的内容可以自定义吗

当然可以。编辑工作区的 HEARTBEAT.md 文件，写入你想要智能体检查的内容即可。你可以随时修改这个文件，下一次心跳就会按照新的清单执行。

这意味着你可以根据不同阶段的需求灵活调整检查内容。项目冲刺期，可以加入"检查 CI 构建状态"；休假期间，可以简化为"只检查紧急邮件"。

5.4 心跳和定时任务可以一起用吗

可以，而且推荐一起用。心跳负责日常感知和智能判断，定时任务负责准时执行和一次性提醒。两者互补，能覆盖更广泛的自动化场景。具体的协同方案请参考上一节的内容。

5.5 如果心跳检查出错了怎么办

如果智能体在心跳检查中遇到错误（比如邮件服务器连不上），它会在响应中报告这个错误，系统会将错误信息发送给你。你可以根据错误内容排查问题。

常见的心跳错误及处理方法：

• 外部服务不可用（邮件、日历 API 超时）：检查网络连接和 API 密钥是否有效。如果问题持续，考虑暂时从 HEARTBEAT.md 中移除该检查项。
• Token 消耗异常偏高：检查是否启用了 lightContext，HEARTBEAT.md 是否过长，以及心跳间隔是否合理。
• 深夜收到心跳消息：检查 activeHours 配置是否正确，时区是否与你的实际位置匹配。

如果频繁出错，可以考虑调整检查内容或暂时关闭心跳。关闭心跳只需将 every 设为一个很大的值，或者直接删除心跳配置块。

6. 总结与进阶

6.1 本章核心知识回顾

心跳机制不是简单的定时器，而是一种以用户为中心的主动服务范式。它通过"周期性检查 + 智能判断"，在保持系统活跃的同时，最大限度减少打扰。

合理配置 HEARTBEAT.md、活跃时间段和投递策略，你就能构建一个既敏锐又克制的智能体：它知道什么时候该说话，更知道什么时候该沉默。好的自动化不是"做更多"，而是"在对的时候做对的事"。心跳机制，正是实现这一理念的关键工具。

6.2 课后练习

1. 基础配置：在你的 openclaw.json 中配置心跳机制，设置间隔为 30 分钟、活跃时间段为 08:00 到 22:00，并启用轻量上下文模式。验证配置是否生效。

2. 编写检查清单：创建一个 HEARTBEAT.md 文件，包含至少 3 个检查项。确保每个检查项都是具体的、有条件的（"如果...则..."格式）。观察几次心跳的执行结果，评估是否符合预期。

3. 成本对比实验：分别在开启和关闭 lightContext 的情况下运行心跳，对比两种模式的 Token 消耗差异。记录数据并分析哪种模式更适合你的使用场景。

4. 协同方案设计：设计一个完整的心跳 + 定时任务组合方案，覆盖以下需求：每天早上的晨报推送（定时任务）、白天的邮件和日历监控（心跳）、以及一次性提醒（定时任务）。写出配置和 HEARTBEAT.md 内容，并实际部署验证。

本章完

本文为《OpenClaw 实战指南》系列第 9 篇。更多技术细节与实践案例，欢迎关注个人技术站 openclaw.bjbook.net。