3.3 Tool Management¶
本节摘要
从State Management角度看，OpenClaw Tool Management的核心特点是：5 类工具源多源合并 + 7 层策略管道逐层过滤。与 Claude Code（LLM 分类器做权限判断）不同，OpenClaw 完全用配置驱动——可预测、可审计。本节按「定义 → 组装 → LLM 看到什么 → 何时变化 → 执行门控」展开。
一、每个工具定义了什么¶
核心类型 AgentToolWithMeta，统一三种来源：AnyAgentTool = AgentToolWithMeta | SDKTool | MCPTool。
| 信息 | LLM 可见？ | 说明 |
|---|---|---|
name |
✅ | 工具名称 |
description |
✅ | 功能描述 |
parameters (JSON Schema) |
✅ | LLM 据此构造调用参数 |
meta（来源、权限、分类） |
❌ | 框架用于策略过滤 |
execute |
❌ | 实际执行函数 |
二、工具池怎么组装¶
createOpenClawCodingTools 从 5 类来源逐层叠加：
| 来源 | 说明 | 示例工具 |
|---|---|---|
| 内置 | pi-coding-agent 基底工具 | read、write、edit、exec |
| OpenClaw 专用 | createOpenClawTools |
sessions_spawn、subagents、cron |
| 渠道工具 | listChannelAgentTools |
Slack/Discord 专用工具 |
| 插件工具 | resolveOpenClawPluginToolsForOptions |
各插件注册的工具 |
| MCP 工具 | 外部 MCP 服务器 | 用户配置的任意 MCP 工具 |
按名称去重后，通过 7 层策略管道过滤（见下节）。Sandbox 模式下 read/write/edit 会被替换为沙箱隔离版本。
三、LLM 每次调用看到什么¶
经过组装和过滤后，工具定义通过 toToolDefinitions 转为 LLM 可消费的 Schema。
Schema 标准化：normalizeProviderToolSchemas 允许 provider 插件重写工具 Schema——不同 LLM provider 对工具参数格式有不同要求（OpenAI function calling vs Anthropic tool use），该函数在送入 LLM 前统一处理差异。
结果标准化：normalizeToolExecutionResult 确保无论工具返回何种格式（string/object/stream），都转换为统一的 ToolResult。
四、工具集何时变化¶
场景 1：7 层策略管道过滤¶
工具可见性由 applyToolPolicyPipeline 控制——任一层 deny 即最终 deny：
| 层级 | 策略 | 作用域 | 典型场景 |
|---|---|---|---|
| L1 | 全局 Profile | allow/deny 正则 | 全局禁用 shell_* |
| L2 | Agent 配置 | 按 agentId | 代码审查 Agent 只给 read 类 |
| L3 | Provider 策略 | 按模型供应商 | 某些工具 OpenAI 不支持 |
| L4 | 群组策略 | 多用户隔离 | 按部门限制工具 |
| L5 | 网关 deny list | 全局禁用 | 公网暴露时禁用危险工具 |
| L6 | 所有者策略 | 非 owner 限制 | 非项目所有者不能 git_push |
| L7 | Run 级白名单 | toolsAllow |
单次 run 只允许特定工具 |
场景 2：MCP 热更新¶
MCP 服务器变更后工具池重新组装。OpenClaw 在 MCP 中同时扮演三种角色（这是与 Claude Code 仅消费的最大差异）：
| 角色 | 说明 |
|---|---|
| Consumer | 连接外部 MCP 服务器，物化远程工具 |
| Exposer | 将自身工具通过 MCP 协议暴露给外部 |
| Gateway | 作为 MCP 代理网关，转发请求 |
五、与 Claude Code 的关键差异¶
| 维度 | Claude Code | OpenClaw |
|---|---|---|
| 过滤方式 | LLM 分类器（YOLO） | 配置管道（7 层） |
| 判断成本 | 高（每次 LLM 调用） | 低（纯内存规则匹配） |
| 可审计性 | 低（LLM 不可预测） | 高（配置即审计轨迹） |
| MCP 角色 | 仅消费 | 消费 + 暴露 + 网关 |
| Schema 适配 | 无 | 按 provider 重写 |
关键文件索引¶
| 文件 | 职责 |
|---|---|
src/agents/pi-tools.ts |
createOpenClawCodingTools 组装管线 |
src/agents/openclaw-tools.ts |
OpenClaw 专用工具集 |
src/agents/tools/common.ts |
AgentToolWithMeta 类型 |
src/mcp/ |
MCP 三角色实现 |