第 8 章：工具系统 🔧
Agent 的"双手"——没有工具，AI 只能说话；有了工具，AI 才能做事。
8.1 工具是什么？
想象一下你是一个老板，有一个超级聪明的助手（AI），但他只有一张嘴——他可以跟你聊天，但没法帮你做任何实际操作。
现在你给了他：
- 一双手 → 可以打字写文件
- 一双眼睛 → 可以看网页
- 一台电脑 → 可以运行代码
- 一部电话 → 可以打电话
这些"能力"就是 工具（Tools）。
在 OpenClaw 里，工具是 Agent 可以调用的"功能函数"。每个工具都有名字、参数和返回值。你把工具交给 AI 模型，它就能在需要的时候主动调用。
工具系统工作流程示意图
8.2 内置工具一览
OpenClaw 提供了一组强大的内置工具，按功能分类：
📁 文件操作工具
| 工具 | 作用 | 场景举例 |
|---|---|---|
read |
读取文件内容 | 查看代码、打开笔记 |
write |
写入/覆盖文件 | 创建新文件、写报告 |
edit |
精确编辑文件某部分 | 修改代码中的某个函数 |
apply_patch |
应用补丁（diff 格式） | 批量代码改动 |
最常用的场景：
你："帮我把昨天的笔记整理一下"
Agent 的思考过程：
1. read("memory/2026-06-25.md") → 读取昨天的笔记
2. write("memory/2026-06-26.md") → 写今天的新笔记
💻 命令执行工具
| 工具 | 作用 | 场景举例 |
|---|---|---|
exec |
运行系统命令 | 编译代码、启动服务 |
process |
管理后台进程 | 查看日志、输入密码 |
安全注意： exec 是有操作风险的。如果不加限制，Agent 可以执行任何命令——包括 rm -rf /。
🌐 网络工具
| 工具 | 作用 | 场景举例 |
|---|---|---|
web_search |
搜索网络 | 查资料、搜新闻 |
web_fetch |
获取网页内容 | 读文档、看博客 |
x_search |
搜索 X/Twitter | 看最新推文 |
🔍 记忆工具
| 工具 | 作用 | 场景举例 |
|---|---|---|
memory_search |
语义搜索记忆 | 查找去年讨论的某个方案 |
memory_get |
读取记忆文件 | 读取某天的笔记 |
🌐 浏览器工具
| 工具 | 作用 | 场景举例 |
|---|---|---|
browser |
控制浏览器 | 网页截图、登录操作、填表单 |
典型场景：
你："帮我看看 Gmail 里有没有新邮件"
Agent 会：browser → 打开 Gmail → 截图 → 告诉你结果
💬 消息工具
| 工具 | 作用 | 场景举例 |
|---|---|---|
message |
发送消息 | 给用户发送通知 |
🖼️ 媒体工具
| 工具 | 作用 | 场景举例 |
|---|---|---|
image |
识别/分析图片 | 看截图里的内容 |
image_generate |
生成图片 | 画图、做封面 |
tts |
文字转语音 | 读文章给你听 |
video_generate |
生成视频 | 简单动画 |
⏰ 自动化工具
| 工具 | 作用 | 场景举例 |
|---|---|---|
cron |
管理定时任务 | 每天早上 8 点发天气 |
heartbeat_respond |
心跳响应 | 定期检查状态 |
8.3 工具权限策略
不是所有工具都应该让 Agent 随意使用。OpenClaw 提供了多层次的权限控制：
全局工具策略
在 openclaw.json 中配置：
{
tools: {
allow: ["read", "write", "web_search", "web_fetch"], // 允许的
deny: ["exec"], // 禁止的
},
}
每 Agent 策略
在多 Agent 场景下，可以为不同 Agent 设置不同策略：
{
agents: {
list: [
{
id: "main",
tools: {
allow: ["read", "write", "edit", "exec", "web_search", "web_fetch"],
},
},
{
id: "guest",
tools: {
deny: ["exec", "write", "edit"], // 访客只能读不能写
},
},
],
},
}
工具策略的检查链条
Agent 调用工具时，OpenClaw 按以下顺序检查：
- 全局 allow/deny 列表 → 是否有权调用？
- Agent 级别策略 → 该 Agent 是否允许？
- 频道权限 → 在当前频道是否可用？
- 沙箱状态 → 在沙箱模式运行？
- 插件可用性 → 所需插件是否安装？
只要其中一层拒绝，工具就不可用。
8.4 exec 安全沙箱
exec 是最强大的工具，也最具风险。OpenClaw 提供了多层安全保护：
安全模式配置
{
tools: {
exec: {
security: "allowlist", // 允许列表模式
ask: "on-miss", // 未匹配规则时询问
timeoutSec: 1800, // 超时时间（秒）
},
},
}
可选的安全模式：
| 模式 | 含义 | 风险等级 |
|---|---|---|
full |
完全访问 | ⚠️ 高 |
allowlist |
仅允许列表中的命令 | ✅ 中等 |
ask |
每个命令都要确认 | ✅ 安全 |
auto |
自动判断低风险命令 | ✅ 推荐 |
deny |
禁止所有 exec | 🛡️ 最安全 |
允许列表模式
在 allowlist 模式下，只有明确允许的命令才能执行：
{
tools: {
exec: {
security: "allowlist",
allowlist: ["git", "node", "python3", "npm", "ls", "cat"],
},
},
}
这样 Agent 只能运行 git、node、python3 等安全命令。
Docker 沙箱（进阶）
如果需要在完全隔离的环境中运行，可以启用 Docker 沙箱：
{
agents: {
defaults: {
sandbox: {
mode: "all", // 所有会话都进沙箱
scope: "agent", // 每 Agent 独立沙箱
},
},
},
}
沙箱模式下，exec 的所有命令都在 Docker 容器内执行，完全隔离于宿主机。
8.5 浏览器工具的使用场景
浏览器工具是 OpenClaw 的"特工装备"——Agent 可以操控真实的浏览器。
它能做什么？
- ✅ 打开网页并截图
- ✅ 填写表单
- ✅ 点击按钮
- ✅ 登录网站
- ✅ 读取页面内容
- ✅ 多标签页管理
实际场景
你："帮我订一张明天去北京的机票"
Agent 过程：
1. browser → 打开携程
2. 搜索"北京" + 明天日期
3. 截图结果给你看
4. 等你选择后下单
你："帮我查一下 GitHub 上那个 PR 的状态"
Agent 过程：
1. browser → 打开 GitHub
2. 找到指定 PR
3. 截图状态给你
浏览器工具的配置
浏览器工具默认可用。如果需要关闭：
{
tools: {
deny: ["browser"],
},
}
8.6 工具失败重试
自动重试机制
当工具调用失败时，OpenClaw 不会直接放弃。它会根据情况自动重试：
| 失败类型 | 重试行为 |
|---|---|
| 网络超时 | 自动重试 1-2 次 |
| API 限流 | 等待后重试 |
| 参数错误 | 报告错误，不重试 |
| 文件不存在 | 报告错误，不重试 |
模型故障切换
如果工具调用失败是因为模型不可用，OpenClaw 会做故障切换：
- 尝试同一模型的另一个认证（多 API Key）
- 如果都不行，切换到配置的备用模型
- 如果全部失败，返回错误说明
{
agents: {
defaults: {
model: {
primary: "anthropic/claude-sonnet-4-6",
fallbacks: ["openai/gpt-5.4", "google/gemini-2.5-pro"],
},
},
},
}
8.7 工具和插件的关系
虽然工具是内置的，但 OpenClaw 的插件系统可以添加更多工具。
| 内置工具 | 插件工具 | |
|---|---|---|
| 来源 | OpenClaw 自带 | 社区或自己开发 |
| 例子 | read, write, browser | Tokenjuice, Canvas |
| 安装 | 无需安装 | 需要安装插件 |
比如安装 Canvas 插件后，Agent 就多了一个 canvas 工具，可以在网页上画图。
8.8 实战：限制一个"只读" Agent
如果你想创建一个只能读文件、查资料，不能写文件、不能执行命令的 Agent：
{
agents: {
list: [
{
id: "reader",
workspace: "~/.openclaw/workspace-reader",
tools: {
allow: [
"read",
"memory_search",
"memory_get",
"web_search",
"web_fetch",
"browser",
"message",
],
deny: [
"write",
"edit",
"apply_patch",
"exec",
"process",
"cron",
"image_generate",
],
},
},
],
},
}
这样这个 Agent 就变成了一个"只读助手"——可以查资料、看网页、回忆记忆，但不能改任何东西。
当当老师 🐾 笔记： 工具是 Agent 能力的边界。给 Agent 什么工具，它就能做什么事。一开始可以宽松一点（open），熟悉了就严格一点（allowlist）。记住一句话：工具越多，Agent 越强，但安全风险也越大。平衡的艺术！
系统教程，帮你把工具用好，再回到任务中。 浏览任务方案 →