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 的基础工具浏览器控制1browser 浏览器控制工具消息通信2message 消息发送、tts 语音合成网络工具2web_search 网络搜索、web_fetch 网页抓取媒体分析2image 图像理解、pdf PDF分析设备控制2nodes 设备控制、canvas Canvas演示控制网关系统2gateway 网关控制、cron 定时任务内存记忆1memory_search 语义搜索记忆会话管理7sessions_* 系列工具Agent管理2agents_list、subagents详细工具说明一、核心编码工具来自mariozechner/pi-coding-agent包的基础工具。1. read - 文件读取工具// 位置pi-coding-agent 内置// 功能读取文件内容参数path: 文件路径必需from: 起始行号可选lines: 读取行数可选maxChars: 最大字符数限制特性支持图像描述当模型无原生视觉能力时支持行号定位可配置图像 sanitization 限制2. write - 文件写入工具// 位置pi-coding-agent 内置// 功能创建或写入文件参数path: 文件路径必需content: 文件内容必需安全策略可配置 workspaceOnly 限制沙箱环境下可能被禁用3. edit - 文件编辑工具// 位置pi-coding-agent 内置// 功能编辑现有文件参数path: 文件路径oldString: 要替换的原文newString: 替换后的新内容约束需要精确匹配 oldString沙箱环境下可能被禁用4. apply_patch - 补丁应用工具// 位置src/agents/apply-patch.ts// 功能通过 unified diff 格式应用代码补丁适用条件仅适用于 OpenAI 提供商需要在配置中启用tools.exec.applyPatch5. exec/bash - 命令执行工具// 位置src/agents/bash-tools.ts// 功能执行 Shell 命令或脚本参数command: 要执行的命令timeout: 超时时间秒context: 执行上下文安全特性支持 safeBins 白名单支持 pathPrepend 路径配置支持后台进程管理支持沙箱隔离执行二、OpenClaw 特有工具1. browser - 浏览器控制工具// 文件src/agents/tools/browser-tool.ts功能控制浏览器执行各种自动化操作支持的操作操作说明start启动浏览器stop停止浏览器navigate导航到 URLact执行交互操作点击、输入等screenshot截取屏幕截图file_choose处理文件选择save_pdf保存 PDFtabs管理标签页运行模式sandbox: 沙箱浏览器在隔离环境中运行host: 宿主机浏览器node: 通过 Gateway 节点运行2. message - 消息发送工具// 文件src/agents/tools/message-tool.ts功能向各种消息渠道发送消息支持的渠道DiscordTelegramWhatsAppSignaliMessageSMS功能特性发送文本消息发送附件图片、文件等创建交互式按钮创建模态框表单发送带特效的消息创建投票重要参数action: 操作类型send, reply, broadcast 等channel: 目标渠道target: 目标用户/频道text: 消息内容attachment: 附件3. tts - 文字转语音工具// 文件src/agents/tools/tts-tool.ts功能将文本转换为语音并发送参数text: 要转换的文本channel: 可选的渠道标识影响输出格式返回音频文件路径特殊标记[[audio_as_voice]]表示语音气泡形式4. web_search - 网络搜索工具// 文件src/agents/tools/web-search.ts功能执行网络搜索默认提供商Brave Search可配置的提供商BraveTavilySerperDuckDuckGo特性自动检测可用的 API 密钥支持配置多个提供商沙箱环境默认启用5. web_fetch - 网页抓取工具// 文件src/agents/tools/web-fetch.ts功能获取网页内容参数url: 目标 URL必需extractMode: 提取模式markdown/textmaxChars: 最大返回字符数高级特性Firecrawl 支持需配置 APISSRF 防护响应缓存内容截断保护6. image - 图像理解工具// 文件src/agents/tools/image-tool.ts功能使用 AI 模型分析图像内容使用场景描述图像内容提取图像中的文字OCR图像问答模型选择优先使用配置的 explicit 模型尝试与主模型配对同提供商回退到 OpenAI/Anthropic参数path: 图像路径或 URLprompt: 分析提示词可选maxTokens: 最大 token 数7. pdf - PDF 文档分析工具// 文件src/agents/tools/pdf-tool.ts功能分析 PDF 文档内容特性文本提取图像分析页面范围选择AI 问答参数path: PDF 文件路径prompt: 分析提示词maxPages: 最大页数限制pageRange: 页面范围如 “1-10”8. nodes - 设备控制工具// 文件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 演示控制工具// 文件src/agents/tools/canvas-tool.ts功能控制 macOS/iOS Canvas 演示功能操作操作说明present开始演示hide隐藏演示navigate导航到 URLeval执行 JavaScriptsnapshot获取快照a2ui_push推送 UI 定义a2ui_reset重置 UI10. gateway - 网关控制工具// 文件src/agents/tools/gateway-tool.ts功能控制 OpenClaw Gateway操作操作说明restart重启网关config.get获取配置config.schema.lookup查看配置 schemaconfig.apply应用配置config.patch修补配置update.run执行更新安全限制仅限 owner所有者使用需要在配置中启用commands.restart11. cron - 定时任务管理工具// 文件src/agents/tools/cron-tool.ts功能管理定时任务和提醒操作操作说明status任务状态list列出任务add添加任务update更新任务remove删除任务run立即运行runs查看运行记录wake唤醒任务任务类型定时消息Webhook 触发循环任务12. memory_search - 记忆搜索工具// 文件src/agents/tools/memory-tool.ts功能语义搜索记忆文件搜索范围MEMORY.md- 主记忆文件memory/*.md- 其他记忆文件可选的会话记录使用场景回答关于之前工作的问题查找决策历史回忆人物、偏好、待办事项参数query: 搜索查询maxResults: 最大结果数minScore: 最低相关度分数三、会话管理工具组13. sessions_list - 会话列表工具// 文件src/agents/tools/sessions-list-tool.ts功能列出当前会话参数kinds: 会话类型过滤main/group/cron/hook/node/otherlimit: 返回数量限制activeMinutes: 活跃时间过滤messageLimit: 消息数量限制14. sessions_history - 会话历史工具// 文件src/agents/tools/sessions-history-tool.ts功能获取会话的历史消息15. sessions_send - 会话消息发送工具// 文件src/agents/tools/sessions-send-tool.ts功能向指定会话发送消息16. sessions_spawn - 会话创建工具// 文件src/agents/tools/sessions-spawn-tool.ts功能创建新的子会话用途开启新的对话分支创建并行处理任务子代理 spawn17. sessions_yield - 会话控制让出工具// 文件src/agents/tools/sessions-yield-tool.ts功能让出控制权返回父会话18. session_status - 会话状态工具// 文件src/agents/tools/session-status-tool.ts功能获取当前会话的状态信息19. agents_list - Agent 列表工具// 文件src/agents/tools/agents-list-tool.ts功能列出所有配置的 Agent20. subagents - 子 Agent 管理工具// 文件src/agents/tools/subagents-tool.ts功能管理已 spawn 的子 Agent操作操作说明list列出子 Agentkill终止子 Agentsteer引导子 Agent工具安全策略OpenClaw 实现了多层次的工具安全控制1. 所有者限制某些敏感工具标记为ownerOnly仅配置的所有者可以使用{name:gateway,ownerOnly:true,// ...}2. 工具策略管道通过配置文件细粒度控制工具访问// 策略检查顺序applyToolPolicyPipeline({steps:[profilePolicy,// Profile 级别策略providerProfilePolicy,// 提供商级别策略globalPolicy,// 全局策略agentPolicy,// Agent 策略groupPolicy,// 群组策略sandboxPolicy,// 沙箱策略subagentPolicy,// 子 Agent 策略]})3. 沙箱隔离支持在隔离环境中运行工具sandboxed: 文件系统隔离workspaceOnly: 仅允许访问工作区read-only: 只读模式4. 文件系统策略// 可配置的 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) └── 第三方扩展工具配置参考启用/禁用工具// config.json{tools:{web:{search:{enabled:true,provider:brave},fetch:{enabled:true}},exec:{enabled:true,security:strict,safeBins:[git,npm,pnpm]}}}配置 safeBins{tools:{exec:{safeBins:[git,npm,pnpm,node,bun],safeBinProfiles:{default:{allow:[git,npm]}}}}}总结OpenClaw 提供了一套功能完备的工具系统使 AI Agent 能够文件操作- 读取、写入、编辑代码文件命令执行- 运行 Shell 命令和脚本浏览器自动化- 网页浏览和交互网络能力- 搜索和抓取网页多媒体处理- 图像和 PDF 分析设备控制- 通过 Gateway 控制移动设备消息通信- 多渠道消息发送语音合成- 文字转语音任务调度- 定时任务管理会话管理- 多会话协作记忆搜索- 语义检索历史信息这套工具系统是 OpenClaw 作为 AI Agent 基础设施的核心组成部分。
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 的基础工具浏览器控制1browser 浏览器控制工具消息通信2message 消息发送、tts 语音合成网络工具2web_search 网络搜索、web_fetch 网页抓取媒体分析2image 图像理解、pdf PDF分析设备控制2nodes 设备控制、canvas Canvas演示控制网关系统2gateway 网关控制、cron 定时任务内存记忆1memory_search 语义搜索记忆会话管理7sessions_* 系列工具Agent管理2agents_list、subagents详细工具说明一、核心编码工具来自mariozechner/pi-coding-agent包的基础工具。1. read - 文件读取工具// 位置pi-coding-agent 内置// 功能读取文件内容参数path: 文件路径必需from: 起始行号可选lines: 读取行数可选maxChars: 最大字符数限制特性支持图像描述当模型无原生视觉能力时支持行号定位可配置图像 sanitization 限制2. write - 文件写入工具// 位置pi-coding-agent 内置// 功能创建或写入文件参数path: 文件路径必需content: 文件内容必需安全策略可配置 workspaceOnly 限制沙箱环境下可能被禁用3. edit - 文件编辑工具// 位置pi-coding-agent 内置// 功能编辑现有文件参数path: 文件路径oldString: 要替换的原文newString: 替换后的新内容约束需要精确匹配 oldString沙箱环境下可能被禁用4. apply_patch - 补丁应用工具// 位置src/agents/apply-patch.ts// 功能通过 unified diff 格式应用代码补丁适用条件仅适用于 OpenAI 提供商需要在配置中启用tools.exec.applyPatch5. exec/bash - 命令执行工具// 位置src/agents/bash-tools.ts// 功能执行 Shell 命令或脚本参数command: 要执行的命令timeout: 超时时间秒context: 执行上下文安全特性支持 safeBins 白名单支持 pathPrepend 路径配置支持后台进程管理支持沙箱隔离执行二、OpenClaw 特有工具1. browser - 浏览器控制工具// 文件src/agents/tools/browser-tool.ts功能控制浏览器执行各种自动化操作支持的操作操作说明start启动浏览器stop停止浏览器navigate导航到 URLact执行交互操作点击、输入等screenshot截取屏幕截图file_choose处理文件选择save_pdf保存 PDFtabs管理标签页运行模式sandbox: 沙箱浏览器在隔离环境中运行host: 宿主机浏览器node: 通过 Gateway 节点运行2. message - 消息发送工具// 文件src/agents/tools/message-tool.ts功能向各种消息渠道发送消息支持的渠道DiscordTelegramWhatsAppSignaliMessageSMS功能特性发送文本消息发送附件图片、文件等创建交互式按钮创建模态框表单发送带特效的消息创建投票重要参数action: 操作类型send, reply, broadcast 等channel: 目标渠道target: 目标用户/频道text: 消息内容attachment: 附件3. tts - 文字转语音工具// 文件src/agents/tools/tts-tool.ts功能将文本转换为语音并发送参数text: 要转换的文本channel: 可选的渠道标识影响输出格式返回音频文件路径特殊标记[[audio_as_voice]]表示语音气泡形式4. web_search - 网络搜索工具// 文件src/agents/tools/web-search.ts功能执行网络搜索默认提供商Brave Search可配置的提供商BraveTavilySerperDuckDuckGo特性自动检测可用的 API 密钥支持配置多个提供商沙箱环境默认启用5. web_fetch - 网页抓取工具// 文件src/agents/tools/web-fetch.ts功能获取网页内容参数url: 目标 URL必需extractMode: 提取模式markdown/textmaxChars: 最大返回字符数高级特性Firecrawl 支持需配置 APISSRF 防护响应缓存内容截断保护6. image - 图像理解工具// 文件src/agents/tools/image-tool.ts功能使用 AI 模型分析图像内容使用场景描述图像内容提取图像中的文字OCR图像问答模型选择优先使用配置的 explicit 模型尝试与主模型配对同提供商回退到 OpenAI/Anthropic参数path: 图像路径或 URLprompt: 分析提示词可选maxTokens: 最大 token 数7. pdf - PDF 文档分析工具// 文件src/agents/tools/pdf-tool.ts功能分析 PDF 文档内容特性文本提取图像分析页面范围选择AI 问答参数path: PDF 文件路径prompt: 分析提示词maxPages: 最大页数限制pageRange: 页面范围如 “1-10”8. nodes - 设备控制工具// 文件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 演示控制工具// 文件src/agents/tools/canvas-tool.ts功能控制 macOS/iOS Canvas 演示功能操作操作说明present开始演示hide隐藏演示navigate导航到 URLeval执行 JavaScriptsnapshot获取快照a2ui_push推送 UI 定义a2ui_reset重置 UI10. gateway - 网关控制工具// 文件src/agents/tools/gateway-tool.ts功能控制 OpenClaw Gateway操作操作说明restart重启网关config.get获取配置config.schema.lookup查看配置 schemaconfig.apply应用配置config.patch修补配置update.run执行更新安全限制仅限 owner所有者使用需要在配置中启用commands.restart11. cron - 定时任务管理工具// 文件src/agents/tools/cron-tool.ts功能管理定时任务和提醒操作操作说明status任务状态list列出任务add添加任务update更新任务remove删除任务run立即运行runs查看运行记录wake唤醒任务任务类型定时消息Webhook 触发循环任务12. memory_search - 记忆搜索工具// 文件src/agents/tools/memory-tool.ts功能语义搜索记忆文件搜索范围MEMORY.md- 主记忆文件memory/*.md- 其他记忆文件可选的会话记录使用场景回答关于之前工作的问题查找决策历史回忆人物、偏好、待办事项参数query: 搜索查询maxResults: 最大结果数minScore: 最低相关度分数三、会话管理工具组13. sessions_list - 会话列表工具// 文件src/agents/tools/sessions-list-tool.ts功能列出当前会话参数kinds: 会话类型过滤main/group/cron/hook/node/otherlimit: 返回数量限制activeMinutes: 活跃时间过滤messageLimit: 消息数量限制14. sessions_history - 会话历史工具// 文件src/agents/tools/sessions-history-tool.ts功能获取会话的历史消息15. sessions_send - 会话消息发送工具// 文件src/agents/tools/sessions-send-tool.ts功能向指定会话发送消息16. sessions_spawn - 会话创建工具// 文件src/agents/tools/sessions-spawn-tool.ts功能创建新的子会话用途开启新的对话分支创建并行处理任务子代理 spawn17. sessions_yield - 会话控制让出工具// 文件src/agents/tools/sessions-yield-tool.ts功能让出控制权返回父会话18. session_status - 会话状态工具// 文件src/agents/tools/session-status-tool.ts功能获取当前会话的状态信息19. agents_list - Agent 列表工具// 文件src/agents/tools/agents-list-tool.ts功能列出所有配置的 Agent20. subagents - 子 Agent 管理工具// 文件src/agents/tools/subagents-tool.ts功能管理已 spawn 的子 Agent操作操作说明list列出子 Agentkill终止子 Agentsteer引导子 Agent工具安全策略OpenClaw 实现了多层次的工具安全控制1. 所有者限制某些敏感工具标记为ownerOnly仅配置的所有者可以使用{name:gateway,ownerOnly:true,// ...}2. 工具策略管道通过配置文件细粒度控制工具访问// 策略检查顺序applyToolPolicyPipeline({steps:[profilePolicy,// Profile 级别策略providerProfilePolicy,// 提供商级别策略globalPolicy,// 全局策略agentPolicy,// Agent 策略groupPolicy,// 群组策略sandboxPolicy,// 沙箱策略subagentPolicy,// 子 Agent 策略]})3. 沙箱隔离支持在隔离环境中运行工具sandboxed: 文件系统隔离workspaceOnly: 仅允许访问工作区read-only: 只读模式4. 文件系统策略// 可配置的 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) └── 第三方扩展工具配置参考启用/禁用工具// config.json{tools:{web:{search:{enabled:true,provider:brave},fetch:{enabled:true}},exec:{enabled:true,security:strict,safeBins:[git,npm,pnpm]}}}配置 safeBins{tools:{exec:{safeBins:[git,npm,pnpm,node,bun],safeBinProfiles:{default:{allow:[git,npm]}}}}}总结OpenClaw 提供了一套功能完备的工具系统使 AI Agent 能够文件操作- 读取、写入、编辑代码文件命令执行- 运行 Shell 命令和脚本浏览器自动化- 网页浏览和交互网络能力- 搜索和抓取网页多媒体处理- 图像和 PDF 分析设备控制- 通过 Gateway 控制移动设备消息通信- 多渠道消息发送语音合成- 文字转语音任务调度- 定时任务管理会话管理- 多会话协作记忆搜索- 语义检索历史信息这套工具系统是 OpenClaw 作为 AI Agent 基础设施的核心组成部分。
