Tools（OpenClaw）

OpenClaw 提供了 一流的 agent 工具，包括 browser、canvas、nodes 和 cron。这些工具取代了旧的 openclaw-* skills：工具是类型化的，不需要 shell 调用， agent 可以直接使用它们。

禁用工具

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

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

注意：

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

Tool profiles（基础白名单）

tools.profile 设置一个 基础工具白名单，在 tools.allow/tools.deny 之前生效。单个 agent 覆盖：agents.list[].tools.profile。

Profiles：

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"],
  },
}

示例（coding profile，但全局拒绝 exec/process）：

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

示例（全局 coding profile，support agent 仅消息功能）：

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

特定提供商的工具策略

使用 tools.byProvider 可以为特定提供商（或单个 provider/model）进一步限制工具，而不改变全局默认设置。单个 agent 覆盖：agents.list[].tools.byProvider。

这会在基础 tool profile 之后、allow/deny 列表之前应用，所以它只能缩小工具集。 Provider 键接受 provider（如 google-antigravity）或 provider/model（如 openai/gpt-5.2）。

示例（保持全局 coding profile，但 Google Antigravity 使用 minimal 工具）：

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

示例（为不稳定的端点设置 provider/model 专属白名单）：

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

示例（agent 专属的单个 provider 覆盖）：

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

Tool groups（简写）

工具策略（全局、agent、sandbox）支持 group:* 条目，可以展开为多个工具。在 tools.allow / tools.deny 中使用这些。

可用的 groups：

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 工具（不包括 provider plugins）

示例（仅允许文件工具 + browser）：

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

Plugins + tools

Plugins 可以注册额外的工具（和 CLI 命令），超出核心工具集。查看 Plugins 了解安装和配置，查看 Skills 了解如何将工具使用指导注入到 prompts 中。一些 plugins 会在工具旁边附带自己的 skills （例如，voice-call plugin）。

可选的 plugin 工具：

Lobster：类型化的工作流运行时，支持可恢复的审批（需要在 gateway 主机上安装 Lobster CLI）。
LLM Task：仅 JSON 的 LLM 步骤，用于结构化工作流输出（可选的 schema 验证）。

工具清单

`apply_patch`

在一个或多个文件中应用结构化补丁。用于多块编辑。实验性功能：通过 tools.exec.applyPatch.enabled 启用（仅 OpenAI 模型）。

`exec`

在 workspace 中运行 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 的 node id/name）
需要真正的 TTY？设置 pty: true。

注意：

后台运行时返回 status: "running" 和一个 sessionId。
使用 process 来轮询/记录/写入/杀死/清除后台 sessions。
如果 process 被禁用，exec 会同步运行并忽略 yieldMs/background。
elevated 受 tools.elevated 以及任何 agents.list[].tools.elevated 覆盖的限制（两者都必须允许），是 host=gateway + security=full 的别名。
elevated 仅在 agent 被沙箱化时改变行为（否则是无操作）。
host=node 可以定位到 macOS companion app 或无头 node 主机（openclaw node run）。
gateway/node 审批和白名单：Exec approvals。

`process`

管理后台 exec sessions。

核心操作：

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

注意：

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

`web_search`

使用 Brave Search API 搜索网络。

核心参数：

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

注意：

需要 Brave API key（推荐：openclaw configure --section web，或设置 BRAVE_API_KEY）。
通过 tools.web.search.enabled 启用。
响应会被缓存（默认 15 分钟）。
查看 Web tools 了解设置。

`web_fetch`

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

核心参数：

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

注意：

通过 tools.web.fetch.enabled 启用。
响应会被缓存（默认 15 分钟）。
对于 JS 密集型网站，优先使用 browser 工具。
查看 Web tools 了解设置。
查看 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

Profile 管理：

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

常用参数：

profile（可选；默认为 browser.defaultProfile）
target（sandbox | host | node）
node（可选；选择特定的 node id/name）注意：
需要 browser.enabled=true（默认为 true；设置 false 以禁用）。
所有操作都接受可选的 profile 参数以支持多实例。
当省略 profile 时，使用 browser.defaultProfile（默认为 “chrome”）。
Profile 名称：仅小写字母数字 + 连字符（最多 64 个字符）。
端口范围：18800-18899（最多约 100 个 profiles）。
远程 profiles 仅支持附加（无 start/stop/reset）。
如果连接了支持浏览器的 node，工具可能会自动路由到它（除非你固定 target）。
当安装了 Playwright 时，snapshot 默认为 ai；使用 aria 获取可访问性树。
snapshot 还支持 role-snapshot 选项（interactive、compact、depth、selector），返回像 e12 这样的引用。
act 需要来自 snapshot 的 ref（AI snapshots 的数字 12，或 role snapshots 的 e12）；对于罕见的 CSS 选择器需求使用 evaluate。
默认避免 act → wait；仅在特殊情况下使用（没有可靠的 UI 状态可等待）。
upload 可以选择传递 ref 以在准备后自动点击。
upload 还支持 inputRef（aria ref）或 element（CSS 选择器）直接设置 <input type="file">。

`canvas`

驱动 node Canvas（present、eval、snapshot、A2UI）。

核心操作：

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

注意：

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

`nodes`

发现和定位配对的 nodes；发送通知；捕获摄像头/屏幕。

核心操作：

status、describe
pending、approve、reject（配对）
notify（macOS system.notify）
run（macOS system.run）
camera_snap、camera_clip、screen_record
location_get

注意：

摄像头/屏幕命令需要 node app 在前台。
图像返回图像块 + MEDIA:<path>。
视频返回 FILE:<path>（mp4）。
位置返回 JSON 负载（lat/lon/accuracy/timestamp）。
run 参数：command argv 数组；可选的 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（可选；默认为 “Describe the image.”）
model（可选覆盖）
maxBytesMb（可选大小限制）

注意：

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

`message`

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

核心操作：

send（文本 + 可选媒体；MS Teams 还支持 card 用于 Adaptive Cards）
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 通过 Gateway 路由 WhatsApp；其他频道直接发送。
poll 对 WhatsApp 和 MS Teams 使用 Gateway；Discord 投票直接发送。
当消息工具调用绑定到活动聊天 session 时，发送会被限制到该 session 的目标，以避免跨上下文泄漏。

`cron`

管理 Gateway cron 作业和唤醒。

核心操作：

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

注意：

add 需要完整的 cron 作业对象（与 cron.add RPC 相同的 schema）。
update 使用 { id, patch }。

`gateway`

重启或对运行中的 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、检查对话历史或发送到另一个 session。

核心参数：

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 是规范的直接聊天键；global/unknown 被隐藏。
messageLimit > 0 获取每个 session 的最后 N 条消息（工具消息被过滤）。
当 timeoutSeconds > 0 时，sessions_send 等待最终完成。
交付/通知发生在完成后，是尽力而为的；status: "ok" 确认 agent 运行完成，而不是通知已交付。
sessions_spawn 启动一个子 agent 运行，并将通知回复发送回请求者聊天。
sessions_spawn 是非阻塞的，立即返回 status: "accepted"。
sessions_send 运行回复乒乓（回复 REPLY_SKIP 停止；最大轮次通过 session.agentToAgent.maxPingPongTurns，0–5）。
乒乓之后，目标 agent 运行一个通知步骤；回复 ANNOUNCE_SKIP 以抑制通知。

`agents_list`

列出当前 session 可以通过 sessions_spawn 定位的 agent ids。

注意：

结果受每个 agent 白名单限制（agents.list[].subagents.allowAgents）。
当配置了 ["*"] 时，工具包括所有配置的 agents 并标记 allowAny: true。

参数（通用）

Gateway 支持的工具（canvas、nodes、cron）：

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

Browser 工具：

profile（可选；默认为 browser.defaultProfile）
target（sandbox | host | node）
node（可选；固定特定的 node id/name）

安全

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

工具如何呈现给 agent

工具通过两个并行渠道暴露：

系统 prompt 文本：人类可读的列表 + 指导。
Tool schema：发送到模型 API 的结构化函数定义。

这意味着 agent 同时看到”存在哪些工具”和”如何调用它们”。如果工具没有出现在系统 prompt 或 schema 中，模型就无法调用它。

Tools（OpenClaw）

禁用工具

Tool profiles（基础白名单）

特定提供商的工具策略

Tool groups（简写）

Plugins + tools

工具清单

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

`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`