OpenClaw内置工具详解

OpenClaw 内置工具详解

本文档详细说明 OpenClaw 项目中供大模型使用的内置工具（Built-in Tools）

概述

OpenClaw 为大模型提供了一套完整的内置工具，使 AI Agent 能够执行文件操作、网络搜索、设备控制、消息发送等多样化任务。这些工具通过 createOpenClawCodingTools 函数统一整合，并提供给 AI 模型使用。

主要源码位置：

工具入口：src/agents/pi-tools.ts
工具定义：src/agents/openclaw-tools.ts
工具实现：src/agents/tools/

工具分类总览

类别	工具数量	说明
核心编码工具	5+	来自 pi-coding-agent 的基础工具
浏览器控制	1	browser 浏览器控制工具
消息通信	2	message 消息发送、tts 语音合成
网络工具	2	web_search 网络搜索、web_fetch 网页抓取
媒体分析	2	image 图像理解、pdf PDF分析
设备控制	2	nodes 设备控制、canvas Canvas演示控制
网关系统	2	gateway 网关控制、cron 定时任务
内存记忆	1	memory_search 语义搜索记忆
会话管理	7	sessions_* 系列工具
Agent管理	2	agents_list、subagents

详细工具说明

一、核心编码工具

来自 @mariozechner/pi-coding-agent 包的基础工具。

1. read - 文件读取工具

typescript 复制代码

// 位置：pi-coding-agent 内置
// 功能：读取文件内容

参数：

path: 文件路径（必需）
from: 起始行号（可选）
lines: 读取行数（可选）
maxChars: 最大字符数限制

特性：

支持图像描述（当模型无原生视觉能力时）
支持行号定位
可配置图像 sanitization 限制

2. write - 文件写入工具

typescript 复制代码

// 位置：pi-coding-agent 内置
// 功能：创建或写入文件

参数：

path: 文件路径（必需）
content: 文件内容（必需）

安全策略：

可配置 workspaceOnly 限制
沙箱环境下可能被禁用

3. edit - 文件编辑工具

typescript 复制代码

// 位置：pi-coding-agent 内置
// 功能：编辑现有文件

参数：

path: 文件路径
oldString: 要替换的原文
newString: 替换后的新内容

约束：

需要精确匹配 oldString
沙箱环境下可能被禁用

4. apply_patch - 补丁应用工具

typescript 复制代码

// 位置：src/agents/apply-patch.ts
// 功能：通过 unified diff 格式应用代码补丁

适用条件：

仅适用于 OpenAI 提供商
需要在配置中启用 tools.exec.applyPatch

5. exec/bash - 命令执行工具

typescript 复制代码

// 位置：src/agents/bash-tools.ts
// 功能：执行 Shell 命令或脚本

参数：

command: 要执行的命令
timeout: 超时时间（秒）
context: 执行上下文

安全特性：

支持 safeBins 白名单
支持 pathPrepend 路径配置
支持后台进程管理
支持沙箱隔离执行

二、OpenClaw 特有工具

1. browser - 浏览器控制工具

typescript 复制代码

// 文件：src/agents/tools/browser-tool.ts

功能：控制浏览器执行各种自动化操作

支持的操作：

操作	说明
start	启动浏览器
stop	停止浏览器
navigate	导航到 URL
act	执行交互操作（点击、输入等）
screenshot	截取屏幕截图
file_choose	处理文件选择
save_pdf	保存 PDF
tabs	管理标签页

运行模式：

sandbox: 沙箱浏览器（在隔离环境中运行）
host: 宿主机浏览器
node: 通过 Gateway 节点运行

2. message - 消息发送工具

typescript 复制代码

// 文件：src/agents/tools/message-tool.ts

功能：向各种消息渠道发送消息

支持的渠道：

Discord
Telegram
WhatsApp
Signal
iMessage
SMS

功能特性：

发送文本消息
发送附件（图片、文件等）
创建交互式按钮
创建模态框表单
发送带特效的消息
创建投票

重要参数：

action: 操作类型（send, reply, broadcast 等）
channel: 目标渠道
target: 目标用户/频道
text: 消息内容
attachment: 附件

3. tts - 文字转语音工具

typescript 复制代码

// 文件：src/agents/tools/tts-tool.ts

功能：将文本转换为语音并发送

参数：

text: 要转换的文本
channel: 可选的渠道标识（影响输出格式）

音频文件路径
特殊标记 [[audio_as_voice]] 表示语音气泡形式

4. web_search - 网络搜索工具

typescript 复制代码

// 文件：src/agents/tools/web-search.ts

功能：执行网络搜索

默认提供商：Brave Search

可配置的提供商：

Brave
Tavily
Serper
DuckDuckGo

特性：

自动检测可用的 API 密钥
支持配置多个提供商
沙箱环境默认启用

5. web_fetch - 网页抓取工具

typescript 复制代码

// 文件：src/agents/tools/web-fetch.ts

功能：获取网页内容

参数：

url: 目标 URL（必需）
extractMode: 提取模式（markdown/text）
maxChars: 最大返回字符数

高级特性：

Firecrawl 支持（需配置 API）
SSRF 防护
响应缓存
内容截断保护

6. image - 图像理解工具

typescript 复制代码

// 文件：src/agents/tools/image-tool.ts

功能：使用 AI 模型分析图像内容

使用场景：

描述图像内容
提取图像中的文字（OCR）
图像问答

模型选择：

优先使用配置的 explicit 模型
尝试与主模型配对（同提供商）
回退到 OpenAI/Anthropic

参数：

path: 图像路径或 URL
prompt: 分析提示词（可选）
maxTokens: 最大 token 数

7. pdf - PDF 文档分析工具

typescript 复制代码

// 文件：src/agents/tools/pdf-tool.ts

功能：分析 PDF 文档内容

特性：

文本提取
图像分析
页面范围选择
AI 问答

参数：

path: PDF 文件路径
prompt: 分析提示词
maxPages: 最大页数限制
pageRange: 页面范围（如 "1-10"）

8. nodes - 设备控制工具

typescript 复制代码

// 文件：src/agents/tools/nodes-tool.ts

功能：通过 Gateway 控制连接的 iOS/Android 设备

支持的操作：

操作	说明
status	节点状态
describe	节点描述
camera_snap	相机拍照
camera_clip	相机录像
camera_list	列出可用相机
photos_latest	获取最新照片
screen_record	屏幕录制
location_get	获取位置
notifications_list	列出通知
notifications_action	处理通知
device_status	设备状态
device_info	设备信息
device_permissions	设备权限
device_health	设备健康状态
run	运行命令
invoke	调用命令

特殊操作：

pending/approve/reject: 审批流操作

9. canvas - Canvas 演示控制工具

typescript 复制代码

// 文件：src/agents/tools/canvas-tool.ts

功能：控制 macOS/iOS Canvas 演示功能

操作：

操作	说明
present	开始演示
hide	隐藏演示
navigate	导航到 URL
eval	执行 JavaScript
snapshot	获取快照
a2ui_push	推送 UI 定义
a2ui_reset	重置 UI

10. gateway - 网关控制工具

typescript 复制代码

// 文件：src/agents/tools/gateway-tool.ts

功能：控制 OpenClaw Gateway

操作：

操作	说明
restart	重启网关
config.get	获取配置
config.schema.lookup	查看配置 schema
config.apply	应用配置
config.patch	修补配置
update.run	执行更新

安全限制：

仅限 owner（所有者）使用
需要在配置中启用 commands.restart

11. cron - 定时任务管理工具

typescript 复制代码

// 文件：src/agents/tools/cron-tool.ts

功能：管理定时任务和提醒

操作：

操作	说明
status	任务状态
list	列出任务
add	添加任务
update	更新任务
remove	删除任务
run	立即运行
runs	查看运行记录
wake	唤醒任务

任务类型：

定时消息
Webhook 触发
循环任务

12. memory_search - 记忆搜索工具

typescript 复制代码

// 文件：src/agents/tools/memory-tool.ts

功能：语义搜索记忆文件

搜索范围：

MEMORY.md - 主记忆文件
memory/*.md - 其他记忆文件
可选的会话记录

使用场景：

回答关于之前工作的问题
查找决策历史
回忆人物、偏好、待办事项

参数：

query: 搜索查询
maxResults: 最大结果数
minScore: 最低相关度分数

三、会话管理工具组

13. sessions_list - 会话列表工具

typescript 复制代码

// 文件：src/agents/tools/sessions-list-tool.ts

功能：列出当前会话

参数：

kinds: 会话类型过滤（main/group/cron/hook/node/other）
limit: 返回数量限制
activeMinutes: 活跃时间过滤
messageLimit: 消息数量限制

14. sessions_history - 会话历史工具

typescript 复制代码

// 文件：src/agents/tools/sessions-history-tool.ts

功能：获取会话的历史消息

15. sessions_send - 会话消息发送工具

typescript 复制代码

// 文件：src/agents/tools/sessions-send-tool.ts

功能：向指定会话发送消息

16. sessions_spawn - 会话创建工具

typescript 复制代码

// 文件：src/agents/tools/sessions-spawn-tool.ts

功能：创建新的子会话

用途：

开启新的对话分支
创建并行处理任务
子代理 spawn

17. sessions_yield - 会话控制让出工具

typescript 复制代码

// 文件：src/agents/tools/sessions-yield-tool.ts

功能：让出控制权，返回父会话

18. session_status - 会话状态工具

typescript 复制代码

// 文件：src/agents/tools/session-status-tool.ts

功能：获取当前会话的状态信息

19. agents_list - Agent 列表工具

typescript 复制代码

// 文件：src/agents/tools/agents-list-tool.ts

功能：列出所有配置的 Agent

20. subagents - 子 Agent 管理工具

typescript 复制代码

// 文件：src/agents/tools/subagents-tool.ts

功能：管理已 spawn 的子 Agent

操作：

操作	说明
list	列出子 Agent
kill	终止子 Agent
steer	引导子 Agent

工具安全策略

OpenClaw 实现了多层次的工具安全控制：

1. 所有者限制

某些敏感工具标记为 ownerOnly，仅配置的所有者可以使用：

typescript 复制代码

{
  name: "gateway",
  ownerOnly: true,
  // ...
}

2. 工具策略管道

通过配置文件细粒度控制工具访问：

typescript 复制代码

// 策略检查顺序
applyToolPolicyPipeline({
  steps: [
    profilePolicy,        // Profile 级别策略
    providerProfilePolicy, // 提供商级别策略
    globalPolicy,         // 全局策略
    agentPolicy,          // Agent 策略
    groupPolicy,          // 群组策略
    sandboxPolicy,        // 沙箱策略
    subagentPolicy,       // 子 Agent 策略
  ]
})

3. 沙箱隔离

支持在隔离环境中运行工具：

sandboxed: 文件系统隔离
workspaceOnly: 仅允许访问工作区
read-only: 只读模式

4. 文件系统策略

typescript 复制代码

// 可配置的 fsPolicy
{
  workspaceOnly: true,    // 仅工作区
  allowPaths: [],        // 额外允许的路径
  denyPaths: [],         // 拒绝的路径
}

工具创建流程

复制代码

createOpenClawCodingTools()
    │
    ├── 1. pi-coding-agent 基础工具
    │       ├── read (包装)
    │       ├── write (包装)
    │       ├── edit (包装)
    │       └── apply_patch
    │
    ├── 2. Bash 工具
    │       ├── exec
    │       └── process
    │
    ├── 3. OpenClaw 工具 (createOpenClawTools)
    │       ├── browser
    │       ├── canvas
    │       ├── nodes
    │       ├── cron
    │       ├── message
    │       ├── tts
    │       ├── gateway
    │       ├── agents_list
    │       ├── sessions_*
    │       ├── subagents
    │       ├── web_search
    │       ├── web_fetch
    │       ├── image
    │       └── pdf
    │
    └── 4. 插件工具 (resolvePluginTools)
            └── 第三方扩展工具

配置参考

启用/禁用工具

typescript 复制代码

// config.json
{
  "tools": {
    "web": {
      "search": {
        "enabled": true,
        "provider": "brave"
      },
      "fetch": {
        "enabled": true
      }
    },
    "exec": {
      "enabled": true,
      "security": "strict",
      "safeBins": ["git", "npm", "pnpm"]
    }
  }
}

配置 safeBins

typescript 复制代码

{
  "tools": {
    "exec": {
      "safeBins": ["git", "npm", "pnpm", "node", "bun"],
      "safeBinProfiles": {
        "default": {
          "allow": ["git", "npm"]
        }
      }
    }
  }
}

总结

OpenClaw 提供了一套功能完备的工具系统，使 AI Agent 能够：

文件操作 - 读取、写入、编辑代码文件
命令执行 - 运行 Shell 命令和脚本
浏览器自动化 - 网页浏览和交互
网络能力 - 搜索和抓取网页
多媒体处理 - 图像和 PDF 分析
设备控制 - 通过 Gateway 控制移动设备
消息通信 - 多渠道消息发送
语音合成 - 文字转语音
任务调度 - 定时任务管理
会话管理 - 多会话协作
记忆搜索 - 语义检索历史信息

这套工具系统是 OpenClaw 作为 AI Agent 基础设施的核心组成部分。