工具(OpenClaw)

OpenClaw 为 browser、canvas、nodes 和 cron 暴露一流的 agent 工具。这些替代了旧的 openclaw-* 技能:工具是类型化的,无需 shelling, agent 应直接依赖它们。

禁用工具

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

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

注意事项:

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

工具配置文件(基础 allowlist)

tools.profile 在 tools.allow/tools.deny 之前设置基础工具 allowlist。每个 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 工具):

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

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

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

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

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

Provider 特定的工具策略

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

这在基础工具配置文件之后和 allow/deny 列表之前应用,因此它只能缩小工具集。 Provider 键接受 provider (例如 google-antigravity) 或 provider/model (例如 openai/gpt-5.2)。

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

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

示例(针对不稳定端点的 provider/model 特定 allowlist):

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

示例(针对单个 provider 的 agent 特定覆盖):

{
  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 工具(不包括 provider 插件)

示例(仅允许文件工具 + browser):

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

插件 + 工具

插件可以在核心集之外注册额外的工具(和 CLI 命令)。参见插件了解安装 + 配置,参见技能了解如何将工具使用指南注入提示中。一些插件与工具一起提供自己的技能 (例如,语音通话插件)。

可选插件工具:

Lobster: 带有可恢复审批的类型化工作流运行时(需要 gateway 主机上的 Lobster CLI)。
LLM Task: 用于结构化工作流输出的仅 JSON LLM 步骤(可选 schema 验证)。

工具清单

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。

注意事项:

后台运行时返回 status: "running" 和 sessionId。
使用 process 轮询/记录/写入/杀死/清除后台会话。
如果 process 不允许,exec 同步运行并忽略 yieldMs/background。
elevated 由 tools.elevated 加上任何 agents.list[].tools.elevated 覆盖(两者都必须允许)门控,并且是 host=gateway + security=full 的别名。
elevated 仅在 agent 沙箱化时改变行为(否则是无操作)。
host=node 可以定位 macOS 伴侣应用或无头节点主机(openclaw node run)。
gateway/node 审批和 allowlist: 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;来自配置的默认值)

注意事项:

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

web_fetch

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

核心参数:

url (必需)
extractMode (markdown | text)
maxChars (截断长页面)

注意事项:

通过 tools.web.fetch.enabled 启用。
响应被缓存(默认 15 分钟)。
对于 JS 重度站点,优先使用 browser 工具。
参见 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 时,使用 browser.defaultProfile (默认为 "chrome")。
配置文件名称: 仅小写字母数字 + 连字符(最大 64 字符)。
端口范围: 18800-18899 (~100 个配置文件最大)。
远程配置文件仅附加(无 start/stop/reset)。
如果连接了支持浏览器的节点,工具可能自动路由到它(除非您固定 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 ref) 或 element (CSS 选择器) 直接设置 <input type="file">。

canvas

驱动节点 Canvas (present、eval、snapshot、A2UI)。

核心操作:

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

注意事项:

底层使用 gateway 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):

{
  "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 (primary 或 fallbacks) 时可用,或当可以从默认模型 + 配置的认证推断隐式图像模型时(尽力配对)。
直接使用图像模型(独立于主聊天模型)。

message

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

核心操作:

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

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_list: kinds?, limit?, activeMinutes?, messageLimit? (0 = 无)
sessions_history: sessionKey (或 sessionId), limit?, includeTools?
sessions_send: sessionKey (或 sessionId), message, timeoutSeconds? (0 = fire-and-forget)
sessions_spawn: task, label?, agentId?, model?, runTimeoutSeconds?, cleanup?
session_status: sessionKey? (默认当前;接受 sessionId), model? (default 清除覆盖)

注意事项:

main 是规范的直接聊天键;global/unknown 被隐藏。
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 的 allowlist (agents.list[].subagents.allowAgents)。
配置 ["*"] 时,工具包括所有配置的 agent 并标记 allowAny: true。

参数(通用)

Gateway 支持的工具(canvas, nodes, cron):

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

Browser 工具:

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

安全

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

工具如何呈现给 agent

工具通过两个并行通道暴露:

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

这意味着 agent 同时看到"存在哪些工具"和"如何调用它们"。如果工具不出现在系统提示或 schema 中,模型无法调用它。

工具(OpenClaw)

禁用工具

工具配置文件(基础 allowlist)

Provider 特定的工具策略

工具组(简写)

插件 + 工具

工具清单

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