工具 (OpenClaw)

OpenClaw 为浏览器、画布、节点和定时任务公开了一流的 agent 工具。这些工具替代了旧的 openclaw-* 技能:工具具有类型安全、无需 shell 调用, agent 应该直接依赖这些工具。

禁用工具

您可以通过 openclaw.json 中的 tools.allow / tools.deny 全局允许/拒绝工具 (拒绝优先)。这可以防止不允许的工具被发送到模型提供商。

json5

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

注意:

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

工具配置文件(基础允许列表)

tools.profile 在 tools.allow/tools.deny 之前设置基础工具允许列表。按 agent 覆盖: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 工具):

json5

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

示例(编码配置文件,但在任何地方都拒绝 exec/process):

json5

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

示例(全局编码配置文件,仅消息支持的 agent):

json5

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

特定于提供商的工具策略

使用 tools.byProvider 为特定提供商(或单个 provider/model)进一步限制工具, 而无需更改全局默认值。按 agent 覆盖:agents.list[].tools.byProvider。

这在基础工具配置文件之后、允许/拒绝列表之前应用, 因此它只能缩小工具集。提供商键接受 provider(例如 google-antigravity) 或 provider/model(例如 openai/gpt-5.2)。

示例(保持全局编码配置文件,但为 Google Antigravity 使用最小工具集):

json5

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

示例(针对不稳定端点的特定于提供商/模型的允许列表):

json5

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

示例(单个提供商的特定于 agent 的覆盖):

json5

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

工具组(简写)

工具策略(全局、agent、沙箱)支持扩展到多个工具的 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 工具(不包括提供商插件)

示例(仅允许文件工具 + 浏览器):

json5

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

插件 + 工具

插件可以注册额外的工具(和 CLI 命令),超出核心集合。有关安装和配置,请参见插件,有关如何将工具使用指南注入提示,请参见技能。某些插件随工具一起提供自己的技能(例如,语音通话插件)。

可选插件工具:

Lobster:具有可恢复批准的类型化工作流运行时(需要在网关主机上安装 Lobster CLI)。
LLM Task:用于结构化工作流输出的纯 JSON LLM 步骤(可选架构验证)。

工具清单

`apply_patch`

在一个或多个文件中应用结构化补丁。用于多块编辑。实验性:通过 tools.exec.applyPatch.enabled 启用(仅限 OpenAI 模型)。

`exec`

在工作空间中运行 shell 命令。

核心参数:

command(必需)
yieldMs(超时后自动后台运行,默认 10000)
background(立即后台运行)
timeout(秒;如果超过则终止进程,默认 1800)
elevated(布尔;如果启用/允许提升模式,则在主机上运行;仅在 agent 被沙箱化时改变行为)
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 仅在 agent 被沙箱化时改变行为(否则它是无操作)。
host=node 可以针对 macOS 配套应用或无头节点主机(openclaw node run)。
网关/节点批准和允许列表:Exec 批准。

`process`

管理后台 exec 会话。

核心操作:

list、poll、log、write、kill、clear、remove

注意:

poll 返回新输出和完成时的退出状态。
log 支持基于行的 offset/limit(省略 offset 以获取最后 N 行)。
process 的作用域为每个 agent;来自其他 agent 的会话不可见。

`web_search`

使用 Brave Search API 搜索网络。

核心参数:

query(必需)
count(1–10;默认来自 tools.web.search.maxResults)

注意:

需要 Brave API 密钥(推荐:openclaw configure --section web,或设置 BRAVE_API_KEY)。
通过 tools.web.search.enabled 启用。
响应被缓存(默认 15 分钟)。
有关设置,请参见 Web 工具。

`web_fetch`

从 URL 获取并提取可读内容(HTML → markdown/文本)。

核心参数:

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 操作:点击/输入/按键/悬停/拖动/选择/填充/调整大小/等待/评估)
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 时,使用 browser.defaultProfile(默认为 "chrome")。
配置文件名称:仅小写字母数字 + 连字符(最多 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`

驱动节点 Canvas(呈现、评估、快照、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(macOS system.notify)
run(macOS system.run)
camera_snap、camera_clip、screen_record
location_get

注意:

相机/屏幕命令需要节点应用在前台。
图像返回图像块 + MEDIA:<path>。
视频返回 FILE:<path>(mp4)。
位置返回 JSON 负载(纬度/经度/精度/时间戳)。
run 参数:command argv 数组;可选的 cwd、env(KEY=VAL)、commandTimeoutMs、invokeTimeoutMs、needsScreenRecording。

示例(run):

json

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

`image`

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

核心参数:

image(必需的路径或 URL)
prompt(可选;默认为 "Describe the image.")
model(可选覆盖)
maxBytesMb(可选大小上限)

注意:

仅在配置了 agents.defaults.imageModel(主要或回退)或当可以从您的默认模型 + 配置的身份验证推断出隐式图像模型时可用(尽力而为的配对)。
直接使用图像模型(独立于主聊天模型)。

`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.add RPC 相同的架构)。
update 使用 { id, patch }。

`gateway`

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

核心操作:

restart(授权 + 发送 SIGUSR1 以进行进程内重启;openclaw gateway 就地重启)
config.get / config.schema
config.apply(验证 + 写入配置 + 重启 + 唤醒)
config.patch(合并部分更新 + 重启 + 唤醒)
update.run(运行更新 + 重启 + 唤醒)

注意:

使用 delayMs(默认为 2000)以避免中断正在进行的回复。
restart 默认禁用;使用 commands.restart: true 启用。

`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?、agentId?、model?、runTimeoutSeconds?、cleanup?
session_status:sessionKey?(默认当前;接受 sessionId)、model?(default 清除覆盖)

注意:

main 是规范的直接聊天键;全局/未知被隐藏。
messageLimit > 0 获取每个会话的最后 N 条消息(工具消息已过滤)。
sessions_send 在 timeoutSeconds > 0 时等待最终完成。
交付/通知在完成后发生,是尽力而为的;status: "ok" 确认 agent 运行完成,而不是通知已交付。
sessions_spawn 启动子 agent 运行并将通知回复发回请求者聊天。
sessions_spawn 是非阻塞的,立即返回 status: "accepted"。
sessions_send 运行回复乒乓球(回复 REPLY_SKIP 以停止;通过 session.agentToAgent.maxPingPongTurns 最大回合,0–5)。
乒乓球之后,目标 agent 运行通知步骤;回复 ANNOUNCE_SKIP 以抑制通知。

`agents_list`

列出当前会话可以使用 sessions_spawn 定位的 agent id。

注意:

结果受每个 agent 允许列表(agents.list[].subagents.allowAgents)限制。
当配置了 ["*"] 时,工具包括所有配置的 agent 并标记 allowAny: true。

参数(通用)

网关支持的工具(canvas、nodes、cron):

gatewayUrl(默认 ws://127.0.0.1:18789)
gatewayToken(如果启用了身份验证)
timeoutMs

浏览器工具:

profile(可选;默认为 browser.defaultProfile)
target(sandbox | host | node)
node(可选;固定特定的节点 id/名称)

安全性

避免直接 system.run;仅在获得明确用户同意的情况下使用 nodes → run。
尊重用户对相机/屏幕捕获的同意。
在调用媒体命令之前使用 status/describe 确保权限。

工具如何呈现给 agent

工具通过两个并行通道公开:

系统提示文本:人类可读的列表 + 指南。
工具架构:发送到模型 API 的结构化函数定义。

这意味着 agent 既看到"存在哪些工具"又看到"如何调用它们"。如果工具没有出现在系统提示或架构中,模型就无法调用它。

工具 (OpenClaw) ​

禁用工具 ​

工具配置文件(基础允许列表) ​

特定于提供商的工具策略 ​

工具组(简写) ​

插件 + 工具 ​

工具清单 ​

apply_patch ​

exec ​

process ​

web_search ​

web_fetch ​

browser ​

canvas ​

nodes ​

image ​

message ​

cron ​

gateway ​

sessions_list / sessions_history / sessions_send / sessions_spawn / session_status ​

agents_list ​

参数(通用) ​

推荐的 agent 流程 ​

安全性 ​

工具如何呈现给 agent ​

工具 (OpenClaw)

禁用工具

工具配置文件(基础允许列表)

特定于提供商的工具策略

工具组(简写)

插件 + 工具

工具清单

`apply_patch`

`exec`

`process`

`web_search`

`web_fetch`

`browser`

`canvas`

`nodes`

`image`

`message`

`cron`

`gateway`

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

`agents_list`

参数(通用)

推荐的 agent 流程

安全性

工具如何呈现给 agent