09. Tools 源码：agent-tools.ts 怎么组装工具面

这篇解决什么问题

上一篇讲工具原理，这一篇看源码主线。

核心文件是：

src/agents/agent-tools.ts

它不是单个工具实现，而是“工具面组装器”。

先看文件头注释

文件头注释写得很清楚：

Builds the effective OpenClaw agent tool surface.
Assembles core, shell, channel, OpenClaw, plugin, and Tool Search tools,
then applies sandbox, profile, provider, sender, group, and sub-agent policy.

这句话就是源码阅读路线。

第一层：工具创建

你会看到很多 create 函数：

createOpenClawReadTool
createHostWorkspaceWriteTool
createHostWorkspaceEditTool
createSandboxedReadTool
createSandboxedWriteTool
createSandboxedEditTool
createApplyPatchTool
createCodingTools
createOpenClawTools
createToolSearchTools

它们负责把不同能力变成统一的 agent tool。

第二层：schema 和参数校验

相关文件包括：

agent-tools.schema.ts
agent-tools.params.ts
agent-tools-parameter-schema.ts

模型传来的参数不可信。工具执行前要做参数归一化、必填字段检查、类型检查和策略检查。

第三层：policy pipeline

相关文件包括：

agent-tools.policy.ts
tool-policy.ts
tool-policy-pipeline.ts
tool-policy-match.ts
sender-tool-policy.ts

这里决定工具是否允许出现在当前 session。

如果你要排查“为什么工具没出现”，这里比具体 tool handler 更重要。

第四层：workspace 和路径边界

相关文件包括：

agent-tools.read.ts
workspace-dir.ts
tool-fs-policy.ts
sandbox/workspace-mounts.ts

OpenClaw 要防止工具越界读写。尤其是在 group session、sandbox session、sub-agent session 下，workspace 边界非常重要。

第五层：插件和 Tool Search

插件工具来自：

openclaw-plugin-tools.ts
plugins/tools.ts

Tool Search 来自：

tool-search.ts

这说明工具面不是只由 OpenClaw core 决定，插件和动态搜索也会参与。

如果要新增一个内置工具

先判断它属于哪类：

文件/编辑类
shell/process 类
channel 类
OpenClaw 管理类
plugin 暴露类
Tool Search 类

然后找已有同类工具的创建方式，不要直接把 handler 硬塞进 Agent loop。

新增工具前必须想清楚

至少回答：

它是否能写文件？
是否需要 sandbox 版本？
是否应该默认允许？
是否受 sender/group policy 限制？
输出会不会太长？
错误信息会不会泄露敏感信息？

下一篇看什么

下一篇看 Gateway。

工具决定能做什么，Gateway 决定消息怎么进来、怎么出去。