当前位置：首页 > news >正文

OpenClaw从入门到应用——工具（Tools）

news 2026/5/6 17:38:28

通过OpenClaw实现副业收入：《OpenClaw赚钱实录：从“养龙虾“到可持续变现的实践指南》

OpenClaw 提供了一流的代理工具，用于浏览器、画布、节点和定时任务。
这些工具取代了旧的openclaw-*技能：新工具是带类型的，不再通过 shell 调用，
代理应直接依赖它们。

禁用工具

你可以通过openclaw.json中的tools.allow/tools.deny来全局允许/禁用工具
（deny优先）。这可以阻止被禁用的工具被发送给模型提供商。

{ tools: { deny: ["browser"] }, }

注意：

匹配时不区分大小写。
支持*通配符（"*"表示所有工具）。
如果tools.allow只引用了未知或未加载的插件工具名称，OpenClaw 会记录警告并忽略该允许列表，以便核心工具保持可用。

工具配置文件（基础允许列表）

tools.profile在应用tools.allow/tools.deny之前，设置一个基础工具允许列表。
代理级覆盖：agents.list[].tools.profile。

配置文件：

minimal：仅session_status
coding：group:fs,group:runtime,group:sessions,group:memory,image
messaging：group:messaging,sessions_list,sessions_history,sessions_send,session_status
full：无限制（与未设置相同）

示例（默认仅限消息功能，同时也允许 Slack + Discord 工具）：

{ tools: { profile: "messaging", allow: ["slack", "discord"], }, }

示例（使用编码配置文件，但全局禁用 exec/process）：

{ tools: { profile: "coding", deny: ["group:runtime"], }, }

示例（全局编码配置文件，仅支持消息功能的代理）：

{ tools: { profile: "coding" }, agents: { list: [ { id: "support", tools: { profile: "messaging", allow: ["slack"] }, }, ], }, }

特定于提供商的工具策略

使用tools.byProvider可以针对特定提供商（或单个provider/model）进一步限制工具，
而无需更改全局默认设置。
代理级覆盖：agents.list[].tools.byProvider。

此策略在基础工具配置文件之后、允许/禁用列表之前应用，
因此它只能缩小工具集。
提供商的键可以接受provider（例如google-antigravity）或
provider/model（例如openai/gpt-5.2）。

示例（保持全局编码配置文件，但对 Google Antigravity 使用最小工具集）：

{ tools: { profile: "coding", byProvider: { "google-antigravity": { profile: "minimal" }, }, }, }

示例（针对不稳定端点的特定提供商/模型允许列表）：

{ tools: { allow: ["group:fs", "group:runtime", "sessions_list"], byProvider: { "openai/gpt-5.2": { allow: ["group:fs", "sessions_list"] }, }, }, }

示例（针对单个提供商的代理特定覆盖）：

{ agents: { list: [ { id: "support", tools: { byProvider: { "google-antigravity": { allow: ["message", "sessions_list"] }, }, }, }, ], }, }

工具组（简写）

工具策略（全局、代理、沙箱）支持group:*条目，这些条目会展开为多个工具。
在tools.allow/tools.deny中使用它们。

可用的组：

group:runtime：exec,bash,process
group:fs：read,write,edit,apply_patch
group:sessions：sessions_list,sessions_history,sessions_send,sessions_spawn,session_status
group:memory：memory_search,memory_get
group:web：web_search,web_fetch
group:ui：browser,canvas
group:automation：cron,gateway
group:messaging：message
group:nodes：nodes
group:openclaw：所有 OpenClaw 内置工具（不包括提供商插件）

示例（仅允许文件工具 + 浏览器）：

{ tools: { allow: ["group:fs", "browser"], }, }

插件 + 工具

插件可以注册额外的工具（和 CLI 命令），超越核心集。
安装和配置请参阅插件，有关如何将工具使用指南注入提示的信息，请参阅技能。一些插件会随工具一起提供自己的技能（例如，语音通话插件）。

可选的插件工具：

Lobster：带可恢复审批的类型化工作流运行时（需要在网关主机上安装 Lobster CLI）。
LLM Task：仅限 JSON 的 LLM 步骤，用于结构化工作流输出（可选的模式验证）。
Diffs：只读差异查看器和 PNG 或 PDF 文件渲染器，用于前后文本或统一补丁。

工具清单

`apply_patch`

跨一个或多个文件应用结构化补丁。用于多块编辑。
实验性功能：通过tools.exec.applyPatch.enabled启用（仅限 OpenAI 模型）。
tools.exec.applyPatch.workspaceOnly默认为true（限制在工作区内）。只有当你故意希望apply_patch在工作区目录之外写入/删除时，才将其设置为false。

`exec`

在工作区中运行 shell 命令。

核心参数：

command（必需）
yieldMs（超时后自动后台运行，默认 10000）
background（立即后台运行）
timeout（秒；如果超过则终止进程，默认 1800）
elevated（布尔值；如果启用了提权模式且被允许，则在主机上运行；仅在代理被沙箱化时改变行为）
host（sandbox | gateway | node）
security（deny | allowlist | full）
ask（off | on-miss | always）
node（用于host=node的节点 ID/名称）
需要真正的 TTY？设置pty: true。

注意：

当后台运行时，返回带有sessionId的status: "running"。
使用process来轮询/记录/写入/终止/清理后台会话。
如果process被禁用，exec将同步运行并忽略yieldMs/background。
elevated受tools.elevated以及任何agents.list[].tools.elevated覆盖的限制（两者都必须允许），并且是host=gateway+security=full的别名。
elevated仅在代理被沙箱化时改变行为（否则无操作）。
host=node可以针对 macOS 配套应用程序或无头节点主机（openclaw node run）。
网关/节点审批和允许列表：Exec 审批。

`process`

管理后台 exec 会话。

核心操作：

list,poll,log,write,kill,clear,remove

注意：

poll在完成时返回新的输出和退出状态。
log支持基于行的offset/limit（省略offset以获取最后 N 行）。
process的作用域是每个代理；来自其他代理的会话不可见。

`loop-detection`（工具调用循环防护）

OpenClaw 会跟踪最近的工具调用历史，并在检测到重复的无进展循环时阻止或发出警告。
通过tools.loopDetection.enabled: true启用（默认为false）。

{ tools: { loopDetection: { enabled: true, warningThreshold: 10, criticalThreshold: 20, globalCircuitBreakerThreshold: 30, historySize: 30, detectors: { genericRepeat: true, knownPollNoProgress: true, pingPong: true, }, }, }, }

genericRepeat：重复相同工具 + 相同参数的调用模式。
knownPollNoProgress：重复的类似轮询工具且输出相同。
pingPong：交替A/B/A/B无进展模式。
代理级覆盖：agents.list[].tools.loopDetection。

`web_search`

使用 Perplexity、Brave、Gemini、Grok 或 Kimi 搜索网络。

核心参数：

query（必需）
count（1–10；默认来自tools.web.search.maxResults）

注意：

需要所选提供商的 API 密钥（推荐：openclaw configure --section web）。
通过tools.web.search.enabled启用。
响应会被缓存（默认 15 分钟）。
设置请参阅 Web 工具。

`web_fetch`

从 URL 获取并提取可读内容（HTML → markdown/text）。

核心参数：

url（必需）
extractMode（markdown|text）
maxChars（截断长页面）

注意：

通过tools.web.fetch.enabled启用。
maxChars受tools.web.fetch.maxCharsCap限制（默认 50000）。
响应会被缓存（默认 15 分钟）。
对于 JS 密集型网站，优先使用浏览器工具。
设置请参阅 Web 工具。
请参阅 Firecrawl 了解可选的防机器人回退。

`browser`

控制由 OpenClaw 管理的专用浏览器。

核心操作：

status,start,stop,tabs,open,focus,close
snapshot（aria/ai）
screenshot（返回图像块 +MEDIA:<path>）
act（UI 操作：click/type/press/hover/drag/select/fill/resize/wait/evaluate）
navigate,console,pdf,upload,dialog

配置文件管理：

profiles— 列出所有浏览器配置文件及其状态
create-profile— 使用自动分配的端口（或cdpUrl）创建新配置文件
delete-profile— 停止浏览器，删除用户数据，从配置中移除（仅本地）
reset-profile— 终止配置文件端口上的孤立进程（仅本地）

常用参数：

profile（可选；默认为browser.defaultProfile）
target（sandbox|host|node）
node（可选；选择特定的节点 ID/名称）

注意：

需要browser.enabled=true（默认为true；设置为false以禁用）。
所有操作都接受可选的profile参数以支持多实例。
省略profile将使用安全的默认设置：由 OpenClaw 管理的独立浏览器（openclaw）。
当需要现有的登录信息/cookie 且用户在场以点击/批准任何附加提示时，使用profile="user"访问真实的本地主机浏览器。
仅对 Chrome 扩展程序/工具栏按钮附加流程使用profile="chrome-relay"。
profile="user"和profile="chrome-relay"仅限主机；不要将它们与沙箱/节点目标结合使用。
当省略profile时，使用browser.defaultProfile（默认为openclaw）。
配置文件名称：仅限小写字母数字和连字符（最多 64 个字符）。
端口范围：18800-18899（最多约 100 个配置文件）。
远程配置文件仅可附加（无法启动/停止/重置）。
如果连接了具有浏览器能力的节点，该工具可能会自动路由到它（除非你固定了target）。
当安装了 Playwright 时，snapshot默认为ai；使用aria获取无障碍树。
snapshot也支持角色快照选项（interactive,compact,depth,selector），它们返回像e12这样的引用。
act需要来自snapshot的ref（来自 AI 快照的数字12，或来自角色快照的e12）；在极少数需要 CSS 选择器的情况下使用evaluate。
默认避免使用act→wait；仅在特殊情况下使用（没有可靠的 UI 状态可以等待）。
upload可以选择传递ref以在准备就绪后自动点击。
upload也支持inputRef（aria 引用）或element（CSS 选择器）来直接设置<input type="file">。

`canvas`

驱动节点画布（present, eval, snapshot, A2UI）。

核心操作：

present,hide,navigate,eval
snapshot（返回图像块 +MEDIA:<path>）
a2ui_push,a2ui_reset

注意：

在底层使用网关的node.invoke。
如果没有提供node，该工具会选择一个默认节点（单个已连接节点或本地 mac 节点）。
A2UI 仅支持 v0.8（没有createSurface）；CLI 会拒绝带有行错误的 v0.9 JSONL。
快速测试：openclaw nodes canvas a2ui push --node <id> --text "Hello from A2UI"。

`nodes`

发现并定位配对的节点；发送通知；捕获相机/屏幕。

核心操作：

status,describe
pending,approve,reject（配对）
notify（macOSsystem.notify）
run（macOSsystem.run）
camera_list,camera_snap,camera_clip,screen_record
location_get,notifications_list,notifications_action
device_status,device_info,device_permissions,device_health

注意：

相机/屏幕命令需要节点应用程序处于前台。
图像返回图像块 +MEDIA:<path>。
视频返回FILE:<path>（mp4）。
位置返回 JSON 负载（纬度/经度/精度/时间戳）。
run参数：commandargv 数组；可选的cwd,env（KEY=VAL）,commandTimeoutMs,invokeTimeoutMs,needsScreenRecording。

示例（run）：

{"action":"run","node":"office-mac","command":["echo","Hello"],"env":["FOO=bar"],"commandTimeoutMs":12000,"invokeTimeoutMs":45000,"needsScreenRecording":false}

`image`

使用配置的图像模型分析图像。

核心参数：

image（必需的路径或 URL）
prompt（可选；默认为“描述图像。”）
model（可选覆盖）
maxBytesMb（可选大小限制）

注意：

仅在配置了agents.defaults.imageModel（主模型或备用模型）时可用，或者可以从你的默认模型 + 配置的身份验证中推断出隐式图像模型时可用（尽力而为的配对）。
直接使用图像模型（独立于主聊天模型）。

`pdf`

分析一个或多个 PDF 文档。

有关完整行为、限制、配置和示例，请参阅 PDF 工具。

`message`

跨 Discord/Google Chat/Slack/Telegram/WhatsApp/Signal/iMessage/MS Teams 发送消息和频道操作。

核心操作：

send（文本 + 可选媒体；MS Teams 还支持用于自适应卡片的card）
poll（WhatsApp/Discord/MS Teams 投票）
react/reactions/read/edit/delete
pin/unpin/list-pins
permissions
thread-create/thread-list/thread-reply
search
sticker
member-info/role-info
emoji-list/emoji-upload/sticker-upload
role-add/role-remove
channel-info/channel-list
voice-status
event-list/event-create
timeout/kick/ban

注意：

send通过网关路由 WhatsApp；其他频道直接发送。
poll对 WhatsApp 和 MS Teams 使用网关；Discord 投票直接发送。
当消息工具调用绑定到活动聊天会话时，发送操作将被限制在该会话的目标范围内，以避免跨上下文泄漏。

`cron`

管理网关定时任务和唤醒。

核心操作：

status,list
add,update,remove,run,runs
wake（将系统事件排队 + 可选立即心跳）

注意：

add需要一个完整的定时任务对象（与cron.addRPC 相同的模式）。
update使用{ jobId, patch }（为兼容性接受id）。

`gateway`

重新启动或对正在运行的网关进程应用更新（就地）。

核心操作：

restart（授权并发送SIGUSR1进行进程内重启；openclaw gateway就地重启）
config.schema.lookup（一次检查一个配置路径，而无需将完整模式加载到提示上下文中）
config.get
config.apply（验证 + 写入配置 + 重启 + 唤醒）
config.patch（合并部分更新 + 重启 + 唤醒）
update.run（运行更新 + 重启 + 唤醒）

注意：

config.schema.lookup需要一个目标配置路径，例如gateway.auth或agents.list.*.heartbeat。
路径在处理plugins.entries.<id>时可能包含斜杠分隔的插件 ID，例如plugins.entries.pack/one.config。
使用delayMs（默认为 2000）以避免中断正在进行的回复。
config.schema仍然可用于内部控制 UI 流程，不通过代理gateway工具公开。
restart默认启用；设置commands.restart: false以禁用它。

`sessions_list`/`sessions_history`/`sessions_send`/`sessions_spawn`/`session_status`

列出会话、检查记录历史或发送到另一个会话。

核心参数：

sessions_list：kinds?,limit?,activeMinutes?,messageLimit?（0 = 无限制）
sessions_history：sessionKey（或sessionId）,limit?,includeTools?
sessions_send：sessionKey（或sessionId）,message,timeoutSeconds?（0 = 即发即忘）
sessions_spawn：task,label?,runtime?,agentId?,model?,thinking?,cwd?,runTimeoutSeconds?,thread?,mode?,cleanup?,sandbox?,streamTo?,attachments?,attachAs?
session_status：sessionKey?（默认为当前；接受sessionId）,model?（default清除覆盖）

注意：

main是规范的直接聊天键；global/unknown 被隐藏。
messageLimit > 0为每个会话获取最后 N 条消息（过滤掉工具消息）。
会话目标由tools.sessions.visibility控制（默认为tree：当前会话 + 生成的子代理会话）。如果你为多个用户运行共享代理，请考虑设置tools.sessions.visibility: "self"以防止跨会话浏览。
当timeoutSeconds > 0时，sessions_send等待最终完成。
传递/通知在完成后进行，并且是尽力而为的；status: "ok"确认代理运行已完成，而不是通知已传递。
sessions_spawn支持runtime: "subagent" | "acp"（subagent为默认值）。有关 ACP 运行时行为，请参阅 ACP 代理。
对于 ACP 运行时，streamTo: "parent"将初始运行进度摘要作为系统事件路由回请求者会话，而不是直接传递子消息。
sessions_spawn启动一个子代理运行，并将一个通知回复发送回请求者聊天。
- 支持一次性模式（mode: "run"）和持久线程绑定模式（mode: "session"配合thread: true）。
- 如果thread: true且省略了mode，则mode默认为session。
- mode: "session"需要thread: true。
- 如果省略了runTimeoutSeconds，当设置了agents.defaults.subagents.runTimeoutSeconds时，OpenClaw 会使用该值；否则超时默认为0（无超时）。
- Discord 线程绑定流程依赖于session.threadBindings.*和channels.discord.threadBindings.*。
- 回复格式包括Status,Result和紧凑的统计信息。
- Result是助手的完成文本；如果缺失，则使用最新的toolResult作为回退。
手动完成模式生成首先直接发送，并在瞬时故障时进行队列回退和重试（status: "ok"表示运行已完成，不表示通知已传递）。
sessions_spawn支持子代理运行时的内联文件附件（ACP 会拒绝它们）。每个附件具有name,content，可选的encoding（utf8或base64）和mimeType。文件被具体化到子工作区的.openclaw/attachments/<uuid>/中，并附带一个.manifest.json元数据文件。该工具返回一个包含count,totalBytes、每个文件的sha256和relDir的收据。附件内容会自动从记录持久化中删除。
- 通过tools.sessions_spawn.attachments配置限制（enabled,maxTotalBytes,maxFiles,maxFileBytes,retainOnSessionKeep）。
- attachAs.mountPath是为将来挂载实现保留的提示。
sessions_spawn是非阻塞的，并立即返回status: "accepted"。
ACPstreamTo: "parent"响应可能包含streamLogPath（会话范围的*.acp-stream.jsonl），用于跟踪进度历史。
sessions_send运行一个回复式乒乓（回复REPLY_SKIP以停止；最大回合数由session.agentToAgent.maxPingPongTurns决定，0–5）。
在乒乓之后，目标代理运行一个通知步骤；回复ANNOUNCE_SKIP以抑制通知。
沙箱限制：当当前会话被沙箱化且agents.defaults.sandbox.sessionToolsVisibility: "spawned"时，OpenClaw 将tools.sessions.visibility限制为tree。

`agents_list`

列出当前会话可能通过sessions_spawn定位的代理 ID。

注意：

结果受每个代理的允许列表限制（agents.list[].subagents.allowAgents）。
当配置为["*"]时，该工具包括所有已配置的代理，并标记allowAny: true。

参数（通用）

基于网关的工具（canvas,nodes,cron）：

gatewayUrl（默认为ws://127.0.0.1:18789）
gatewayToken（如果启用了身份验证）
timeoutMs

注意：当设置了gatewayUrl时，请显式包含gatewayToken。工具不会继承覆盖的配置或环境凭据，缺少显式凭据将被视为错误。

浏览器工具：

profile（可选；默认为browser.defaultProfile）
target（sandbox|host|node）
node（可选；固定特定的节点 ID/名称）
故障排除指南：
- Linux 启动/CDP 问题：浏览器故障排除（Linux）
- WSL2 网关 + Windows 远程 Chrome CDP：WSL2 + Windows + 远程 Chrome CDP 故障排除