OpenClaw 工具调用机制深度解析

0｜为什么你需要理解工具调用

在 OpenClaw 的架构里，Agent 不是直接操作系统资源的。它通过一套标准化的工具调用（Tool Calling）协议，将自然语言指令转化为具体的系统操作。

理解这套机制，是你在 OpenClaw 上做二次开发、调试异常、或者设计自己的 Agent 行为的前提。

本文将沿着一条完整的调用链路，从指令发出开始，一路追踪到结果返回，拆解每一个环节的设计逻辑。

1｜五步生命周期：一次工具调用的完整旅程

OpenClaw 的工具调用遵循一个清晰的状态机模型，总共五个阶段：

Copy

PENDING → APPROVAL_REQUIRED → EXECUTING → COMPLETED/FAILED

阶段一：PENDING

调用发起。用户的自然语言经过 LLM 解析，被翻译为一个结构化的 ToolCall 对象，包含：

name

：工具名称（如 exec、read、write）

arguments

：参数对象（JSON 格式）

callId

：唯一标识这次调用的 ID

这个阶段极短——只是把 LLM 的输出做一个格式校验。如果参数不符合工具的 JSON Schema，直接在这里 reject，不会进入执行阶段。

阶段二：APPROVAL_REQUIRED

这是 OpenClaw 安全模型的核心环节。

当工具调用涉及写操作、命令执行或外部网络访问时，系统会检查当前的权限策略。如果该操作需要额外授权，调用会在这里暂停，等待人类的确认。

常见的授权方式：

/approve

命令（单次授权）

openclaw allowlist

配置（白名单机制）

配置文件中的 security 策略级别

关键点：Approval 是按调用粒度控制的，不是按 session 或按用户。如果你配置了 allow-always，同一来源的后续同类调用不会再次触发 Approval。

阶段三：EXECUTING

授权通过（或不需要授权），工具开始执行。

执行在 OpenClaw 的运行时环境中进行。根据工具类型，可能是：

内置工具

（read/write/edit）：在 Node.js 进程内直接执行

exec 工具

：fork 一个子进程（默认 PTY 模式），在独立的 shell 环境里运行命令

扩展工具

（来自 skill 或 MCP 协议）：在各自对应的运行时里执行

阶段四：COMPLETED / FAILED

执行完成，结果被序列化并返回给调用方。成功时返回 output，失败时返回 error。这些结果随后被 LLM 继续消费，决定下一步操作或生成自然语言回复。

2｜Tool Manifest：工具是如何被发现的

每个可用工具的元信息，由一个Tool Manifest描述。它不是给人类看的文档，而是给 LLM 看的接口定义。

Manifest 包含以下关键字段：

Copy

name: string

description: string

parameters: JSON Schema (type, properties, required)

returns: JSON Schema

security: { requiresApproval: boolean, riskLevel: 'low'|'medium'|'high' }

description是最关键的部分。LLM 依赖这段文字来决定何时调用、以什么参数调用。一段模糊的 description 会直接导致工具被错误使用或完全忽略。

OpenClaw 的内置工具 description 经过仔细编写。扩展工具（来自 skill）的 Manifest 由 skill 的 SKILL.md 自动生成。

3｜exec 安全模型：最危险也最强大的工具

exec 是 OpenClaw 工具箱里权限最高的工具。OpenClaw 将 exec 操作分为三个风险等级：

风险等级	描述	默认行为
`low`	读操作、查询类命令（`ls`、`cat`、`git status`）	自动放行
`medium`	文件写入、环境修改（`echo`、`mkdir`、`npm install`）	需要 Approval
`high`	系统修改、危险命令（`rm -rf`、`kill`、`sudo`）	强制 Approval + 警告日志

PTY 模式：默认情况下，exec 在 PTY 模式下运行——命令在真实终端环境里执行，支持交互式操作（vim、nano、top 等）。如果不需要 TTY，可设置 pty: false 减少资源开销。

4｜MCP 扩展协议：OpenClaw 的插件系统

MCP（Model Context Protocol）采用客户端-服务器架构。OpenClaw 是 MCP 客户端，外部系统是 MCP 服务器。两者通过 JSON-RPC 2.0 协议通信：

Copy

OpenClaw (MCP Client)

├──→ tools/list （发现可用工具）

├──→ tools/call （执行工具）

├──→ resources/read （读取资源）

└──→ resources/subscribe（订阅实时数据）

Skill 是 OpenClaw 的官方扩展格式。每个 skill 目录下的 SKILL.md 会被自动解析，生成对应的 Tool Manifest 并注册到 OpenClaw。

5｜调试方法

场景	检查点	方法
工具没被调用	description 是否清晰	开启 `verbose: true`，看 LLM 思考过程
参数校验失败	arguments 是否符合 Schema	工具返回的 error 信息包含具体错误
结果不对	命令本身 vs OpenClaw 解析	用 `timeout` 和 `yieldMs` 控制，小范围测试
Approval 卡住	超时？CLI 交互提示被跳过？	检查 `exec.approvalTimeout` 设置

6｜总结

OpenClaw 的工具调用机制核心价值：

标准化

：所有工具共享同一套调用协议

安全性

：通过 Approval 机制和风险分级，确保高危操作被人类知晓

可扩展性

：MCP 协议和 Skill Manifest 让第三方扩展成为可能