OpenClaw（UpClaw）三层Tool全链路治理深度详解

一、三层Tool治理核心定义与设计目标

核心概念区分（三层是纵深防御闭环，自外向内层层拦截，优先级逐层升高）

OpenClaw 三层Tool治理是面向企业生产、配套19项工程改造中技能执行、安全隔离、权限合规、推理预算四大板块的标准化管控体系，三层分别对应：

第一层：业务引导层（Skill / SKILL.md + TOOLS.md）
作用：告诉模型可以用什么工具、什么场景用、标准执行步骤 ，属于提示词柔性约束，仅引导AI行为，无强制阻断能力。
第二层：运行时执行层（ToolAdapter插件 + 沙箱隔离）
作用：管控工具底层执行环境、资源配额、调用格式校验，属于执行介质硬管控，拦截非法参数、资源超限操作。
第三层：全局规则拦截层（rules.md 安全策略引擎）
作用：最高优先级硬红线，全生命周期前置熔断，无视上层Skill/模型意图，高危调用直接拒绝、不进入沙箱执行。

三层治理遵循先引导、再执行、最后兜底拦截的纵深安全模型，解决原生AgentScope无工具权限管控、无沙箱隔离、无全局熔断、审计缺失的线上失控风险，实现工具从"随便调用"到"可审计、可限流、可隔离、可熔断"企业上线标准。

三层递进关系（优先级：第三层 > 第二层 > 第一层）

复制代码

rules.md（全局硬拦截，最高权重）
  ↓ 拦截则直接终止，放行才进入执行层
ToolAdapter沙箱/资源管控（执行介质校验）
  ↓ 校验通过才允许模型调用Skill流程
SKILL.md + TOOLS.md（业务流程引导，最低权重）

核心逻辑：第一层仅做行为指引；第二层管控执行环境；第三层拥有一票否决权，所有工具调用必须先过rules.md校验。

二、第一层：业务引导层（SKILL.md + TOOLS.md）

1. 组成组件

TOOLS.md：系统自动生成全局工具契约清单，统一描述所有底层Tool原子函数（exec、read_file、web_fetch、db_query等）的入参、返回格式、能力边界，一次性注入System Prompt，让模型知道系统存在哪些基础工具。
SKILL.md ：分场景技能说明书，存放于三级技能目录（工作区自定义 > 用户全局 > 系统内置），定义工具组合业务流程，指导模型按步骤串联多个原子Tool完成复杂任务。

2. 加载与生命周期介入时机

会话初始化onSessionCreate阶段
按目录优先级扫描全部SKILL.md，合并TOOLS.md生成工具基线提示词，固定拼接在System Prompt中（低于rules、IDENTITY、SOUL优先级）。
LLM推理循环onReasoningStart
模型每次思考时读取Skill流程，自主匹配当前业务场景选择对应工具组合；仅在无规则拦截、无执行层异常时生效。
onToolRun工具执行前
Skill文档约束工具调用顺序、参数规范，引导AI按标准化步骤执行，避免无序乱调用工具。

3. 核心治理能力（柔性引导，无阻断）

工具可见域管控
可在SKILL.md限定当前业务场景仅暴露部分工具，隐藏无关底层Tool，减少模型幻觉式调用；
标准化执行流程约束
定义多工具串行/并行调用步骤（例如查工单→查客户→生成回复三步固定工具链）；
参数格式规范
强制模型输出标准JSON工具调用参数，减少格式解析失败；
场景触发匹配
通过frontmatter triggers 绑定用户指令关键词，自动加载对应技能文档，降低上下文Token消耗。

4. 局限性

仅属于提示词层面引导，无法阻止模型主动调用高危工具，模型仍会生成违规工具调用指令，必须依赖第二层、第三层兜底拦截。

三、第二层：运行时执行层（ToolAdapter插件 + 沙箱隔离）

1. 组成组件

基于可插拔运行时ToolAdapter插槽实现，包含两大子模块：

工具适配器插件：底层原子Tool执行实现（文件读写、代码沙箱、数据库、视频解析、子代理委派等）；
分层沙箱系统：进程隔离容器，分为普通沙箱、提升权限elevated沙箱、禁止执行三级环境。

2. 生命周期介入全节点

before_tool_run（模型输出工具指令后，真实执行前）
- 校验工具参数合法性、参数长度、敏感字段过滤；
- 校验单会话工具调用次数、单次推理最大调用上限；
- 分配对应隔离沙箱容器，高危工具强制独立销毁式临时沙箱；
tool_running（工具执行中）
- 实时监控CPU/内存/运行时长，超时自动kill进程；
- 网络访问白名单拦截内网越权访问；
- 所有IO操作全量埋点，写入可观测Observer插件；
after_tool_run（执行完成/异常退出）
- 沙箱资源自动销毁，清理临时文件、缓存；
- 标准化工具返回结果，过滤报错堆栈敏感信息；
- 统计本次工具Token、耗时，更新会话预算计数器。

3. 核心治理能力（执行介质硬管控，可阻断但无全局策略）

环境隔离沙箱
- 普通文件/脚本运行在隔离容器，无法直接读写宿主敏感目录；
- elevated提升权限工具需二次人工确认，默认禁用；
- 高危exec命令、数据库删改操作启用一次性销毁沙箱，执行完毕彻底回收；
资源限流管控
单会话最大工具调用轮次、单工具超时阈值、并发子技能并行上限、网络请求速率限制；
参数与输出清洗
自动脱敏工具输入输出中的手机号、身份证、密钥；过滤报错堆栈内凭证信息；
多源工具适配
统一封装内部业务API、私有数据库、第三方SDK为标准化Tool，上层Agent无感知切换；
执行异常熔断
工具连续失败阈值自动终止本轮工具循环，避免无限重试消耗算力。

4. 局限性

仅管控已经放行进入执行阶段的工具调用；无法在模型生成违规指令前拦截，若rules.md未拦截高危工具，会进入沙箱执行后才终止，存在一定算力浪费。

四、第三层：全局规则拦截层（rules.md 安全策略引擎，最高优先级）

1. 组件定位

三层治理的兜底硬防线，独立于提示词、沙箱执行逻辑，由SecurityPolicy可插拔插件解析运行，是企业合规、权限管控核心载体，优先级高于所有Skill、工具执行逻辑。

2. 生命周期介入节点（全链路前置拦截，第一道关卡）

onInput 用户消息入站：提前拦截意图为高危工具操作的用户请求，不进入推理；
on_llm_output 模型生成工具调用指令后，第二层沙箱校验之前 ：
最关键拦截点，解析模型输出的tool名称、参数、目标资源，匹配rules.md黑白名单、权限规则，命中违规直接丢弃调用指令，不分配沙箱、不执行任何操作；
before_memory_write：管控工具执行结果写入长期记忆的权限，禁止工具返回敏感数据入库；
onSessionCreate会话初始化：预加载当前Agent工具权限配置，初始化工具调用计数器、预算上限。

3. 核心Tool治理能力（一票否决，全局刚性约束）

工具黑白名单管控
- 全局黑名单：永久禁用高危工具（rm -rf、数据库drop、内网无限制访问）；
- 会话白名单：不同租户/子Agent分配独立可用工具集，实现最小权限；
精细化参数约束规则
限制工具操作范围：例如read_file仅允许读取业务目录，禁止读取/etc/密钥目录；exec仅允许指定脚本路径；
推理预算全局管控
全局单轮最大工具调用次数、单日会话总调用上限，到达阈值直接熔断会话；
高危操作二次确认规则
删数据、修改生产库、对外批量发送消息等工具，强制触发人工复核，AI无法自主执行；
子代理工具权限隔离
AGENTS.md委派子代理时，rules.md自动收缩子代理工具权限，禁止子代理调用父代理高危工具；
合规审计强制埋点
所有规则拦截、放行、高危工具调用自动生成不可篡改审计日志，对接Observer监控插件，输出告警。

4. 核心优势

前置拦截，零算力浪费：在分配沙箱、执行工具前直接阻断违规调用，避免无用推理与容器资源占用，满足企业成本与安全双重要求。

五、三层Tool完整协同执行流程（标准工具调用闭环）

#mermaid-svg-fEts426cPAAaG89P{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-fEts426cPAAaG89P .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-fEts426cPAAaG89P .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-fEts426cPAAaG89P .error-icon{fill:#552222;}#mermaid-svg-fEts426cPAAaG89P .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-fEts426cPAAaG89P .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-fEts426cPAAaG89P .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-fEts426cPAAaG89P .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-fEts426cPAAaG89P .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-fEts426cPAAaG89P .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-fEts426cPAAaG89P .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-fEts426cPAAaG89P .marker{fill:#333333;stroke:#333333;}#mermaid-svg-fEts426cPAAaG89P .marker.cross{stroke:#333333;}#mermaid-svg-fEts426cPAAaG89P svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-fEts426cPAAaG89P p{margin:0;}#mermaid-svg-fEts426cPAAaG89P .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-fEts426cPAAaG89P .cluster-label text{fill:#333;}#mermaid-svg-fEts426cPAAaG89P .cluster-label span{color:#333;}#mermaid-svg-fEts426cPAAaG89P .cluster-label span p{background-color:transparent;}#mermaid-svg-fEts426cPAAaG89P .label text,#mermaid-svg-fEts426cPAAaG89P span{fill:#333;color:#333;}#mermaid-svg-fEts426cPAAaG89P .node rect,#mermaid-svg-fEts426cPAAaG89P .node circle,#mermaid-svg-fEts426cPAAaG89P .node ellipse,#mermaid-svg-fEts426cPAAaG89P .node polygon,#mermaid-svg-fEts426cPAAaG89P .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-fEts426cPAAaG89P .rough-node .label text,#mermaid-svg-fEts426cPAAaG89P .node .label text,#mermaid-svg-fEts426cPAAaG89P .image-shape .label,#mermaid-svg-fEts426cPAAaG89P .icon-shape .label{text-anchor:middle;}#mermaid-svg-fEts426cPAAaG89P .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-fEts426cPAAaG89P .rough-node .label,#mermaid-svg-fEts426cPAAaG89P .node .label,#mermaid-svg-fEts426cPAAaG89P .image-shape .label,#mermaid-svg-fEts426cPAAaG89P .icon-shape .label{text-align:center;}#mermaid-svg-fEts426cPAAaG89P .node.clickable{cursor:pointer;}#mermaid-svg-fEts426cPAAaG89P .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-fEts426cPAAaG89P .arrowheadPath{fill:#333333;}#mermaid-svg-fEts426cPAAaG89P .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-fEts426cPAAaG89P .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-fEts426cPAAaG89P .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-fEts426cPAAaG89P .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-fEts426cPAAaG89P .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-fEts426cPAAaG89P .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-fEts426cPAAaG89P .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-fEts426cPAAaG89P .cluster text{fill:#333;}#mermaid-svg-fEts426cPAAaG89P .cluster span{color:#333;}#mermaid-svg-fEts426cPAAaG89P div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-fEts426cPAAaG89P .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-fEts426cPAAaG89P rect.text{fill:none;stroke-width:0;}#mermaid-svg-fEts426cPAAaG89P .icon-shape,#mermaid-svg-fEts426cPAAaG89P .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-fEts426cPAAaG89P .icon-shape p,#mermaid-svg-fEts426cPAAaG89P .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-fEts426cPAAaG89P .icon-shape .label rect,#mermaid-svg-fEts426cPAAaG89P .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-fEts426cPAAaG89P .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-fEts426cPAAaG89P .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-fEts426cPAAaG89P :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 命中违规规则
放行
违规
合规
参数/资源超限/沙箱禁止
校验通过
用户输入需求
第三层rules.md前置意图校验
直接拒绝，记录审计日志，流程终止
LLM推理，读取第一层SKILL.md/TOOLS.md引导
模型输出工具调用JSON指令
第三层rules.md二次校验工具名称、参数、资源
第二层ToolAdapter沙箱与资源校验
终止执行，返回异常
分配隔离沙箱，真实执行工具
工具执行完成，清洗输出结果
第三层rules.md校验结果是否允许写入LongTermMemory
写入记忆/返回结果给用户
会话本轮循环结束，更新工具调用计数器

流程拆解：

消息入站先过第三层rules意图风控；
模型基于第一层Skill文档生成工具调用；
模型输出指令再次走第三层硬规则拦截（核心卡点）；
规则放行后进入第二层沙箱资源校验与执行；
工具输出结果再次经过规则校验，控制记忆写入；
全流程所有拦截、放行动作统一审计埋点。

六、三层Tool治理在Agent完整生命周期各阶段参与明细

生命周期钩子	第一层Skill(TOOLS/SKILL.md)	第二层ToolAdapter沙箱	第三层rules.md规则引擎
onSessionCreate	一次性加载全部技能文档，拼装System Prompt	初始化工具适配器、沙箱池	加载工具权限策略，初始化调用计数器
onInput消息入站	无参与	无参与	前置意图风控，拦截高危工具需求
onReasoningStart	注入技能流程引导模型思考	预分配工具客户端	校验剩余工具调用预算，预算耗尽直接熔断
on_llm_output模型输出	校验工具调用格式是否符合Skill规范	无参与	解析工具指令，黑白名单拦截违规调用
before_tool_run	约束工具执行顺序、步骤	沙箱创建、参数校验、资源限流	二次校验操作资源范围
tool_running执行中	无动态干预	实时监控超时、内存、网络	实时检测异常数据流，动态终止执行
after_tool_run执行结束	标准化工具输出解析	销毁沙箱、释放资源、清洗结果	校验输出敏感数据，管控记忆写入权限
onOutput对外返回	规范结果行文格式	无参与	输出脱敏、隐私屏蔽兜底审计
onSessionClose会话销毁	清空会话技能缓存	回收全部会话沙箱资源	归档本轮所有工具调用审计日志，重置计数器

七、三层Tool治理核心价值（对应UpClaw从"可用"到"可上线"）

分层解耦，低代码运维
- 业务流程调整：仅修改SKILL.md，无需改动底层插件代码；
- 执行环境切换：替换ToolAdapter插件（本地沙箱/云端容器）；
- 安全权限管控：统一修改全局rules.md黑白名单，全局生效；
纵深零信任安全闭环
三层层层兜底，不存在单点防护失效风险：引导层约束AI行为、执行层隔离运行环境、规则层全局强制红线，解决AI自主调用工具带来的删库、数据泄露、内网越权风险；
精细化资源成本管控
第三层全局预算+第二层单会话限流双重管控，杜绝AI无限循环调用工具，避免算力、接口费用失控；
完整合规审计链路
每一层拦截、放行、执行动作全埋点，区分：规则拦截日志、沙箱执行日志、技能调用日志，满足企业等保、隐私合规审计追溯需求；
最小权限落地
三层协同实现租户/子Agent工具权限隔离，不同业务智能体仅分配必要工具，符合企业零信任最小权限原则；
适配多代理SFA2A委派场景
子代理委派时三层治理自动联动收缩权限：rules.md限制子代理高危工具、Skill仅加载子业务技能、沙箱分配独立隔离容器，防止跨代理权限泄露。

八、与Codex、Claude Code原生工具管控的核心区别

OpenAI Codex
仅单层云端沙箱执行管控，无业务Skill分层引导、无全局规则拦截层；工具权限、调用次数硬编码在厂商后台，不支持自定义黑白名单，无企业级可配置rules管控。
Claude Code
仅有提示词工具说明+本地单层执行沙箱，缺少独立全局规则引擎前置拦截；无法按会话/租户拆分工具权限，无分层审计体系，仅适合个人开发，不支持企业多租户生产管控。
OpenClaw三层Tool治理
三层独立分层架构，配置全外置MD文件+可插拔插件，支持私有化内网部署、自定义安全策略、多租户权限隔离、全链路审计，是面向企业生产环境的完整工具管控体系。

九、典型落地场景示例

场景：企业客服智能体工具管控

第一层SKILL.md
定义工具调用流程：用户咨询订单→调用订单查询工具→调用客户画像工具→生成回复；禁止模型跳过查询直接编造数据；
第二层ToolAdapter
订单API工具封装适配器，沙箱隔离网络请求，限制单轮最多3次接口调用，超时10s自动终止；自动脱敏返回手机号、身份证；
第三层rules.md
黑名单禁用数据库delete、exec高危命令；仅开放订单查询、工单创建两类工具；单日单会话工具调用上限100次；批量发送短信工具需人工二次确认。

三层协同效果：AI只能按业务流程调用指定客服工具，无法执行高危操作，资源可控、行为可审计，满足企业客服线上安全上线标准。