1. 从一次“Agent 装死”说起Heartbeat 到底解决什么问题如果你玩过 OpenClaw 或者 Nanobot 这类个人 AI 助手框架大概率遇到过这种场景你给它布置了一个“每半小时看看服务器日志有没有报错”的任务然后关掉终端去干别的。等你两小时后回来发现它安安静静什么都没做。不是它不想做而是它根本不知道“时间到了该醒一醒”。这就是 Heartbeat 心跳机制要解决的核心问题让 Agent 从“被动应答”变成“主动巡检”。Nanobot 是香港大学数据科学实验室开源的超轻量级个人 AI 助手框架定位是“Ultra-Lightweight OpenClaw”非常适合拿来学 Agent 架构。它的 HeartbeatService 组件用不到 200 行代码就实现了 OpenClaw 同等核心的“定时唤醒 Agent 检查任务”能力。这篇文章我会带你从源码层面拆解 Heartbeat 的两阶段执行设计然后落到实操怎么用 TaoToken 的统一 Key/API 通道把心跳服务接起来给出可复制的settings.json、config.toml骨架以及 CC Switch、Cline 的配置片段。最后给一套验证动作和预期结果让你确认心跳真的在跑而不是“看起来在跑”。适合谁看正在学 Agent 架构、想给自己的助手加定时任务能力、或者被“Agent 不主动干活”困扰的开发者。读完你能自己搭一个最小可用的心跳服务并且知道每一步为什么这么设计。2. 前置准备TaoToken 统一 Key 与 API 通道在动手改配置之前先把模型调用这条链路理顺。Heartbeat 的 Phase 1 决策阶段需要调用 LLMPhase 2 执行阶段走完整的 Agent Loop同样要调模型。如果每个环节都单独配一套 Key维护起来会很痛苦。TaoToken 的思路是提供一个统一的 API 通道你只需要一个 Key就能在多个客户端和框架之间复用。先拿到你的 API Key。访问控制台创建https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentheartbeat_consoleutm_campaignrewrite创建完 Key 之后在 API Keys 页面可以查看和管理https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentheartbeat_apikeysutm_campaignrewrite这里有个细节要注意TaoToken 的 API 端点是不带 UTM 参数的统一用https://taotoken.net/api。你在配置文件里填 Base URL 的时候直接写这个就行别把带?utm_source的官网地址填进去否则请求会 404。我见过有人把浏览器地址栏的链接直接复制到base_url里排查了半天才发现问题。注意API Key 属于敏感凭证不要提交到 Git 仓库。建议放在环境变量或者本地未跟踪的配置文件里。如果你还没决定用哪个模型可以先去模型对话页面试一下确认通道通畅再写进配置https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_contentheartbeat_modelchatutm_campaignrewrite对于长期跑心跳任务的场景比如你要让 Agent 每隔 30 分钟巡检一次建议了解一下 Coding Plan它在持续调用场景下更划算https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentheartbeat_codingplanutm_campaignrewrite接入文档在这里配置项有疑问可以对照查https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentheartbeat_docutm_campaignrewrite3. 可复制配置settings.json 与 config.toml 骨架Nanobot 的配置分两层一层是模型 Provider 的接入配置一层是 Gateway 里 Heartbeat 的行为配置。下面给的是骨架你按自己的路径和 Key 替换即可。3.1 settings.jsonProvider 接入骨架这个文件负责告诉框架“用哪个 API 通道、哪个模型”。关键字段是base_url和api_key{ provider: { name: taotoken, base_url: https://taotoken.net/api, api_key: sk-你的TaoToken密钥, model: claude-sonnet-4-20250514, timeout: 60, max_retries: 3 }, workspace: /Users/yourname/nanobot-workspace, log_level: INFO }base_url必须是https://taotoken.net/api不要带路径后缀。model字段填你在模型对话页面确认可用的模型名。workspace是工作目录HEARTBEAT.md就放在这个目录的根下。3.2 config.tomlHeartbeat 行为配置Gateway 层的心跳配置决定“多久醒一次、在哪些时段醒”[gateway.heartbeat] enabled true interval_s 1800 active_hours [8, 23] [gateway.cron] enabled false [gateway.channels] enabled [cli, telegram]interval_s 1800就是 30 分钟一次。active_hours [8, 23]表示只在早上 8 点到晚上 11 点之间触发避免半夜把你叫醒。这个时段判断在源码里是这么实现的hour datetime.now().hour s, e self.active_hours in_hours (s hour e) if s e else not (e hour s) if not in_hours: return False, foutside active hours ({s}:00-{e}:00)注意它处理了跨天的情况如果s e比如[22, 6]判断逻辑会反过来。这个细节很多人配的时候会踩坑。3.3 CC Switch 配置片段如果你用 CC Switch 管理多个 Provider可以加一个 TaoToken 的 profile{ profiles: { taotoken-heartbeat: { base_url: https://taotoken.net/api, api_key: sk-你的TaoToken密钥, model: claude-sonnet-4-20250514, description: TaoToken 统一通道 - 心跳任务专用 } } }3.4 Cline 配置片段Cline 里选 “OpenAI Compatible”然后填{ apiProvider: openai, openAiBaseUrl: https://taotoken.net/api, openAiApiKey: sk-你的TaoToken密钥, openAiModelId: claude-sonnet-4-20250514 }Cline 的配置界面里 Base URL 那一栏容易填错记住是https://taotoken.net/api不是官网首页。4. 验证请求确认心跳真的在跑配置写完不代表心跳在工作。你需要一套验证动作从“文件被读取”到“LLM 被调用”再到“结果被推送”逐层确认。4.1 准备 HEARTBEAT.md在工作目录根下创建HEARTBEAT.md内容如下# Heartbeat Tasks This file is checked every 30 minutes by your nanobot agent. ## Active Tasks - [ ] 检查 /var/log/app.log 最近 100 行是否有 ERROR - [ ] 确认磁盘使用率是否超过 85% ## Completed注意如果这个文件只有标题和注释、没有实际任务条目心跳会直接跳过。源码里的判断是读取内容后如果为空就返回所以你得至少留一条未完成的任务。4.2 手动触发一次心跳不用等 30 分钟Nanobot 提供了trigger_now()方法。你可以在 REPL 里调用或者写个小脚本import asyncio from nanobot.gateway import build_gateway async def main(): gateway await build_gateway(config.toml) result await gateway.heartbeat.trigger_now() print(心跳执行结果:, result) asyncio.run(main())预期结果如果HEARTBEAT.md里有活跃任务trigger_now()会返回 Agent 执行后的文本结果如果没任务返回None。4.3 观察日志输出正常的心跳周期日志长这样INFO Heartbeat started (every 1800s) INFO Heartbeat: checking for tasks... INFO Heartbeat: tasks found, executing... INFO Heartbeat: completed, delivering response如果看到的是INFO Heartbeat: OK (nothing to report)说明 Phase 1 的 LLM 决策返回了skip也就是它认为没有活跃任务。这时候去检查HEARTBEAT.md是不是只有标题没有条目。4.4 验证 Phase 1 的工具调用想确认 LLM 真的按_HEARTBEAT_TOOL的规范返回了结构化决策可以在_decide方法里临时加一行日志response await self.provider.chat( messagesmessages, tools_HEARTBEAT_TOOL, modelself.model, ) logger.info(工具调用结果: {}, response.tool_calls)预期看到类似这样的结构[{name: heartbeat, arguments: {action: run, tasks: 检查日志错误和磁盘使用率}}]如果has_tool_calls是False说明模型没有按预期调用工具。常见原因是模型不支持 function calling或者系统提示被截断了。5. 本篇常见错排查5.1 心跳一直 skip明明有任务先看HEARTBEAT.md的路径对不对。源码里heartbeat_file是workspace / HEARTBEAT.md如果你把文件放在了子目录里它读不到。另外检查文件编码必须是 UTF-8源码里写死了encodingutf-8。还有一种情况任务条目被写成了- [x]已完成。虽然 Nanobot 的 LLM 决策不像 MimiClaw 那样硬编码过滤- [x]但模型看到已完成标记大概率会返回skip。5.2 报错 “outside active hours”这是active_hours配置和当前时间不匹配。比如你配了[8, 23]但现在是凌晨 2 点心跳就会跳过。调试阶段建议先把active_hours设成[0, 24]确认链路通了再收紧。5.3 API 请求 404 或 401404 通常是base_url填错了。检查是不是填成了https://taotoken.net或者带了/v1后缀。正确值是https://taotoken.net/api。401 是 Key 无效或过期。去 API Keys 页面重新生成一个注意复制的时候别漏字符。如果 Key 里包含特殊字符在 JSON 里要确保转义正确。5.4 心跳执行了但收不到通知on_notify回调依赖_pick_heartbeat_target()选出一个可路由的渠道。如果所有 session 都是cli或system它会 fallback 到(cli, direct)而on_heartbeat_notify里有一句if channel cli: return # No external channel available to deliver to也就是说没有配置外部渠道比如 Telegram时心跳结果不会推送出来。你需要先在config.toml的gateway.channels.enabled里加上一个真实渠道。5.5 两阶段执行卡在 Phase 2Phase 2 调用on_execute而on_execute指向agent.process_direct()。如果 Agent Loop 本身有问题比如工具注册失败、上下文构建异常心跳会卡住。排查方法是单独调一次process_direct()看能不能正常返回。源码里_tick的异常捕获是logger.exception(Heartbeat execution failed)去看完整堆栈。6. 把心跳接进你的工作流Heartbeat 的价值不在于“定时”本身而在于它把决策权交给了 LLM。传统的 cron 是硬编码规则你写什么它执行什么Heartbeat 是让模型读自然语言描述的任务自己判断该不该动。这个设计让 Agent 从“工具”变成了“助手”。实际用的时候我建议把HEARTBEAT.md当成一个“待办清单”来维护。Agent 自己也能通过edit_file、write_file这些文件工具更新它所以你甚至可以让它自己往里加任务。比如你跟它说“以后每天检查一下备份有没有跑”它会把这个写成周期性任务而不是创建一个一次性提醒。配置层面TaoToken 的统一通道省去了多客户端分别配 Key 的麻烦。一个 Key 同时给 Nanobot、Cline、CC Switch 用Base URL 都是https://taotoken.net/api。如果你要跑长期心跳任务Coding Plan 在持续调用场景下更合适如果只是验证模型通不通模型对话页面点几下就能确认。最后留一个实操建议先把interval_s设成 60 秒active_hours设成[0, 24]手动触发一次确认全链路通了再改回 30 分钟和正常时段。这样调试效率最高也不容易在“等半小时”里消耗耐心。
【OpenClaw】通过 Nanobot 源码学习架构---（10）Heartbeat 心跳机制与 TaoToken 配置实战
1. 从一次“Agent 装死”说起Heartbeat 到底解决什么问题如果你玩过 OpenClaw 或者 Nanobot 这类个人 AI 助手框架大概率遇到过这种场景你给它布置了一个“每半小时看看服务器日志有没有报错”的任务然后关掉终端去干别的。等你两小时后回来发现它安安静静什么都没做。不是它不想做而是它根本不知道“时间到了该醒一醒”。这就是 Heartbeat 心跳机制要解决的核心问题让 Agent 从“被动应答”变成“主动巡检”。Nanobot 是香港大学数据科学实验室开源的超轻量级个人 AI 助手框架定位是“Ultra-Lightweight OpenClaw”非常适合拿来学 Agent 架构。它的 HeartbeatService 组件用不到 200 行代码就实现了 OpenClaw 同等核心的“定时唤醒 Agent 检查任务”能力。这篇文章我会带你从源码层面拆解 Heartbeat 的两阶段执行设计然后落到实操怎么用 TaoToken 的统一 Key/API 通道把心跳服务接起来给出可复制的settings.json、config.toml骨架以及 CC Switch、Cline 的配置片段。最后给一套验证动作和预期结果让你确认心跳真的在跑而不是“看起来在跑”。适合谁看正在学 Agent 架构、想给自己的助手加定时任务能力、或者被“Agent 不主动干活”困扰的开发者。读完你能自己搭一个最小可用的心跳服务并且知道每一步为什么这么设计。2. 前置准备TaoToken 统一 Key 与 API 通道在动手改配置之前先把模型调用这条链路理顺。Heartbeat 的 Phase 1 决策阶段需要调用 LLMPhase 2 执行阶段走完整的 Agent Loop同样要调模型。如果每个环节都单独配一套 Key维护起来会很痛苦。TaoToken 的思路是提供一个统一的 API 通道你只需要一个 Key就能在多个客户端和框架之间复用。先拿到你的 API Key。访问控制台创建https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentheartbeat_consoleutm_campaignrewrite创建完 Key 之后在 API Keys 页面可以查看和管理https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentheartbeat_apikeysutm_campaignrewrite这里有个细节要注意TaoToken 的 API 端点是不带 UTM 参数的统一用https://taotoken.net/api。你在配置文件里填 Base URL 的时候直接写这个就行别把带?utm_source的官网地址填进去否则请求会 404。我见过有人把浏览器地址栏的链接直接复制到base_url里排查了半天才发现问题。注意API Key 属于敏感凭证不要提交到 Git 仓库。建议放在环境变量或者本地未跟踪的配置文件里。如果你还没决定用哪个模型可以先去模型对话页面试一下确认通道通畅再写进配置https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_contentheartbeat_modelchatutm_campaignrewrite对于长期跑心跳任务的场景比如你要让 Agent 每隔 30 分钟巡检一次建议了解一下 Coding Plan它在持续调用场景下更划算https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentheartbeat_codingplanutm_campaignrewrite接入文档在这里配置项有疑问可以对照查https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentheartbeat_docutm_campaignrewrite3. 可复制配置settings.json 与 config.toml 骨架Nanobot 的配置分两层一层是模型 Provider 的接入配置一层是 Gateway 里 Heartbeat 的行为配置。下面给的是骨架你按自己的路径和 Key 替换即可。3.1 settings.jsonProvider 接入骨架这个文件负责告诉框架“用哪个 API 通道、哪个模型”。关键字段是base_url和api_key{ provider: { name: taotoken, base_url: https://taotoken.net/api, api_key: sk-你的TaoToken密钥, model: claude-sonnet-4-20250514, timeout: 60, max_retries: 3 }, workspace: /Users/yourname/nanobot-workspace, log_level: INFO }base_url必须是https://taotoken.net/api不要带路径后缀。model字段填你在模型对话页面确认可用的模型名。workspace是工作目录HEARTBEAT.md就放在这个目录的根下。3.2 config.tomlHeartbeat 行为配置Gateway 层的心跳配置决定“多久醒一次、在哪些时段醒”[gateway.heartbeat] enabled true interval_s 1800 active_hours [8, 23] [gateway.cron] enabled false [gateway.channels] enabled [cli, telegram]interval_s 1800就是 30 分钟一次。active_hours [8, 23]表示只在早上 8 点到晚上 11 点之间触发避免半夜把你叫醒。这个时段判断在源码里是这么实现的hour datetime.now().hour s, e self.active_hours in_hours (s hour e) if s e else not (e hour s) if not in_hours: return False, foutside active hours ({s}:00-{e}:00)注意它处理了跨天的情况如果s e比如[22, 6]判断逻辑会反过来。这个细节很多人配的时候会踩坑。3.3 CC Switch 配置片段如果你用 CC Switch 管理多个 Provider可以加一个 TaoToken 的 profile{ profiles: { taotoken-heartbeat: { base_url: https://taotoken.net/api, api_key: sk-你的TaoToken密钥, model: claude-sonnet-4-20250514, description: TaoToken 统一通道 - 心跳任务专用 } } }3.4 Cline 配置片段Cline 里选 “OpenAI Compatible”然后填{ apiProvider: openai, openAiBaseUrl: https://taotoken.net/api, openAiApiKey: sk-你的TaoToken密钥, openAiModelId: claude-sonnet-4-20250514 }Cline 的配置界面里 Base URL 那一栏容易填错记住是https://taotoken.net/api不是官网首页。4. 验证请求确认心跳真的在跑配置写完不代表心跳在工作。你需要一套验证动作从“文件被读取”到“LLM 被调用”再到“结果被推送”逐层确认。4.1 准备 HEARTBEAT.md在工作目录根下创建HEARTBEAT.md内容如下# Heartbeat Tasks This file is checked every 30 minutes by your nanobot agent. ## Active Tasks - [ ] 检查 /var/log/app.log 最近 100 行是否有 ERROR - [ ] 确认磁盘使用率是否超过 85% ## Completed注意如果这个文件只有标题和注释、没有实际任务条目心跳会直接跳过。源码里的判断是读取内容后如果为空就返回所以你得至少留一条未完成的任务。4.2 手动触发一次心跳不用等 30 分钟Nanobot 提供了trigger_now()方法。你可以在 REPL 里调用或者写个小脚本import asyncio from nanobot.gateway import build_gateway async def main(): gateway await build_gateway(config.toml) result await gateway.heartbeat.trigger_now() print(心跳执行结果:, result) asyncio.run(main())预期结果如果HEARTBEAT.md里有活跃任务trigger_now()会返回 Agent 执行后的文本结果如果没任务返回None。4.3 观察日志输出正常的心跳周期日志长这样INFO Heartbeat started (every 1800s) INFO Heartbeat: checking for tasks... INFO Heartbeat: tasks found, executing... INFO Heartbeat: completed, delivering response如果看到的是INFO Heartbeat: OK (nothing to report)说明 Phase 1 的 LLM 决策返回了skip也就是它认为没有活跃任务。这时候去检查HEARTBEAT.md是不是只有标题没有条目。4.4 验证 Phase 1 的工具调用想确认 LLM 真的按_HEARTBEAT_TOOL的规范返回了结构化决策可以在_decide方法里临时加一行日志response await self.provider.chat( messagesmessages, tools_HEARTBEAT_TOOL, modelself.model, ) logger.info(工具调用结果: {}, response.tool_calls)预期看到类似这样的结构[{name: heartbeat, arguments: {action: run, tasks: 检查日志错误和磁盘使用率}}]如果has_tool_calls是False说明模型没有按预期调用工具。常见原因是模型不支持 function calling或者系统提示被截断了。5. 本篇常见错排查5.1 心跳一直 skip明明有任务先看HEARTBEAT.md的路径对不对。源码里heartbeat_file是workspace / HEARTBEAT.md如果你把文件放在了子目录里它读不到。另外检查文件编码必须是 UTF-8源码里写死了encodingutf-8。还有一种情况任务条目被写成了- [x]已完成。虽然 Nanobot 的 LLM 决策不像 MimiClaw 那样硬编码过滤- [x]但模型看到已完成标记大概率会返回skip。5.2 报错 “outside active hours”这是active_hours配置和当前时间不匹配。比如你配了[8, 23]但现在是凌晨 2 点心跳就会跳过。调试阶段建议先把active_hours设成[0, 24]确认链路通了再收紧。5.3 API 请求 404 或 401404 通常是base_url填错了。检查是不是填成了https://taotoken.net或者带了/v1后缀。正确值是https://taotoken.net/api。401 是 Key 无效或过期。去 API Keys 页面重新生成一个注意复制的时候别漏字符。如果 Key 里包含特殊字符在 JSON 里要确保转义正确。5.4 心跳执行了但收不到通知on_notify回调依赖_pick_heartbeat_target()选出一个可路由的渠道。如果所有 session 都是cli或system它会 fallback 到(cli, direct)而on_heartbeat_notify里有一句if channel cli: return # No external channel available to deliver to也就是说没有配置外部渠道比如 Telegram时心跳结果不会推送出来。你需要先在config.toml的gateway.channels.enabled里加上一个真实渠道。5.5 两阶段执行卡在 Phase 2Phase 2 调用on_execute而on_execute指向agent.process_direct()。如果 Agent Loop 本身有问题比如工具注册失败、上下文构建异常心跳会卡住。排查方法是单独调一次process_direct()看能不能正常返回。源码里_tick的异常捕获是logger.exception(Heartbeat execution failed)去看完整堆栈。6. 把心跳接进你的工作流Heartbeat 的价值不在于“定时”本身而在于它把决策权交给了 LLM。传统的 cron 是硬编码规则你写什么它执行什么Heartbeat 是让模型读自然语言描述的任务自己判断该不该动。这个设计让 Agent 从“工具”变成了“助手”。实际用的时候我建议把HEARTBEAT.md当成一个“待办清单”来维护。Agent 自己也能通过edit_file、write_file这些文件工具更新它所以你甚至可以让它自己往里加任务。比如你跟它说“以后每天检查一下备份有没有跑”它会把这个写成周期性任务而不是创建一个一次性提醒。配置层面TaoToken 的统一通道省去了多客户端分别配 Key 的麻烦。一个 Key 同时给 Nanobot、Cline、CC Switch 用Base URL 都是https://taotoken.net/api。如果你要跑长期心跳任务Coding Plan 在持续调用场景下更合适如果只是验证模型通不通模型对话页面点几下就能确认。最后留一个实操建议先把interval_s设成 60 秒active_hours设成[0, 24]手动触发一次确认全链路通了再改回 30 分钟和正常时段。这样调试效率最高也不容易在“等半小时”里消耗耐心。
