一、整体定位与三层治理总纲

OpenClaw Tool 系统 = 全链路工具调用管控底座，承接 LLM / Harness 输出的 tool_call 请求，统一完成校验、权限判定、资源隔离、执行、结果封装与回流。
整套体系遵循 三层Tool治理（行业标准命名，UpClaw核心安全骨架）：

1. 第一层：业务引导层（Skill / SKILL.md）
2. 第二层：执行调度层（ToolAdapter + 沙箱运行载体）
3. 第三层：全局规则拦截层（rules.md 运行时规则引擎）

核心铁律：
任何工具调用不能由Harness/模型直接执行；所有tool_call必须上交网关内核Tool系统统一校验流转。
杜绝模型、外部Harness绕过安全防线直接发起高危操作。

Tool系统解决的原生痛点

1. LLM自由调用工具，无权限管控，可随意执行删除、内网访问、数据库变更；
2. 缺少调用次数、并发、时长限制，引发资源雪崩；
3. 代码/Shell执行无隔离，存在逃逸、服务器入侵风险；
4. 工具返回原始超长日志直接灌入上下文，造成上下文腐烂；
5. 缺少统一观测，无法审计谁、何时、调用了什么工具；
6. 多租户、多Agent需要差异化工具黑白名单。

术语先厘清

• Tool（原子工具）：最小执行单元，如 query_order、matplotlib_plot、shell_exec
• Skill（技能）：业务能力封装，由SKILL.md描述调用规范，可由单个或多个Tool组合实现（如matplotlib绘图Skill）
• ToolGroup（工具组）：工具归类分组 shell / db / file / api，支持批量开关权限
• ToolAdapter：可插拔执行适配器，分发工具请求至对应运行载体（HTTP接口、代码沙箱、内部服务）

二、三层Tool治理逐层拆解

第一层｜业务引导层：Skill (SKILL.md)

载体：skills/{skillName}/SKILL.md
归属：六层提示词工程 第4层（工具契约与技能流程层）
作用：柔性引导模型正确调用工具，属于提示词约束，不能作为安全防线

包含内容：

1. 工具名称、入参结构、参数描述、必填项
2. 调用时机、业务使用场景、标准示例代码/调用样例
3. 禁止行为提示（不要读取外部文件、不要使用plt.show()等）

边界重点：
模型存在幻觉，可能无视SKILL.md写出违规调用。
👉 安全不能依赖本层，必须依靠第二层、第三层硬拦截兜底。

第二层｜执行调度层：ToolAdapter + 运行载体

Tool系统核心执行枢纽，可插拔插件架构。
收到标准化tool_call后，路由至对应适配器：

1. HttpToolAdapter：调用外部HTTP业务接口（订单、客户信息查询）
2. SandboxToolAdapter：承载代码执行类Skill（python、shell、matplotlib绘图），对接【代码沙箱双层防护】
3. InternalAdapter：网关内置本地工具（会话信息查询、记忆检索）

配套执行约束：

• 单轮Agent最大工具调用次数限制
• 单工具执行超时强制终止
• 并发限流：同一会话、全局工具并发上限
• 结果预处理：超长输出截断、敏感信息脱敏、过滤内网地址

SandboxToolAdapter 专项联动

复用沙箱双层防护体系：
正则前置静态扫描 → Preamble运行时环境劫持 → unprivileged非特权账号容器隔离。
Matplotlib Skill、通用Python代码执行全部走这条链路。

第三层｜全局规则拦截层：rules.md 规则引擎（硬安全防线）

最高优先级，执行于工具调用最前置，容器创建之前。
属于会话刚性安全约束（六层提示词第1层），同时编译为运行时可执行规则。
规则类型：

1. 工具黑白名单：允许/禁止单个Tool、整个ToolGroup
2. 参数校验规则：禁止入参携带内网IP、路径穿越字符、高危指令
3. 频次规则：每分钟最大调用次数
4. 风险阻断：高危工具必须人工审批（shell、数据库DDL）
5. 子代理工具权限收缩：子代理默认裁剪高危工具组

执行顺序：规则引擎不通过 → 直接拒绝，不进入ToolAdapter，不分配任何沙箱资源。

三、一次tool_call完整标准时序（全链路）

1. Harness（内置/ Codex外部Harness）解析模型输出，产生tool_call结构
2. Harness禁止自行执行，向上提交至网关内核Tool入口
3. 【第三层 规则引擎前置校验 rules.md】
   ├─ 拦截命中 → 生成RulePolicySpan，直接返回调用拒绝，流程终止
   └─ 校验通过，进入下一步
4. 【参数标准化、入参脱敏、基础格式校验】
5. 根据toolName路由，匹配对应ToolAdapter
6. 【第二层 ToolAdapter执行调度】
   a. 如果是沙箱类工具：触发正则静态扫描
   b. 启动隔离运行环境（容器/进程），注入Preamble安全脚本
   c. 执行工具逻辑
   d. 执行完毕销毁沙箱、临时资源
7. 工具原始结果返回，执行后置处理：截断超长文本、脱敏敏感内容
8. 生成标准化tool_result结构
9. 回流至原Harness继续Agent ReAct循环
10. 整条链路生成独立ToolRunSpan存入四层Langfuse

四、Tool系统核心内置能力模块

4.1 工具寻址与注册体系

网关启动扫描两处来源：

1. 内置原生Tool（内存工具、沙箱基础工具）
2. 外部Skill目录 skills/* 动态注册Skill绑定的工具

元数据结构关键字段：

toolId
skillName
toolGroup
adapterType: http / sandbox / internal
riskLevel: low / medium / high
maxTimeout

风险等级用于rules批量管控：高风险工具默认对子代理关闭。

4.2 ToolGroup 分组批量管控

预定义分组，支持一键批量启用/禁用，避免逐个配置工具：

tool_group:
  shell: shell_exec
  db: db_query, db_execute
  visualize: matplotlib_plot
  file: file_read, file_write

典型配置（rules.md / yaml）

claw.tool.group.shell.enable: false

联动 ConditionalOnToolGroup 条件开关，按租户、Agent、环境差异化管控。

4.3 调用限流与熔断（三级限流）

1. 单会话限流：单轮turn最大工具调用次数 maxTurnToolCalls
2. 会话频控：单session每分钟调用上限
3. 全局工具并发：Sandbox沙箱全局最大并行数量，防止大量容器耗尽服务器资源

4.4 工具结果后置净化（防上下文污染）

所有tool_result统一执行净化策略：

1. 超长字符串截断（防止数万行日志撑爆Transcript）
2. 自动脱敏密钥、内网IP、路径信息
3. 可配置：是否过滤堆栈、stdout调试信息

与Transcript Mirror协同：子代理工具原始输出封闭在镜像内，仅摘要回写父会话。

4.5 人工审批流程（高风险工具）

高风险工具（shell、文件删除、变更类SQL）开启审批模式：
tool_call到达Tool系统后不直接执行，向外推送审批事件；人工确认通过后才继续调度执行；拒绝则返回工具调用失败。

4.6 工具调用观测埋点（四层Langfuse）

每一次合法工具调用生成独立 ToolRunSpan，核心标签：

• toolId、skill、toolGroup、riskLevel
• 执行耗时、超时标记、是否被规则拦截
• 是否来自子代理、context_type(user_request/cron_task)
• 审批状态、截断标记、原始入参（合规开启才记录完整参数）

拦截事件单独生成 RulePolicySpan，区分「参数非法」「工具黑名单」「子代理权限收缩拦截」。

五、Tool系统与全OpenClaw模块联动

5.1 联动 Harness / Harness选择 / Harness回退

1. 硬性约束：所有Harness无论内置/ Codex外部，tool_call必须上交Tool系统；禁止直调工具
2. Harness回退后（codex → builtin），仍然复用同一套Tool规则、沙箱策略，安全基线统一，不会出现两套标准

5.2 联动 并发安全（Per-Request + SessionLock + CronContextHolder）

1. 用户消息流量：Tool调用绑定Per-Request上下文
2. Cron定时任务执行工具：使用CronContextHolder，标记cron_task；定时任务默认自动收紧工具权限
3. SessionLock：同一会话主循环串行执行工具；子代理独立session可并行调用工具，受全局沙箱并发上限管控

5.3 联动 SubAgent三层安全约束 + Transcript Mirror

1. 子代理工具权限自动收缩：rules支持配置子代理可用工具子集，默认剔除高危toolGroup
2. 子代理工具执行结果保存在Mirror镜像，默认不直接回流父会话，仅摘要受控回写，防止上下文污染

5.4 联动 代码沙箱双层防护（正则+Preamble+特权账号）

SandboxToolAdapter是沙箱上层入口；所有Python/Shell/matplotlib工具统一流经沙箱安全防线。

5.5 联动 三层配置分层 + ${VAR:default}

工具超时、黑白名单、审批开关遵循三层配置优先级：
内置默认 < global.yaml < agent.yaml < tenant.yaml < 环境变量
可利用ConditionalOnTenant给金融租户关闭所有db_write、shell工具组。

5.6 联动 Context Compaction

工具超长返回自动预截断，减少上下文压缩压力；
CJK中文场景下，工具返回文本纳入CJK字符占比统计，辅助深度推理自适应打分。

5.7 联动 深度推理自适应

大量工具调用需求会提升任务复杂度得分，自动上调thinking预算；
频繁工具调用失败（报错、被拦截）作为反馈信号进入自适应闭环。

六、执行载体区分（三大ToolAdapter对比）

适配器	承载工具	运行隔离方式	安全约束
InternalAdapter	内存内置工具（记忆检索、会话查询）	进程内函数调用	依赖rules参数校验
HttpToolAdapter	外部业务HTTP接口	网络层面隔离	入参校验、出参脱敏、访问白名单域名
SandboxToolAdapter	Python/Shell/Matplotlib绘图Skill	独立容器，非特权账号	正则前置 + Preamble劫持 + 网络阻断 + 资源限额

七、常见误区澄清

❌ 误区1：SKILL.md（第一层）可以作为安全防线
✅ 纠正：只是提示词引导，模型可无视；安全必须依靠rules.md + 沙箱硬拦截。

❌ 误区2：Codex-Harness可以直接执行代码工具，不走Tool系统
✅ 纠正：属于高危逃逸漏洞；规范要求所有tool_call必须向上转发内核Tool系统校验。

❌ 误区3：子代理拥有独立Harness，就可以放开工具权限
✅ 纠正：子代理默认执行权限收缩策略，由rules全局统一管控。

❌ 误区4：Http工具没有沙箱，不需要安全管控
✅ 纠正：依然存在入参注入、内网地址访问风险，依靠第三层rules参数正则拦截。

❌ 误区5：工具调用失败等同于规则拦截
✅ 纠正：
RulePolicySpan = 前置被规则拦截（还没执行）
ToolRunSpan内异常 = 工具正常调度执行后运行时报错

八、优势总结

1. 统一收敛安全入口，所有模型、所有Harness、父子代理的工具调用汇集一处管控，无逃逸缺口；
2. 三层分层治理兼顾开发便捷（Skill引导）与生产刚性安全（rules+沙箱）；
3. 支持工具分组、多租户差异化权限、人工审批等高阶企业能力；
4. 全链路观测审计，满足等保、数据安全审计需求；
5. 适配器可插拔，新增外部接口工具、新增绘图/数据分析Skill架构无需重构。

九、横向对比

原生AgentScope

工具调用无统一调度层，模型输出直接执行；缺少三层治理、无沙箱标准化约束，仅适合演示原型。

OpenAI Codex

内置工具执行，但权限、黑白名单、审计由厂商管控，无法自定义分层规则，不支持私有化内网安全策略。

Claude Code

本地进程直接执行工具，缺少前置规则引擎、容器沙箱隔离、多租户权限体系。

OpenClaw Tool系统

三层治理+可插拔适配器+沙箱纵深防御，完整适配多租户、父子代理、定时任务混合场景，是企业AI智能体中台标准化工具底座。

十、生产最佳实践

1. 高危工具（shell、数据库变更）默认关闭，如需启用强制开启人工审批；
2. 子代理默认裁剪shell、file_write等高风险工具组；
3. 沙箱工具统一阻断内网网段访问；
4. 所有tool_result开启自动截断与脱敏，避免上下文持续膨胀；
5. Langfuse配置告警：高频出现RulePolicySpan拦截，提示存在持续尝试调用违规工具；
6. 离线私有化部署可通过条件开关整体关闭外网HTTP类工具。