1. 从一次“分身失控”说起nanobot 子智能体到底解决什么问题如果你正在找 openclaw 的平替方案大概率已经翻过 nanobot 的源码。前几篇我们拆了主循环、工具注册、消息总线这一篇专门聊最容易被忽略、但决定多任务协作上限的模块Subagents子智能体。简单说子智能体就是主 Agent 召唤出来的“分身”它能在后台独立跑一个耗时任务主 Agent meanwhile 继续和用户对话或者再召唤更多分身。适合谁适合那些想让本地 Agent 同时处理“搜集资料 生成封面 整理摘要”这类并行任务的开发者。我试过把 nanobot 的子智能体接到 TaoToken 的统一 Key 通道上发现配置骨架其实不复杂难的是理解它的任务分发和上下文隔离机制。源码里两个文件最关键nanobot/agent/tools/spawn.py定义了 spawn 工具是主 Agent 召唤分身的入口nanobot/agent/subagent.py里的SubagentManager负责生命周期管理。主 Agent 判断某个任务太复杂或太耗时就调用 spawn传入task任务描述和label任务标签Manager 生成唯一task_id用asyncio.create_task在后台启动异步任务。这意味着子智能体跑的时候主 Agent 不会被阻塞。但子智能体不是主 Agent 的克隆。它有自己的工具箱读写文件、执行 Shell、网页搜索都能用但它默认没有 spawn 工具不能再分身也没有 message 工具不能直接给用户发消息。它的 System Prompt 明确写着“你是被主 Agent 派去完成特定任务的子智能体保持专注”。说白了它就是一个没有人格、没有自我意识的工具人纯纯的牛马 Agent。结果怎么汇总靠 MessageBus。子智能体完成后调用_announce_result把结果封装成一条特殊的 System 消息发到总线的 inbound 队列主 Agent 像收到普通用户消息一样接收然后自然总结给用户。这套机制的精妙之处在于上下文隔离但结果回流。2. TaoToken 前置统一 Key 与 API 通道准备在跑通子智能体之前得先把模型调用通道理顺。nanobot 本身不绑定特定模型供应商它通过配置读取 API Key 和 Base URL。如果你本地同时跑多个 Agent 实例每个实例都去配不同的 Key 会很乱。TaoToken 在这里的作用是提供一个统一的 Key/API 通道让主 Agent 和子智能体共用同一套接入配置减少环境变量污染。你需要先拿到一个可用的 API Key。访问 TaoToken 的 API Keys 管理页面https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentsubagents_configutm_campaignrewrite 登录后创建一个新 Key复制保存。注意不要把它硬编码进源码后面我们用settings.json和环境变量来管理。TaoToken 的 API 入口是 https://taotoken.net/api 这个地址不加 UTM直接作为 Base URL 使用。如果你用的是 OpenAI 兼容的 SDKBase URL 填这个Key 填刚才生成的。模型名称按你实际订阅的填比如gpt-4o或claude-3-5-sonnet这类。子智能体和主 Agent 可以共用同一个 Key因为 TaoToken 的通道是按请求计费不限制并发来源。但要注意子智能体是异步并发的如果同时 spawn 多个请求会并行发出确认你的套餐并发额度够用。配置前建议先验证 Key 是否可用。用 curl 发一个最小请求curl -X POST https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: gpt-4o, messages: [{role: user, content: ping}], max_tokens: 10 }如果返回正常 JSON说明通道没问题。这一步别跳过后面子智能体报错时你能快速排除是 Key 问题还是源码问题。3. 可复制配置settings.json 骨架与 Subagents 参数nanobot 的配置通常放在项目根目录的settings.json或.nanobot/settings.json。下面是一个可复制的骨架重点看subagents段和llm段。我把它拆成三块模型通道、子智能体开关、工具权限。{ llm: { provider: openai-compatible, base_url: https://taotoken.net/api, api_key_env: TAOTOKEN_API_KEY, model: gpt-4o, max_tokens: 4096, temperature: 0.7 }, subagents: { enabled: true, max_concurrent: 3, default_timeout_seconds: 300, allow_spawn: false, allow_message: false, tools: [read_file, write_file, shell, web_search], system_prompt_extra: Stay focused on the assigned task. Report concisely. }, message_bus: { inbound_queue_size: 100, announce_prefix: [Subagent] } }逐项说明。llm.base_url填 TaoToken 的 API 地址api_key_env指向环境变量名这样 Key 不落盘。subagents.enabled是总开关设为 true 才会注册 spawn 工具。max_concurrent控制同时跑几个子智能体本地调试建议 2 到 3太多会抢模型并发。default_timeout_seconds是单个子任务超时超时后 Manager 会标记失败并 announce。allow_spawn和allow_message必须为 false这是防止无限套娃和子智能体直接打扰用户的关键。tools列表决定子智能体能调用哪些工具按需裁剪比如不需要 shell 就去掉。环境变量这样设export TAOTOKEN_API_KEYsk-你的实际Key如果你用.env文件确保 nanobot 启动时加载了它。源码里SubagentManager初始化时会读取settings.json的subagents段然后为每个子智能体构建独立的工具注册表和 System Prompt。注意system_prompt_extra会追加到子智能体的基础提示词后面你可以在这里强调输出格式比如“结果用 Markdown 列表返回”。还有一个隐藏参数origin。spawn 工具调用时会自动带上当前会话的channel和chat_id子智能体完成后_announce_result用这个 origin 把结果发回正确的会话。你不需要手动配但调试时要留意日志里的 origin 字段确认结果回流到了对的聊天窗口。4. 验证请求跑通一次子智能体协作流程配置写好后启动 nanobot。主 Agent 的入口通常是python -m nanobot或项目里的main.py。启动日志里应该能看到SubagentManager initialized和spawn tool registered。如果没有检查subagents.enabled是否为 true以及spawn.py是否在工具注册路径下。接下来触发一次 spawn。在对话里输入一个明确需要并行的任务比如“帮我搜集三个不同城市的天气然后分别生成一句话摘要。”主 Agent 判断这个任务可以拆分就会调用 spawn。你会在日志里看到类似SpawnTool invoked: task搜集北京天气 labelweather-beijing Subagent [weather-beijing] starting task Subagent [weather-beijing] completed successfully同时主 Agent 的思考日志和子智能体的执行日志会交织出现。这是因为asyncio的异步特性主 Agent 在等模型返回时事件循环切到子智能体执行子智能体等模型时又切回主 Agent。你可以在subagent.py的 while 循环内打一个断点观察子智能体的独立上下文。注意看调试控制台的 “Threads Variables”如果当前停在loop.py就是主 Agent停在subagent.py就是子智能体。验证结果回流子智能体完成后_announce_result会构造一条InboundMessagechannelsystemsender_idsubagentcontent里包含任务和结果并附带一句“Summarize this naturally for the user”。主 Agent 收到这条系统消息后会触发新一轮思考最终回复用户。你看到的用户侧消息应该是自然语言总结而不是原始的技术细节。如果主 Agent 直接把[Subagent xxx completed successfully]这种原文吐给用户说明announce_content里的指令没被遵循可以调低temperature或强化system_prompt_extra。想单独验证子智能体的模型通道是否走 TaoToken可以在subagent.py的模型调用处加一行日志打印base_url和model。确认输出是https://taotoken.net/api和你在 settings 里配的模型名。如果子智能体报 401大概率是环境变量没传进去因为子智能体是异步任务可能在新的事件循环里跑确保os.environ在进程启动时就设置好。5. 本篇常见错排查spawn 不触发、结果不回、并发冲突第一个坑spawn 工具没注册。现象是主 Agent 永远不调用 spawn即使任务很复杂。原因通常是subagents.enabled为 false或者spawn.py里的SpawnTool类没有被工具注册器扫描到。检查nanobot/agent/tools/__init__.py是否导入了 spawn以及 settings 里subagents段是否存在。另一个可能是主 Agent 的 System Prompt 里没有告知它可以使用 spawn你可以在主 Agent 的提示词里加一句“对于可并行的子任务使用 spawn 工具”。第二个坑子智能体跑完但用户没收到结果。先看日志有没有_announce_result的输出。如果没有说明子智能体异常退出或超时status不是ok。如果有 announce 但主 Agent 没反应检查message_bus.inbound_queue_size是否太小导致消息被丢弃或者主 Agent 的 inbound 消费循环是否在运行。还有一种情况origin里的chat_id格式不对导致消息发到了错误的会话。调试时打印origin字典确认。第三个坑并发数超限导致请求排队或失败。max_concurrent设得太大同时 spawn 多个子智能体TaoToken 通道可能返回 429。建议本地调试设为 2生产环境根据套餐并发调整。另外子智能体的default_timeout_seconds如果太短复杂任务会被截断结果里只有部分内容。可以适当调大到 600 秒但要注意主 Agent 的等待策略。第四个坑子智能体递归调用 spawn。虽然默认allow_spawn为 false但如果你手动改了工具列表把 spawn 加进了子智能体的tools就会无限套娃。日志里会看到Subagent [...] starting task不断嵌套。解决办法是严格保持allow_spawn: false并且不要在子智能体的工具注册里包含 spawn。第五个坑模型通道混用。主 Agent 和子智能体如果配了不同的 Base URL子智能体可能走了默认的 OpenAI 地址而不是 TaoToken。统一在llm段配置子智能体继承同一份配置。如果你需要子智能体用更便宜的模型可以在subagents段单独加model_override但 Base URL 和 Key 仍然走 TaoToken。6. 继续深入从子智能体到长期编码协作子智能体跑通后你会发现它特别适合“搜集 整理 生成”这类流水线任务。但如果你想让 Agent 长期驻留在编码环境里反复调用子智能体做代码审查、测试生成、依赖检查那就需要考虑更稳定的通道和额度管理。TaoToken 的 Coding Plan 提供了适合长期编码场景的套餐你可以在这里查看https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentsubagents_codingutm_campaignrewrite 。它和按量计费的 API Key 是两套体系按你的使用频率选。如果你只是想先验证子智能体的模型对话效果不想写代码可以直接在 TaoToken 的模型对话页面测试https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentsubagents_chatutm_campaignrewrite 。把子智能体的 System Prompt 贴进去模拟一个任务描述看模型返回是否符合“专注、简洁、不提及技术细节”的要求。这能帮你快速调提示词不用反复重启 nanobot。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentsubagents_docutm_campaignrewrite 里面有 OpenAI 兼容接口的详细参数和错误码说明。控制台在 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentsubagents_consoleutm_campaignrewrite 可以看请求量和余额。如果你用 Claude Code 或 Anthropic 风格的接口参考 https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentsubagents_claudeutm_campaignrewrite 。最后留一个实用技巧在subagent.py的_announce_result里把announce_content的“Keep it brief (1-2 sentences)”改成“Keep it brief (1-2 sentences). Include the label for reference.”这样主 Agent 总结时会带上任务标签方便你在多子智能体场景下对应结果。改完重启再跑一次三城市天气任务观察用户侧回复是否带上了weather-beijing这类标识。这个改动很小但调试多分身时非常省心。