【OpenClaw】通过 Nanobot 源码学习架构---（10）Heartbeat

📌 一句话摘要

本文深入分析了 Nanobot 框架中 HeartbeatService 组件的架构设计与实现，展示了如何通过 LLM 驱动的两阶段决策模式，用不到 200 行代码实现轻量级的周期性任务检测与执行。

📝 详细摘要

本文是「通过 Nanobot 源码学习架构」系列的第 10 篇，聚焦于 HeartbeatService 组件的设计与实现。文章首先介绍了 HeartbeatService 的整体作用：作为 Nanobot 的周期性任务检测与执行服务，它放弃传统的硬编码规则解析，改用 LLM 驱动的智能决策，基于 asyncio 实现轻量化的周期性调度。核心设计是两阶段执行模式：Phase 1 通过 LLM 虚拟工具调用分析 HEARTBEAT.md 内容，判断是否有活跃任务；Phase 2 仅在决策为「run」时触发，通过回调函数执行实际的 Agent 操作。文章详细分析了 _HEARTBEAT_TOOL 的设计逻辑、LLM 调用流程、与 AgentLoop 和 MessageBus 的配合机制，并与 OpenClaw 的 Claw0 和 ZeroClaw 架构进行了对比。最后展示了 HeartbeatService 的完整代码实现，包括生命周期管理、手动触发流程和回调机制。

💡 主要观点

- HeartbeatService 采用 LLM 驱动的两阶段执行模式，将决策与执行解耦。 Phase 1 通过 LLM 虚拟工具调用分析 HEARTBEAT.md 内容，返回 skip/run 决策；Phase 2 仅在决策为 run 时触发回调执行任务，实现了智能决策与执行逻辑的分离。

_HEARTBEAT_TOOL 虚拟工具的核心价值是约束 LLM 的输出格式。 通过定义标准化的工具调用 Schema，强制 LLM 按固定结构返回决策结果，避免了自由文本解析的不稳定性和 HEARTBEAT_OK 这类硬编码令牌的不可靠性。

HeartbeatService 通过回调机制实现灵活的解耦扩展。 on_execute 和 on_notify 回调函数将任务执行和结果推送逻辑与核心心跳服务解耦，无需修改核心代码即可适配不同的执行和推送策略。

用户消息始终优先于心跳任务，通过 Lane 互斥机制保证。 Claw0 架构中，用户线程阻塞获取锁，心跳线程非阻塞获取锁，确保用户交互不受后台心跳任务干扰。

💬 文章金句

- HeartbeatService 组件仅用不到 200 行代码就完成了 OpenClaw 同等核心的「定时唤醒 Agent 检查任务」能力。

Phase 1 (decision): reads HEARTBEAT.md and asks the LLM --- via a virtual tool call --- whether there are active tasks. This avoids free-text parsing and the unreliable HEARTBEAT_OK token.
LLM 被赋予的角色是「heartbeat agent」（心跳代理），其唯一职责是：读取 HEARTBEAT.md 内容；判断是否有活跃任务；按_HEARTBEAT_TOOL 的规范调用 heartbeat 工具，返回「skip/run」决策。
用户总是赢 (阻塞获取); 心跳让步 (非阻塞获取)。

📊 文章信息

AI 初评：86

来源：罗西的思考

作者：罗西的思考

分类：人工智能

语言：中文

阅读时间：41 分钟

字数：10110

标签： Nanobot, HeartbeatService, Agent 架构, LLM 工具调用, 两阶段执行

阅读完整文章

【OpenClaw】通过 Nanobot 源码学习架构---（10）Heartbeat

🤖 問 AI