08. Tools 原理：OpenClaw 的工具面是怎么组成的

这篇解决什么问题

OpenClaw 的工具系统不只是一个 tools 数组。

src/agents/agent-tools.ts 文件开头就写了它的职责：构建有效的 OpenClaw agent tool surface，把 core、shell、channel、OpenClaw、plugin、Tool Search tools 组装起来，再应用 sandbox、profile、provider、sender、group、sub-agent policy。

这句话很关键。

工具面不是固定的

同一个 OpenClaw，在不同上下文里可用工具可能不同：

main session 和 group session 不同
host 模式和 sandbox 模式不同
不同 sender / allowlist 不同
不同 provider 支持能力不同
不同 agent profile 不同
插件启用情况不同
sub-agent session 不同

所以不要以为某个工具文件存在，模型就一定能调用。

工具来源有哪些

从 agent-tools.ts 的导入和注释可以看到，工具面可能来自：

core tools
shell / exec / process tools
read / write / edit tools
apply_patch
channel tools
OpenClaw tools
plugin tools
Tool Search tools
cron creator tools

这比普通 agent 的工具系统复杂，因为 OpenClaw 要同时面对本地文件、shell、消息平台、插件和 sandbox。

policy 是工具系统的核心

OpenClaw 有很多工具策略：

tool allowlist / denylist
group tool policy
sender tool policy
subagent tool policy
profile tool policy
sandbox policy
provider policy
message provider policy

这些策略共同决定一个工具是否暴露给模型。

所以如果模型“看不到某个工具”，不要只查 schema。先查 policy。

sandbox 会改变工具行为

同样是 read/write/edit，在 host 模式和 sandbox 模式下不一样。

源码里有：

createOpenClawReadTool
createHostWorkspaceWriteTool
createHostWorkspaceEditTool
createSandboxedReadTool
createSandboxedWriteTool
createSandboxedEditTool

这说明工具不是简单函数，而是根据当前运行环境创建不同实现。

before/after hooks

OpenClaw 的工具调用还会经过 hook 包装。

例如 before-tool-call hook 可以在工具执行前检查、记录或拦截；after-tool-call 可以处理结果和状态。

这也是为什么 tool surface 组装过程会很长。

输出为什么要受控

工具结果会进入模型上下文，也可能回到聊天平台。

所以工具系统要控制：

• 参数校验；
• 路径边界；
• 权限策略；
• 输出大小；
• 安全摘要；
• 是否允许 host edit。

下一篇看什么

下一篇看 Tools 源码，按 agent-tools.ts 这条主线拆。