工具（OpenClaw）

OpenClaw 提供了一套一等公民级别的 Agent 工具，涵盖 browser、canvas、nodes 和 cron。这些工具取代了旧版 openclaw-* skills——类型化、无需 shell 中转，Agent 可以直接调用。

禁用工具

在 openclaw.json 中通过 tools.allow / tools.deny 全局允许或拒绝工具（deny 优先）。被拒绝的工具不会发送给模型提供商。

{
  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 工具）：

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

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

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

示例（全局 coding 配置文件，support agent 仅消息）：

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

按提供商设置工具策略

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

这个策略在基础工具配置文件之后、allow/deny 列表之前应用，所以它只能缩小工具集。提供商 key 接受 provider（如 google-antigravity）或 provider/model（如 openai/gpt-5.2）。

示例（保持全局 coding 配置文件，但 Google Antigravity 只用最小工具集）：

{
  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 级别覆盖）：

{
  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 工具（不含提供商插件）

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

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

插件 + 工具

插件可以在核心工具集之外注册额外的工具（和 CLI 命令）。参见插件了解安装和配置，Skills 了解工具使用指引如何注入到提示词中。部分插件会随工具一起附带 skills（例如语音通话插件）。

可选插件工具：

Lobster：支持可恢复审批的类型化工作流运行时（需要在 Gateway 主机上安装 Lobster CLI）。
LLM Task：JSON-only LLM 步骤，用于结构化工作流输出（可选 schema 校验）。
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（布尔值；如果启用了 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 审批和白名单：Exec 审批。

`process`

管理后台 exec 会话。

核心操作：

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

注意事项：

poll 返回新输出，完成时返回退出状态。
log 支持基于行的 offset/limit（省略 offset 可获取最后 N 行）。
process 按 Agent 隔离；其他 Agent 的会话不可见。

`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 无进展的交替模式。
按 Agent 覆盖：agents.list[].tools.loopDetection。

`web_search`

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

核心参数：

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

注意事项：

需要所选提供商的 API key（推荐：openclaw configure --section web）。
通过 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 密集型网站，建议用 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）。
snapshot 在安装了 Playwright 时默认为 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（展示、eval、快照、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_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 数据（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（主模型或备选）时可用，或者当能从默认模型 + 已配置的认证中推断出隐式图像模型时（尽力匹配）。
直接使用图像模型（独立于主聊天模型）。

`pdf`

分析一个或多个 PDF 文档。

完整的行为说明、限制、配置和示例，参见 PDF 工具。

`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 投票直接发送。
当消息工具调用绑定到活跃聊天会话时，发送范围限制在该会话的目标，避免跨上下文泄漏。

`cron`

管理 Gateway 定时任务和唤醒。

核心操作：

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

注意事项：

add 需要完整的 cron 任务对象（与 cron.add RPC schema 相同）。
update 使用 { jobId, patch }（id 为兼容性保留）。

`gateway`

重启或更新运行中的 Gateway 进程（原地更新）。

核心操作：

restart（授权 + 发送 SIGUSR1 原地重启；openclaw gateway 原地重启）
config.schema.lookup（逐个查看配置路径，无需将完整 schema 加载到提示词上下文中）
config.get
config.apply（校验 + 写入配置 + 重启 + 唤醒）
config.patch（合并部分更新 + 重启 + 唤醒）
update.run（运行更新 + 重启 + 唤醒）

注意事项：

config.schema.lookup 需要指定配置路径，如 gateway.auth 或 agents.list.*.heartbeat。
路径中可以包含斜杠分隔的插件 id，用于定位 plugins.entries.<id>，例如 plugins.entries.pack/one.config。
使用 delayMs（默认 2000）避免中断正在进行的回复。
config.schema 仍可供内部 Control UI 流程使用，不通过 Agent 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 是标准的直接聊天 key；global/unknown 被隐藏。
messageLimit > 0 获取每个会话最后 N 条消息（过滤工具消息）。
会话定位受 tools.sessions.visibility 控制（默认 tree：当前会话 + 衍生的子 Agent 会话）。如果你运行共享 Agent 服务多个用户，考虑设置 tools.sessions.visibility: "self" 防止跨会话浏览。
sessions_send 在 timeoutSeconds > 0 时等待最终完成。
投递/通告在完成后进行，属于尽力而为；status: "ok" 确认 Agent 运行完成，不代表通告已送达。
sessions_spawn 支持 runtime: "subagent" | "acp"（默认 subagent）。ACP 运行时行为参见 ACP Agents。
ACP 运行时中，streamTo: "parent" 将初始运行进度摘要作为系统事件路由回请求者会话，而非直接子投递。
sessions_spawn 启动子 Agent 运行并将通告回复发回请求者聊天。
- 支持一次性模式（mode: "run"）和持久线程绑定模式（mode: "session" + thread: true）。
- 如果 thread: true 且省略 mode，mode 默认为 session。
- mode: "session" 需要 thread: true。
- 省略 runTimeoutSeconds 时，OpenClaw 在设置了 agents.defaults.subagents.runTimeoutSeconds 时使用该值；否则默认 0（无超时）。
- Discord 线程绑定流程依赖 session.threadBindings.* 和 channels.discord.threadBindings.*。
- 回复格式包含 Status、Result 和紧凑统计。
- Result 是助手完成文本；如果为空，使用最新的 toolResult 作为备选。
手动完成模式的 spawn 先直接发送，失败后走队列备选，并在瞬态故障时重试（status: "ok" 表示运行完成，不代表通告已送达）。
sessions_spawn 支持内联文件附件（仅 subagent 运行时；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"。
ACP streamTo: "parent" 响应可能包含 streamLogPath（会话级 *.acp-stream.jsonl），用于查看进度历史。
sessions_send 执行回复式 ping-pong（回复 REPLY_SKIP 停止；最大轮次通过 session.agentToAgent.maxPingPongTurns 控制，0–5）。
ping-pong 之后，目标 Agent 运行一个通告步骤；回复 ANNOUNCE_SKIP 可以跳过通告。
沙箱限制：当前会话沙箱化且 agents.defaults.sandbox.sessionToolsVisibility: "spawned" 时，OpenClaw 将 tools.sessions.visibility 限制为 tree。

`agents_list`

列出当前会话可通过 sessions_spawn 定位的 Agent id。

注意事项：

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

通用参数

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

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

注意：设置 gatewayUrl 时，必须显式包含 gatewayToken。工具不会继承配置或环境凭证来处理覆盖，缺少显式凭证会报错。

Browser 工具：

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

安全

避免直接使用 system.run；只在用户明确同意时使用 nodes → run。
使用摄像头/屏幕捕获时尊重用户同意。
在调用媒体命令前，使用 status/describe 确认权限。

工具如何呈现给 Agent

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

系统提示词文本：人类可读的列表 + 指引。
工具 Schema：发送给模型 API 的结构化函数定义。

也就是说，Agent 既能看到”有哪些工具”，也能看到”怎么调用”。如果一个工具既不在系统提示词里、也不在 schema 中，模型就无法调用它。

工具（OpenClaw）

禁用工具

工具配置文件（基础白名单）

按提供商设置工具策略

工具组（快捷方式）

插件 + 工具

工具清单

apply_patch

exec

process

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

web_search

web_fetch

browser

canvas

nodes

image

pdf

message

cron

gateway

sessions_list / sessions_history / sessions_send / sessions_spawn / session_status

agents_list

通用参数

推荐的 Agent 流程

安全

工具如何呈现给 Agent

`apply_patch`

`exec`

`process`

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

`web_search`

`web_fetch`

`browser`

`canvas`

`nodes`

`image`

`pdf`

`message`

`cron`

`gateway`

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

`agents_list`