OpenClaw SubAgent 三层安全约束完整详解

整体分为三大核心防护体系：子代理黑白名单权限收缩、递归委派阻断（防无限循环/资源雪崩）、全链路上下文/数据隔离（防污染） ，配套 rules.md、AGENTS.md、三层Tool治理、四层Langfuse追踪、可插拔运行时沙箱统一生效，属于 UpClaw「安全隔离、权限合规、并发安全、推理预算」四大改造板块核心实现，遵循零信任、最小权限、默认禁止、全链路审计四大安全原则。

前置基础：SubAgent 委派基础模型

OpenClaw 采用父代理主动委派、子代理独立会话、单向结果回流架构，基于 SFA2A 跨代理通信协议：

1. 父 Agent 通过 spawn_subagent 工具发起子任务；
2. 生成独立子会话 ID：session:xxx/subagent:uuid，完全隔离内存、沙箱、工作区、记忆；
3. 子代理执行完毕仅返回结构化摘要结果，中间推理、工具日志、原始上下文不回灌父会话；
4. 所有委派、权限校验、递归检测、污染拦截全部在 onSubAgentDispatch 全局钩子执行前置拦截。

三大风险原生痛点（对应三套约束）：

1. 权限扩散：子代理继承父全部高危工具，越权删改数据、访问内网；→ 黑白名单权限收缩
2. 递归雪崩：子代理继续派生子代理，无限嵌套、无限消息乒乓循环，算力耗尽；→ 防递归深度/乒乓/委派阻断
3. 数据污染：父子上下文互通、记忆跨代理读写、敏感凭证泄露、子任务中间日志膨胀父窗口；→ 防上下文/记忆/凭证污染隔离

一、第一套：SubAgent 多级黑白名单权限收缩（最小权限管控）

1. 分层权限策略（自上而下收敛，下级不能扩权）

权限遵循全局 → 父Agent → 子Agent实例三级策略叠加，规则：黑名单叠加追加、白名单取交集，子代理可用工具 = 父白名单 ∩ 子自定义白名单 − 全局/父/子三层黑名单。

（1）全局层：rules.md 全局子代理黑名单（强制兜底）

固定永久拦截所有子代理的高危能力，全局生效，不可绕过：

• 高危系统工具：shell/exec/fs_delete/drop_table/network_scan
• 递归委派工具：spawn_subagent/delegate_task（默认禁用，防止自递归）
• 特权凭证工具：cred_read/secrets_export
• 全局配置字段：subagent.blockGlobalTools: ["exec", "spawn_subagent"]

（2）父代理层：AGENTS.md 委派准入白名单

管控允许创建哪些子代理、父能下放哪些工具集：

1. allowAgents: ["order_query_sub", "report_sub"]
   仅列表内子代理ID可被父创建；请求不在列表直接拦截委派，不创建子会话；
2. delegateToolAllowlist：父允许下放给子代理的工具集合；
3. requireApprovalElevatedTools：提升权限操作必须人工复核，子代理无法自主执行生产变更。

（3）子实例层：子代理私有白名单（进一步收缩）

每个子Agent目录独立 rules.md / TOOLS.md 定义自身可用工具：

• 示例：订单查询子代理仅保留 query_order/read_customer，剔除所有写库、删除、执行命令工具；
• 沙箱降级：子代理强制使用 non-main 轻量隔离沙箱，禁止 elevated 特权模式，除非显式配置时间盒临时授权（timeout自动回收权限）。

2. 工具权限核心机制：交集收缩原则

父可用工具集合：T_p

子允许下放工具：T_delegate

子自身白名单：T_child

全局黑名单：T_deny

子实际可用 = T_p ∩ T_delegate ∩ T_child − T_deny

子代理永远无法获得父代理没有的工具权限，只能更少，不能更多，彻底阻断权限扩散。

3. 配套隔离增强（与三层Tool治理联动）

1. 沙箱独立分配：每个子代理独占临时沙箱容器，独立网络白名单、独立文件工作区，无法读写父Agent工作目录，workspaceAccess=none/ro 只读隔离；
2. 通信 allowFrom 双向校验：子代理仅接收父代理消息，拒绝其他Agent发起的指令，防止第三方劫持子代理会话；
3. 临时授权时间盒：如需临时开放高危工具，必须配置 timeout，到期自动销毁子会话回收权限，不可永久持有特权；
4. 全链路审计：RulePolicySpan + SubAgentDispatchSpan 记录每一次工具放行/拦截、权限收缩明细，存入四层Langfuse追踪。

4. 生命周期介入时机

1. onSubAgentDispatch 委派创建前：执行三级黑白名单交集计算，无可用工具直接拒绝创建子代理；
2. before_tool_run 子代理工具执行前：二次校验子工具白名单，拦截越权调用；
3. session:after_close 子代理销毁：回收沙箱、清理临时权限快照，重置工具计数器。

二、第二套：防递归全套阻断机制（三层递归防护，杜绝无限嵌套/乒乓循环）

递归风险分两类：

1. 垂直嵌套递归：父→子→孙→重孙无限委派，层级爆炸、会话指数增长；
2. 水平乒乓递归：A委派B，B委派A来回互调，消息无限往返、算力耗尽。

OpenClaw 通过 深度限制、委派工具禁用、乒乓轮次阈值、消息TTL、循环拓扑检测 五重防护。

1. 垂直嵌套递归防护（层级深度锁）

（1）最大嵌套深度阈值 maxSubAgentDepth

全局默认 max=1（仅允许父→子单层，禁止孙代理），企业可放宽至2，超过直接阻断委派：

• 深度计算规则：父depth=0，一级子depth=1，二级子depth=2；达到阈值时 spawn_subagent 工具调用直接被rules.md拦截，返回递归熔断错误；
• 底层实现：每个子会话携带 parentTraceId、nestDepth 元数据，创建时校验深度，写入Langfuse标签。

（2）子代理默认移除委派工具（根源阻断）

全局rules.md将 spawn_subagent 加入子代理黑名单：

• 父Agent独有委派工具；所有子代理工具集自动剔除 spawn_subagent，子代理完全没有创建孙代理的入口，从根源杜绝多层嵌套递归；
• 如需特殊多层委派，需在AGENTS.md显式开启 allowSubSpawn=true，同时强制收紧maxDepth并开启人工审批。

2. 水平乒乓互调递归防护（消息往返阻断）

（1）最大乒乓往返轮次 maxPingPongTurns

配置父子间双向消息最大交互次数（默认8轮），超过阈值自动终止子会话并熔断链路；

场景：子代理反复向父请求补充信息，无限来回拉扯消耗Token。

（2）消息TTL + 拓扑闭环检测

1. SFA2A每条跨代理消息携带 hopCount 跳数，每跨一次Agent+1，全局最大hop=5，超限丢弃消息；
2. 路由层维护通信拓扑图，实时检测循环链路（A↔B闭环），一旦识别循环直接中断子代理执行，生成告警日志；
3. 消息携带唯一 traceId，四层Langfuse可完整还原递归调用链用于复盘。

3. 资源兜底熔断（递归失控兜底）

1. 单会话最大并发子代理数量 maxConcurrentSubAgents（默认3），达到上限拒绝新建；
2. 子代理最大运行时长 subagentMaxRuntime（默认300s），超时强制销毁，防止无限执行；
3. 推理预算联动：子代理独立Token预算，耗尽自动终止，避免递归循环持续消耗模型算力。

4. 生命周期拦截点

所有递归检测统一在 onSubAgentDispatch 前置执行，未创建子会话前直接拦截，不分配沙箱、不消耗模型算力；命中递归熔断生成独立RulePolicySpan追踪记录。

三、第三套：全链路防污染隔离机制（上下文/记忆/凭证/日志隔离）

污染定义：父子Agent数据互通导致四大风险：

1. 上下文污染：子代理中间工具日志、冗余思考灌入父会话，父窗口快速溢出、模型丢失全局目标；
2. 记忆污染：子代理写入共享长期记忆，业务数据、客户信息跨租户/跨任务泄露；
3. 凭证污染：父密钥、API凭证传递给子代理，子代理被劫持后泄露核心凭据；
4. 指令污染：子代理恶意输出注入父上下文，篡改父代理原有业务约束、rules规则。

分五大隔离维度实现彻底防污染。

1. 上下文视图隔离（核心：子独立窗口，仅摘要回流）

（1）完全独立上下文内存空间

子代理初始化时创建全新空白上下文，不会复制、fork父完整对话历史，仅传递精简任务指令（无父冗余轮次、工具日志、敏感上下文），从源头避免父污染子窗口。

（2）结果单向摘要回流，禁止中间日志回灌

子代理执行完成后，执行强制摘要压缩逻辑：

• 仅返回结构化结论、关键数值、业务结果；
• 子代理全部中间推理、工具调用原始输出、报错堆栈永久不回传给父Agent；
• 父上下文只会追加简短子任务摘要，不会膨胀大量冗余日志，解决父窗口上下文爆炸污染问题。

（3）边界注入防护（防指令篡改污染）

1. 子代理返回内容自动添加不可篡改隔离标记 [SUBAGENT_RESULT_BOUNDARY]，ContextEngine解析时识别边界，禁止子输出伪造System Prompt、rules约束、身份指令；
2. 自动过滤零宽不可见字符、伪边界标记，阻断注入攻击，防止子代理篡改父Agent行为逻辑。

2. LongTermMemory 长期记忆读写隔离（防数据跨代理污染泄露）

1. 记忆空间物理分片隔离：
   父、子代理拥有独立记忆分片目录 memory/subagent/<uuid>.md，默认禁止子代理读写父代理记忆分片，也禁止子之间互相读取记忆；
2. 读写权限管控（MEMORY.md + rules.md）：
   • 子代理仅允许读写自身专属记忆分片；
   • 如需子代理读取父历史记忆，必须显式配置 allowParentMemoryRead，并开启记忆脱敏、内容过滤；
   • 子代理写入记忆自动附加 subagent:uuid 租户标签，向量检索时自动过滤其他代理记忆片段，避免跨任务数据混入；
3. 压缩隔离：子代理内部执行独立 Context Compaction，压缩摘要仅存于子会话，不污染父全局记忆。

3. 凭证与配置隔离（防密钥污染泄露）

1. 认证配置按Agent目录物理隔离：父API Key、数据库凭证、密钥文件仅挂载父工作区，子代理工作区完全不可见，文件系统权限 700 隔离配置目录；
2. 跨代理消息自动脱敏：SFA2A通信通道内置脱敏过滤器，自动屏蔽密钥、手机号、证件、Token，子代理无法通过消息窃取父敏感凭证；
3. 子代理沙箱环境变量剥离：创建沙箱时剔除父全部密钥类环境变量，仅下放业务只读配置。

4. MD配置提示词隔离（规则、身份互不污染）

1. 子代理独立加载自身全套MD：rules.md/IDENTITY.md/SOUL.md/SKILL.md，不会继承父的人格、业务流程、提示词约束；
2. 父、子System Prompt完全分离，子代理无法修改、覆盖父全局rules硬规则；
3. 子代理执行时仅生效自身层级MD，父的业务约束不会污染子任务逻辑，反之亦然。

5. 工作区&文件系统物理隔离（防文件污染覆盖）

每个子代理分配独立临时工作目录，生命周期结束自动全盘销毁：

• 禁止子代理读写父Agent工作区、全局配置目录；
• 文件操作工具自动添加路径白名单，仅允许访问自身临时目录，防止子代理修改父代码、配置、业务文件造成污染与破坏。

四、三大安全约束完整协同执行流程（一次子代理委派全链路）

父Agent生成 spawn_subagent 工具调用指令
    ↓
【第一层拦截：rules.md 全局黑名单校验】
拦截：是否包含递归工具、全局高危工具；拦截则直接终止
放行 → 进入onSubAgentDispatch钩子
    ↓
【第二层：防递归检测】
1. 校验nestDepth嵌套深度；2. 检测拓扑乒乓循环；3. 校验并发子代理上限
命中递归 → 熔断，记录RulePolicySpan审计日志
放行 → 进入权限黑白名单收缩
    ↓
【第三层：三级黑白名单交集计算】
全局黑名单 ∩ 父下放白名单 ∩ 子私有白名单，生成子代理可用工具集
无可用工具 → 拒绝创建子会话
有合法工具 → 初始化独立子代理运行环境
    ↓
创建隔离资源（独立沙箱、独立空白上下文、独立记忆分片、独立工作区、剥离父密钥）
    ↓
子代理独立执行ReAct循环（自身MD、自身工具、独立压缩、独立记忆读写）
全程约束：
1. 子无spawn_subagent工具，禁止递归委派
2. 子工具执行持续校验子白名单
3. 子记忆仅读写自身分片
4. 子消息往返受maxPingPongTurns限制
    ↓
子任务完成 → 执行结果摘要压缩，过滤所有中间日志
仅结构化结论回流父Agent，附加隔离边界标记，防止注入污染
    ↓
子会话销毁：销毁沙箱、清空临时工作区、归档子独立记忆分片、释放所有临时权限
    ↓
四层Langfuse完整链路留存：SubAgentDispatchSpan + 内部全部ToolRunSpan/RulePolicySpan/ContextEngineSpan

五、三大约束在Agent完整生命周期的介入总览

生命周期钩子	黑白名单权限收缩	防递归阻断	防污染隔离
onSessionCreate（父会话）	预加载全局/父子代理权限策略	初始化nestDepth计数器、并发池	初始化父独立记忆、工作区、凭证隔离
on_llm_output（父生成委派指令）	rules全局黑名单前置拦截	初步检测递归工具调用	无
onSubAgentDispatch（核心委派卡点）	三级白名单交集计算，锁定子工具集	深度、乒乓、并发、拓扑循环四重检测	分配独立上下文、沙箱、记忆分片，剥离父密钥
before_tool_run（子代理工具执行）	二次校验子工具白名单，拦截越权	子无spawn_subagent，彻底阻断递归入口	工具路径白名单，禁止跨工作区读写
before_memory_rw（子记忆读写）	管控记忆访问权限白名单	无	限制仅读写自身记忆分片，自动脱敏
after_subagent_finish（子任务结束）	回收临时下放权限	重置子递归计数器	摘要过滤中间日志，隔离标记回流结果
session:after_close（子销毁）	清空子权限快照	释放并发子代理配额	销毁临时沙箱/工作区，归档独立记忆

六、与原生AgentScope、Codex、Claude Code子代理机制对比

1. vs 原生AgentScope

• AgentScope无标准化子代理黑白名单，权限完全继承；无强制递归深度限制；父子上下文默认复制，无防污染隔离；无独立子代理沙箱、记忆分片；仅提供基础委派能力，无企业安全约束；
• OpenClaw三层约束完整补齐生产安全短板，全链路前置拦截、最小权限、隔离销毁、审计闭环。

2. vs OpenAI Codex SubAgent

1. 权限：Codex仅简单工具过滤，无三级黑白名单交集收缩，无法精细化下放权限；
2. 递归：仅单层深度限制，无乒乓循环拓扑检测；
3. 污染隔离：子中间日志会回灌主上下文，无强制摘要隔离机制，极易窗口污染；
4. 无独立记忆分片、文件沙箱隔离，云端统一存储无法私有化合规管控。

3. vs Claude Code SubAgent

• 仅本地单层沙箱，缺少全局rules统一管控子代理权限；无记忆分片隔离；无SFA2A通信乒乓循环防护；无分层审计追踪；仅适用于个人本地代码调试，不支持企业多租户子代理安全管控。

七、核心落地业务价值（匹配UpClaw从"可用"到"可上线"）

1. 零信任最小权限落地：子代理权限持续收缩，杜绝权限扩散、越权操作，满足政企数据合规；
2. 算力成本稳定可控：防递归阻断无限嵌套/乒乓循环，避免AI自主创建大量子代理耗尽服务器资源；
3. 上下文稳定不爆炸：防污染隔离阻断子中间日志回灌父会话，大幅降低父窗口Token膨胀，配合Context Compaction减少频繁压缩抖动；
4. 数据泄露风险闭环：记忆、文件、凭证三层物理隔离，子代理无法窃取父敏感业务数据、客户隐私；
5. 完整审计可追溯：所有委派、权限拦截、递归熔断、跨代理读写行为全部分层埋点至Langfuse，满足等保审计追溯要求；
6. 多租户安全隔离：不同业务线子代理记忆、工作区、权限完全隔离，防止跨租户数据污染与泄露。

八、典型企业落地场景示例

场景：企业客服多子代理分工（订单查询、退款审批、工单创建）

1. 黑白名单管控
   订单子代理仅开放只读查询工具，黑名单拦截删单、改库、执行shell；审批子代理仅允许退款审核接口，无数据库删除权限；
2. 防递归
   所有子代理移除spawn_subagent工具，maxDepth=1，禁止子代理再拆分任务；限制全局并发子代理最大3个，避免会话泛滥；
3. 防污染
   每个子代理独立记忆分片，仅存储对应客户订单数据；子查询完整日志不回传给主客服Agent，仅返回订单摘要；子沙箱无权限读取主客服的全局客户密钥配置；不同客户会话子代理记忆完全隔离，防止客户数据交叉污染。