OpenClaw多智能体协作与工具实现深度解析

一、Sub-Agent的注册与调用

1.1 Sub-Agent的本质

Sub-Agent不是独立的Agent，而是主Agent派生出来的后台任务。它运行在自己的会话里，会话key长这样：agent:<agentId>: subagent:<uuid>。注意这个 key 结构，它明确标识了这是一个子代理，而不是顶级 Agent。

Sub-Agent最大的价值是隔离。主Agent的上下文不会被子任务污染，子Agent跑完以后把结果汇报回来，主Agent再决定下一步。

// 调用 sessions_spawn 启动子代理{  tool:'sessions_spawn',  input:{    task:"帮我查一下 Rust 和 Go 在并发性能上的对比",    label:"rust-vs-go-research",// 方便后续追踪    agentId:"worker",// 指定用哪个 Agent 配置    model:"anthropic/claude-sonnet-4-5",// 可以单独指定模型    runTimeoutSeconds:300,    thread:true// 是否绑定到频道线程  }}

1.2 权限控制

Agent之间如何知道谁能调用谁？默认情况下，Agent间通信是关闭的，必须手动启用。

{"tools":{    "agentToAgent":{      "enabled":true,      "allow":["main","worker","researcher"]    }  }}

allow 数组定义了哪些Agent ID可以被 sessions_spawn 调用。如果这里没配对，即使代码写了也白搭，你会看到agentId is not allowed for sessions_spawn错误。

1.3 子Agent能用什么工具

默认情况下，子Agent能用除了会话工具之外的所有工具。这是有意的设计，因为子Agent只是被当成一个后台任务来运行，不应该能操控其他会话。

但如果你启用了嵌套子Agent（maxSpawnDepth >= 2），depth-1的子Agent会额外获得 sessions_spawn、subagents、sessions_list、sessions_history，只有这样它才能管理自己的子任务。

{"agents":{    "defaults":{      "subagents":{        "maxSpawnDepth":2,//允许两层嵌套        "maxChildrenPerAgent":5//每个Agent最多同时跑5个子任务      }    }  }}

不同深度级别的Agent工具差异如下：

深度	会话 key 模式	角色	能否spawn
0	`agent:<id>: main`	主 Agent	永远可以
1	`agent:<id>: subagent:<uuid>`	子 Agent	仅当 maxSpawnDepth >= 2
2	`agent:<id>: subagent:<uuid>: subagent:<uuid>`	孙子 Agent	永远不行

1.4 子Agent结果回传机制

子Agent跑完后不会自动消失，它会执行一个announce步骤，把结果汇报给调用者。

Depth-2叶子完成 → 汇报给 depth-1父节点depth-1父节点收到 → 整合结果 → 汇报给主Agent主Agent收到 →组织语言 →发给用户

每个层级只看到直接子节点发回来的announce，消息末尾会带一行统计信息：

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━🧹Runs:1(0 succeeded,1 failed)⏱️Duration:2m34s📝Tokens:12.3K(in:8.1K,out:4.2K)━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

1.5 线程绑定

默认情况下，子Agent跑完就结束了，但如果开了 thread: true，子Agent会绑定到频道的某个线程上，后续在这个线程里的跟进消息会继续路由到这个子Agent会话。

{tool:'sessions_spawn',  input:{    task:"帮我重构这个 API",    thread:true,    mode:"session"  }}

用户可以用 /focus <label> 手动切换当前线程绑定，用 /unfocus 解绑，用 /session ttl 查看或修改自动解绑时间。

二、工具系统的实现

2.1 工具组装过程

Agent每个Turn能看到哪些工具，不是一成不变的，这是一个层层过滤的过程：

原始工具列表↓来源合并（pi-coding-agent 的 codingTools +OpenClaw原生工具）    ↓Schema规范化（处理不同 provider 的兼容性quirks）    ↓策略管道应用（全局→Agent→沙箱→Provider）    ↓前后置钩子包装（loop detection、before/after hook）    ↓最终工具列表→发送给模型

工具来自两个地方：

1. pi-coding-agent 的 codingTools：read、bash、edit、write 这些基础工具
2. OpenClaw原生工具：在 src/agents/openclaw-tools.ts 里定义的所有其他工具

2.2 Schema规范化

不同模型提供商对工具schema的要求不一样。OpenClaw在发送前会做一轮清理，比如：

• 某些provider要求参数顺序
• 某些provider不支持特定参数类型
• 某些provider对描述字段长度有限制

这个规范化在 pi-tool-definition-adapter.ts 里处理。最关键的适配是执行签名的转换：

// pi-agent-core 的 AgentTool 签名execute(toolCallId:string,params:any,signal:AbortSignal, onUpdate?:()=>void)// pi-coding-agent 的 ToolDefinition 签名execute(toolCallId:string,params:any,onUpdate:()=>void,ctx:any,signal:AbortSignal)

2.3 策略管道

工具最终能不能用，由多层策略决定，应用顺序如下：

1. 全局策略：tools.allow / tools.deny
2. Agent 策略：agents.list[].tools.allow / deny
3. 沙箱策略：沙箱模式下的额外限制
4. Provider 策略：tools.byProvider 对特定模型的额外限制

每一层都只能收紧工具集，不能放宽。

{"tools":{    "allow":["read","write","exec"],//全局允许这些    "deny":["gateway"]//全局禁止这些  },  "agents":{    "list":[{      "id":"restricted",      "tools":{        "deny":["exec"]//这个Agent额外禁止 exec      }    }]  },  "tools":{    "byProvider":{      "google-gemini-2-0-flash":{        "deny":["browser"]//Gemini模型禁用浏览器工具      }    }  }}

最终这个「restricted」Agent用Gemini 2.0 Flash模型时，只剩下 read 和 write工具可用，exec 被全局禁了，而browser 被 provider策略禁了。

2.4 简化配置的工具组

在OpenClaw的设计中，写一长串工具名很麻烦，可以用组名进行简化。

组名	包含工具
`group: runtime`	exec, bash, process
`group: fs`	read, write, edit, apply_patch
`group: sessions`	sessions_list, sessions_history, sessions_send, sessions_spawn, session_status
`group: memory`	memory_search, memory_get
`group: web`	web_search, web_fetch
`group: ui`	browser, canvas
`group: automation`	cron, gateway
`group: messaging`	message
`group: nodes`	nodes
`group: openclaw`	所有内置 OpenClaw 工具

有了上述定义好的工具组，工具禁用同样可以使用简化的写法：

{"tools":{"deny":["group:runtime","group:automation"]}}

2.5 工具结果返回

工具执行完后，结果以特定格式返回给模型。

// 成功结果{  role:"tool_result",  tool_use_id:"toolu_xxx",  content:[    {type:"text",text:"文件内容..."}  ]}// 错误结果{  role:"tool_result",  tool_use_id:"toolu_xxx",  content:[    {type:"text",text:"Error: 文件不存在"}  ]}

注意这里没有 isError 字段，所以模型需要从文本内容判断是否出错，这也是为什么模型有时候会忽略错误继续尝试。

长时间运行的会话，工具结果可能会持续膨胀。OpenClaw在持久化时会裁剪结果中的 schema字段，只保留实际数据。

// 持久化前{result: "data",schema:{/* huge schema */},$schema:"http://..."}// 持久化后{result: "data"}

这能显著减少session文件大小和token的消耗。

2.6 工具循环限制

如果模型连续多次调用同一个工具、读同一个文件、执行同一个命令，这通常是陷入了无效循环，OpenClaw 可以在检测到这种情况时自动干预。

{"tools":{  "loopDetection":{    "enabled":true,    "maxConsecutiveCalls":3,    "maxSameFileReads":5  } }}

触发后会注入一个提示告诉模型「你已经对这个文件操作 N 次了」，让它换个思路处理，不要陷入死循环。

三、总结

之前也分析了很多Agent的框架，不难发现，多Agent协作从本质上来看就是个金字塔架构，顶层指挥，中间调度，底层干活，各层各管各的事。主Agent派个任务下去，子Agent在自己的一亩三分地里折腾，折腾完了举举手说「我好了」，主Agent再把结果拿走。但这套架构能运转起来，靠的是一堆看不见的细节，比如工具的权限怎么设计、工具是否可以嵌套使用、Agent消息如何回传等等，如果细节设计不合理，配出来的东西要么转不起来，要么转起来全是bug。

总之，多Agent这东西，设计好了是生产力，设计不好就是灾难。与其盲目抄配置，不如先把背后的门道搞清楚，再根据实际需求决定如何设计，省得一路踩坑。

你好，我是William，一名喜欢折腾的程序员。曾担任大厂算法工程师，现在初创公司做AI应用全栈开发。

工作内容与兴趣点集中于大模型、Agent、RAG、文档智能等方向，平常也会介绍有趣的开源工作，欢迎围观。

如果本文对您有帮助，可以来个点赞、在看、关注，或者转发到您的朋友圈。