OpenClaw：多 Agent 隔离 + Subagent 四大协作模块

生产环境我没有实战过多Agent执行方面的内容，最近看了一下OpenClaw的信息，收获还是挺多的。以前了解的都比较碎片化，但人家设计的已经比较系统了。

一、前置核心结论

隔离是协作的前提

所有 Agent 天然完全隔离，杜绝文件冲突、上下文污染、权限越界；正因 Agent 互相隔绝，才需要 Spawn/Registry/Control/Announce 四大模块搭建通信桥梁，实现安全可控的多智能体协同。

二、三层 Agent 隔离体系（协作安全底座）

2.1三层强制隔离边界

1. Workspace 工作空间隔离：每个 Agent 专属独立文件目录，Shell 工具强制路径校验，禁止跨目录访问敏感配置，限制子 Agent 的数据访问范围。

2. agentDir 私有目录隔离：独立存储运行状态、密钥凭证、缓存配置，多 Agent 并行运行时状态互不干扰，杜绝密钥泄露。

3. tools/model 能力配置隔离：遵循最小权限，不同 Agent 绑定专属模型、工具集；翻译子 Agent 仅开放读取 / 搜索能力，禁止 Shell 执行。

2.1配置隔离规则

依靠 resolveAgentConfig() 实现配置解析：

显式配置 > 父配置继承 > 系统默认配置；

子 Agent 可继承父模型配置、单独覆盖工具权限，兼顾复用与定制。

三、Subagent 四大核心模块（协作完整生命周期）

整体流转链路：Spawn 创建子 Agent → Registry 登记户籍 → Control 运行调控 → Announce 结果回传

生产环境我没有实战过多Agent执行方面的内容，最近看了一下OpenClaw的信息，收获还是挺多的。以前了解的都比较碎片化，但人家设计的已经比较系统了。

一、前置核心结论

隔离是协作的前提

所有 Agent 天然完全隔离，杜绝文件冲突、上下文污染、权限越界；正因 Agent 互相隔绝，才需要 Spawn/Registry/Control/Announce 四大模块搭建通信桥梁，实现安全可控的多智能体协同。

二、三层 Agent 隔离体系（协作安全底座）

2.1三层强制隔离边界

1. Workspace 工作空间隔离：每个 Agent 专属独立文件目录，Shell 工具强制路径校验，禁止跨目录访问敏感配置，限制子 Agent 的数据访问范围。

2. agentDir 私有目录隔离：独立存储运行状态、密钥凭证、缓存配置，多 Agent 并行运行时状态互不干扰，杜绝密钥泄露。

3. tools/model 能力配置隔离：遵循最小权限，不同 Agent 绑定专属模型、工具集；翻译子 Agent 仅开放读取 / 搜索能力，禁止 Shell 执行。

2.1配置隔离规则

依靠 resolveAgentConfig() 实现配置解析：

显式配置 > 父配置继承 > 系统默认配置；

子 Agent 可继承父模型配置、单独覆盖工具权限，兼顾复用与定制。

三、Subagent 四大核心模块（协作完整生命周期）

整体流转链路：Spawn 创建子 Agent → Registry 登记户籍 → Control 运行调控 → Announce 结果回传

3.1 Spawn 模块：Subagent 生成器（负责「诞生」）

核心职责：安全创建隔离子 Agent，管控创建权限，防止资源雪崩。

两种运行模式

• Run 模式（任务型）：子 Agent 执行单次任务，结束立刻销毁，适合代码分析、文档翻译。

• Session 模式（会话型）：子 Agent 长期存活，支持多轮交互，适合持续监控、多轮问答。

两类沙箱权限策略

• Inherit：继承父 Agent 全部权限，父子任务联动场景使用。

• Require：子 Agent 必须主动申请权限，严格最小权限，安全性更高。

9 步生成流程

参数校验 → 嵌套深度校验 → 子 Agent 数量校验 → 白名单校验 → 解析配置 → 搭建隔离沙箱 → 实例化工具 → Registry 注册 → 启动运行

三道安全防线

maxSpawnDepth（限制嵌套层级）、maxChildrenPerAgent（限制单父最大子 Agent 数量）、allowAgents类型白名单，避免递归创建耗尽算力。

3.2 Registry 模块：户籍生命周期中心（负责「登记管理」）

核心职责：统一记录所有子 Agent 状态、父子关系，自动清理孤儿 Agent。

1. 三大生命周期接口：

• 注册新建子 Agent

• 标记任务完成、留存结果

• 释放内存、目录等物理资源

2. 持久化机制：状态增量落盘，进程崩溃重启后可恢复 Agent 生命周期。

3. 孤儿清扫机制：定时 Sweeper 扫描，父 Agent 宕机则判定子 Agent 为孤儿，自动终止并回收资源，避免僵尸进程。

3.3 Control 模块：运行调度中枢（负责「运行干预」）

父 Agent 运行时管控子 Agent 的五大能力：

1. list：查询子 Agent 状态、内存、耗时，支撑运维面板；

2. kill：级联终止，杀掉父 Agent 时递归销毁所有子孙 Agent；

3. steer：软干预，插入引导指令，不中断当前任务、修正后续行为；

4. send：仅用于 Session 模式，追加消息实现多轮对话；

5. resolveTarget：兼容 ID、命名、层级路径三种寻址方式，简化跨 Agent 调用。

3.4 Announce 模块：通信通知枢纽（负责「结果上报」）

核心职责：子 Agent 完成任务 / 报错后，异步将消息推送父 Agent，实现 Fork-Join 并行汇总。

3 种消息投递通道

• Queue 异步队列：进度推送、状态上报，非阻塞；

• Steer 引导投递：下发后续任务指令，驱动父 Agent 流转流程；

• Direct 同步投递：阻塞等待确认，用于全部子任务完成后的汇总节点。

关键机制：后代休眠唤醒

父 Agent 派发子任务后休眠，全部子 Agent 执行完毕再由 Announce 唤醒父 Agent 汇总结果，省去轮询巡检，节省 CPU 资源。

四、四大模块完整流转关系

1. 父 Agent 调用 Spawn 生成隔离 Subagent；

2. Spawn 完成安全校验后，将子 Agent 注册写入 Registry；

3. 父 Agent 通过 Control 模块随时查看、管控正在运行的子 Agent；

4. 子 Agent 执行结束，经由 Announce 模块把结果推送父 Agent；

5. Registry 识别已完成 / 孤儿 Agent，执行资源清理，生命周期闭环。

五、整体架构逻辑总结

1. 底层依靠三层隔离保证各个 Agent 相互独立、安全隔离；

2. 上层四大模块分工串联子 Agent 全生命周期，打通隔离边界实现有序协作；

3. 隔离底座 + 模块化协作，既不会出现状态污染，又能完成复杂任务拆解并行执行。

3.1 Spawn 模块：Subagent 生成器（负责「诞生」）

核心职责：安全创建隔离子 Agent，管控创建权限，防止资源雪崩。

两种运行模式

• Run 模式（任务型）：子 Agent 执行单次任务，结束立刻销毁，适合代码分析、文档翻译。

• Session 模式（会话型）：子 Agent 长期存活，支持多轮交互，适合持续监控、多轮问答。

两类沙箱权限策略

• Inherit：继承父 Agent 全部权限，父子任务联动场景使用。

• Require：子 Agent 必须主动申请权限，严格最小权限，安全性更高。

9 步生成流程

参数校验 → 嵌套深度校验 → 子 Agent 数量校验 → 白名单校验 → 解析配置 → 搭建隔离沙箱 → 实例化工具 → Registry 注册 → 启动运行

三道安全防线

maxSpawnDepth（限制嵌套层级）、maxChildrenPerAgent（限制单父最大子 Agent 数量）、allowAgents类型白名单，避免递归创建耗尽算力。

3.2 Registry 模块：户籍生命周期中心（负责「登记管理」）

核心职责：统一记录所有子 Agent 状态、父子关系，自动清理孤儿 Agent。

1. 三大生命周期接口：

• 注册新建子 Agent

• 标记任务完成、留存结果

• 释放内存、目录等物理资源

2. 持久化机制：状态增量落盘，进程崩溃重启后可恢复 Agent 生命周期。

3. 孤儿清扫机制：定时 Sweeper 扫描，父 Agent 宕机则判定子 Agent 为孤儿，自动终止并回收资源，避免僵尸进程。

3.3 Control 模块：运行调度中枢（负责「运行干预」）

父 Agent 运行时管控子 Agent 的五大能力：

1. list：查询子 Agent 状态、内存、耗时，支撑运维面板；

2. kill：级联终止，杀掉父 Agent 时递归销毁所有子孙 Agent；

3. steer：软干预，插入引导指令，不中断当前任务、修正后续行为；

4. send：仅用于 Session 模式，追加消息实现多轮对话；

5. resolveTarget：兼容 ID、命名、层级路径三种寻址方式，简化跨 Agent 调用。

3.4 Announce 模块：通信通知枢纽（负责「结果上报」）

核心职责：子 Agent 完成任务 / 报错后，异步将消息推送父 Agent，实现 Fork-Join 并行汇总。

3 种消息投递通道

• Queue 异步队列：进度推送、状态上报，非阻塞；

• Steer 引导投递：下发后续任务指令，驱动父 Agent 流转流程；

• Direct 同步投递：阻塞等待确认，用于全部子任务完成后的汇总节点。

关键机制：后代休眠唤醒

父 Agent 派发子任务后休眠，全部子 Agent 执行完毕再由 Announce 唤醒父 Agent 汇总结果，省去轮询巡检，节省 CPU 资源。

四、四大模块完整流转关系

1. 父 Agent 调用 Spawn 生成隔离 Subagent；

2. Spawn 完成安全校验后，将子 Agent 注册写入 Registry；

3. 父 Agent 通过 Control 模块随时查看、管控正在运行的子 Agent；

4. 子 Agent 执行结束，经由 Announce 模块把结果推送父 Agent；

5. Registry 识别已完成 / 孤儿 Agent，执行资源清理，生命周期闭环。

五、整体架构逻辑总结

1. 底层依靠三层隔离保证各个 Agent 相互独立、安全隔离；

2. 上层四大模块分工串联子 Agent 全生命周期，打通隔离边界实现有序协作；

3. 隔离底座 + 模块化协作，既不会出现状态污染，又能完成复杂任务拆解并行执行。