OpenClaw 框架深度指南
OpenClaw 是一个本地运行的自主 AI 代理框架,能通过 WhatsApp、Telegram 等聊天应用互动,并支持后台主动监控钱包、盯盘链上异动及发送警报。
其核心机制包括 Heartbeat(心跳清单) 和 Cron Jobs(定时任务)。合理配置可避免 Token 浪费、提醒重复及上下文污染。
第一部分:HEARTBEAT.md 是什么?
HEARTBEAT.md 是 OpenClaw 的核心配置文件之一(通常位于 workspace 根目录,如 ~/.openclaw/workspace/HEARTBEAT.md)。
作用
- 变被动为主动:Agent 每隔固定时间(默认 30 分钟)自动'心跳'一次。
- 指令注入:每次心跳读取 HEARTBEAT.md 中的 checklist,作为用户指令喂给模型。
- 智能过滤:模型判断有事则处理/提醒,没事则静默(输出
HEARTBEAT_OK,Gateway 自动吞掉消息)。
心跳原理(完整 Agent Turn)
- Gateway 定时触发心跳事件。
- 构建上下文:加载主会话历史 + SOUL.md(性格)+ AGENTS.md(规则)+ MEMORY.md(长期记忆)。
- 注入指令:将 HEARTBEAT.md 内容作为'用户消息'注入(Prompt 大意:'严格读 HEARTBEAT.md,跟随它检查,不要脑补旧任务。如果没事,回复 HEARTBEAT_OK')。
- 模型推理:可能调用工具(查邮箱、日历、链上、X、硬盘等)。
- 输出处理:
- 无事 →
HEARTBEAT_OK(静默)。 - 有事 → 总结/警报 → 通过 Target(Telegram 等)发送。
- 无事 →
- 记录存储:本次 Turn 的思考与工具结果存入主会话历史,避免重复。
一句话:心跳 = 自动给自己发一条带 HEARTBEAT.md 的消息,然后完整跑一次 Agent。带记忆、智能过滤,但频率过高会累积上下文并消耗 Token。
心跳与聊天的冲突处理
OpenClaw 使用 Lane Queue(通道队列) 设计,同一 Session 内所有任务严格串行:
- 用户消息:高优先级,插队到队列头部,优先处理。
- 心跳任务:低优先级,若主 Lane 忙(正在聊天或运行长任务),则排队等待。
- 体验:聊天零延迟;聊完后心跳紧接着执行,可能补充'刚才查到的大额转账警报'。
频率设置
在 config.json(路径通常为 ~/.openclaw/config/openclaw.json 或 gateway/config.json)中调整:
{
"agents": {
"defaults":

