1. 先搞清楚什么时候真的需要 SubagentOpenClaw 里的 Subagent子 Agent不是多开几个窗口这么简单它解决的是单 Agent 在上下文、工具权限和并行度上的硬瓶颈。我见过不少人一上来就把任务拆成五六个子 Agent结果调试成本比收益还高。所以第一步不是写配置而是判断这个任务到底该不该拆。判断标准其实很朴素如果单个 Agent 能在一次会话里把活干完且上下文不爆、工具不冲突那就别拆。真正需要 Subagent 的场景通常长这样——任务可以切成互不依赖的并行块比如同时抓三个数据源做竞品对比或者不同子任务需要完全不同的模型和工具集比如一个子任务要跑代码执行、另一个只做文本摘要再或者单次上下文塞不下所有素材必须分治后再汇总。OpenClaw 的多 Agent 协作走的是主从路线核心原语就两个sessions_spawn负责派活Announce 机制负责回传结果。父 Agent 有绝对控制权子 Agent 在自己的独立 session 里干活默认不会直接跟用户对话只向父 Agent 汇报。这个设计的好处是边界清晰坏处是你必须显式把上下文传过去不能指望子 Agent自己去看。下面这张表可以帮你快速判断场景特征建议方案原因单轮问答、简单查询单 Agent拆了反而增加调度开销3 个以上独立数据源并行抓取多 Subagent串行太慢并行收益明显子任务需要不同模型/工具权限多 Subagent单 Agent 的 prompt 会臃肿到难以维护上下文超过模型窗口 70%多 Subagent 分治避免截断和注意力稀释需要多轮追问同一子任务session 模式 Subagentrun 模式执行完就销毁接不住追问2. TaoToken 前置把模型接入这步先跑通Subagent 能不能用不同模型取决于你的接入层是否统一。我习惯把所有模型调用收敛到同一个入口这样父 Agent 和子 Agent 切换模型时只改配置不改代码。TaoToken 在这里扮演的就是这个统一入口的角色官网在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end API 地址是 https://taotoken.net/api 。你需要先拿到 API Key入口在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 。拿到之后建议先做一次最小连通性验证别等到 Subagent 跑起来才发现鉴权失败。验证命令如下curl -X POST https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: claude-sonnet-4-20250514, messages: [{role: user, content: reply with ok}], max_tokens: 16 }返回里能看到choices[0].message.content就说明链路通了。这一步别跳过后面 Subagent 报错时你才能快速排除是接入层问题还是编排层问题。如果你打算长期跑编码类或 Agent 类任务建议看一下 Coding Plan入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 它更适合高频调用的场景。模型对话的调试入口在 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。3. 可复制的 Subagent 配置骨架OpenClaw 的 Subagent 配置核心是三个字段mode、maxSpawnDepth、lane。mode决定子 Agent 执行完是销毁还是保留会话maxSpawnDepth控制嵌套深度lane做并发槽位隔离。下面是一份可以直接改的骨架配置# openclaw.subagent.yaml subagent: enabled: true maxSpawnDepth: 1 # 默认只允许一层防止无限扩散 defaultMode: run # run执行完销毁session保留会话 lane: name: default capacity: 5 # 同一 lane 最多同时跑 5 个子 Agent announce: idempotent: true # 回传带幂等 key防重复处理 timeoutMs: 120000 # 子 Agent 超时时间 models: default: claude-sonnet-4-20250514 overrides: code_task: claude-sonnet-4-20250514 summary_task: claude-haiku-3-5-20241022父 Agent 派活的调用形态大致如下注意prompt里必须把子任务需要的上下文显式带上因为子 Agent 的 session 跟父 Agent 是隔离的# 父 Agent 中派发子任务 result sessions_spawn( moderun, modelclaude-sonnet-4-20250514, lanedefault, prompt( 你是一个数据抓取子 Agent。 任务抓取以下三个仓库的 star 数和最近一次 commit 时间。 仓库列表repo_a, repo_b, repo_c。 只返回 JSON不要额外解释。 ) )如果你需要子 Agent 持续接收追加指令把mode改成session之后用/subagents send继续发消息。管理命令这块建议记牢/subagents list # 查看活跃子 Agent 及状态 /subagents kill id # 终止指定子 Agent /subagents send id msg # 给 session 模式子 Agent 追加消息 /subagents steer id new_task # 重定向任务maxSpawnDepth设成 2 时会变成编排者 工人两级结构适合大批量并行任务比如对 50 个仓库做代码审查编排者拆成 10 组、每组 5 个spawn 10 个工人 Agent 并行处理。但深度每加一层调试复杂度是指数上升的建议先用 1 跑通再考虑加。4. 验证请求与成功结果长什么样配置写完别急着上生产先跑一个最小验证。我一般用三个独立查询 汇总这个模式来验证整条链路因为它同时覆盖了并行派发、结果回传和汇总三个阶段。第一步父 Agent 派发三个子任务tasks [ sessions_spawn(moderun, lanedefault, prompt查询 A 数据源返回 JSON), sessions_spawn(moderun, lanedefault, prompt查询 B 数据源返回 JSON), sessions_spawn(moderun, lanedefault, prompt查询 C 数据源返回 JSON), ]第二步观察 Announce 回传。正常情况下你会看到类似这样的日志[announce] subagent_idsub_001 statussuccess idempotent_keyabc123 [announce] subagent_idsub_002 statussuccess idempotent_keydef456 [announce] subagent_idsub_003 statussuccess idempotent_keyghi789三个idempotent_key各不相同说明幂等机制在工作。如果同一个 key 出现两次说明回传被重复触发了这时候要检查announce.idempotent是否真的生效。第三步父 Agent 汇总。成功的结果应该是父 Agent 拿到三份 JSON 后合并输出而不是自己再去查一遍。如果你发现父 Agent 在子 Agent 返回后还在重复调用工具大概率是 prompt 里没写清楚收到回传后直接汇总。验证通过的标准很简单/subagents list里三个子 Agent 状态都变成completed父 Agent 的最终输出包含三份数据的合并结果且总耗时明显低于串行执行。5. 本篇常见错排查报错一spawn failed: lane capacity exceeded这是并发槽位打满。lane.capacity设的是 5你一次派了 8 个后 3 个会排队。解决办法要么调大 capacity要么在父 Agent 里做分批派发。别直接把 capacity 拉到 100资源打满后整个进程都会卡。报错二子 Agent 返回空结果或context missing九成是上下文没传全。子 Agent 的 session 跟父 Agent 隔离父 Agent context 里的东西它看不到。检查prompt里是否把必要的摘要信息带上了。注意是传摘要不是传原始数据原始数据太大反而会撑爆子 Agent 的上下文。报错三announce timeout子 Agent 执行超过timeoutMs还没回传。先看/subagents list里它的状态如果是running说明任务确实重调大超时如果是stuck说明子 Agent 卡住了用/subagents kill终止后重新派发。OpenClaw 本身没有自动重试重试逻辑要写在父 Agent 的 prompt 里。报错四子 Agent 重复回传同一结果检查announce.idempotent是否为true。如果已经是 true 还重复看是不是父 Agent 在收到回传后又 spawn 了一个相同任务的子 Agent。这种情况常见于父 Agent 的 prompt 没写清楚收到回传即停止派发。报错五maxSpawnDepth exceeded子 Agent 试图再创建子 Agent但maxSpawnDepth是 1。要么调成 2要么重新设计任务拆分让父 Agent 直接派发所有子任务而不是让子 Agent 再往下拆。6. 把多 Agent 用对的几个实操建议第一先用单 Agent 跑一遍任务记录上下文占用和耗时。如果上下文没超过模型窗口的 70%、耗时也能接受就别拆。拆分的收益必须大于调度开销否则就是负优化。第二子 Agent 的 prompt 要写得像给外包的工单输入是什么、输出格式是什么、边界在哪全部写清楚。模糊的 prompt 会让子 Agent 自由发挥回传的结果父 Agent 根本没法汇总。第三lane.capacity和maxSpawnDepth是两道防线前者防并发爆炸后者防嵌套爆炸。两个都要设别只设一个。第四session 模式的子 Agent 用完记得 kill不然它会一直占着 lane 槽位。我见过有人跑了一晚上没清理第二天发现 lane 全被僵尸子 Agent 占满了。如果你在接入层还没跑通先去 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 拿 Key再对照 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 的接入文档把基础调用验证一遍。模型对话调试用 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 长期跑编码和 Agent 任务建议上 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。Claude Code 相关的接入参考 https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaude_codeutm_campaignrewrite 控制台在 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 。最后一句实在话Subagent 的价值在并行和隔离不在数量。三个各司其职的子 Agent 比十个职责重叠的子 Agent 有用得多。先把一个子 Agent 的派发、执行、回传、汇总跑通再考虑加第二个。