工具（OpenClaw）

OpenClaw 提供 一級代理程式工具，涵蓋 browser、canvas、nodes 與 cron。這些工具取代舊版的 openclaw-* Skills：工具具備型別定義、不需要 shelling，且代理程式應直接依賴它們。 These replace the old openclaw-* skills: the tools are typed, no shelling, and the agent should rely on them directly. These replace the old openclaw-* skills: the tools are typed, no shelling, and the agent should rely on them directly.

停用工具

你可以在 openclaw.json 中，透過 tools.allow / tools.deny 全域允許或拒絕工具（拒絕優先）。這會防止不被允許的工具送往模型提供者。 This prevents disallowed tools from being sent to model providers. This prevents disallowed tools from being sent to model providers.

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

注意事項：

Matching is case-insensitive.
支援 * 萬用字元（"*" 代表所有工具）。
若 tools.allow 僅參照未知或未載入的外掛工具名稱，OpenClaw 會記錄警告並忽略允許清單，以確保核心工具仍可使用。

工具設定檔（基礎允許清單）

使用 tools.byProvider 可針對特定提供者（或單一 provider/model）進一步限制 工具，而不影響你的全域預設值。每個代理程式可覆寫：agents.list[].tools.byProvider。 36. 每代理覆寫：agents.list[].tools.byProvider。 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"],
  },
}

範例（程式開發設定檔，但在所有地方拒絕 exec/process）：

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

Example (global coding profile, messaging-only support agent):

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

提供者專屬的工具政策

使用 tools.byProvider 可針對特定提供者（或單一 provider/model）進一步限制 工具，而不影響你的全域預設值。每個代理程式可覆寫：agents.list[].tools.byProvider。 tools.profile 會在 tools.allow/tools.deny 之前設定 基礎工具允許清單。每個代理程式可覆寫：agents.list[].tools.profile。 Per-agent override: agents.list[].tools.profile. 此設定會在基礎工具設定檔之後、允許／拒絕清單之前套用，因此只能縮小工具集合。此設定會在基礎工具設定檔之後、允許／拒絕清單之前套用，因此只能縮小工具集合。 Provider keys accept either provider (e.g. google-antigravity) or provider/model (e.g. 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 中使用。 Use these in tools.allow / tools.deny. Use these in 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"],
  },
}

外掛 + 工具

Plugins can register additional tools (and CLI commands) beyond the core set. See Plugins for install + config, and Skills for how tool usage guidance is injected into prompts. Some plugins ship their own skills alongside tools (for example, the voice-call plugin). 可選外掛工具：

Lobster: typed workflow runtime with resumable approvals (requires the Lobster CLI on the gateway host).
LLM Task：僅 JSON 的 LLM 步驟，用於結構化工作流程輸出（可選的結構驗證）。

工具清單

`apply_patch`

Apply structured patches across one or more files. Use for multi-hunk edits. 在一或多個檔案上套用結構化修補。適用於多段（multi-hunk）編輯。實驗性功能：透過 tools.exec.applyPatch.enabled 啟用（僅 OpenAI 模型）。 tools.exec.applyPatch.workspaceOnly 預設為 true（僅限於 workspace 內）。僅在你有意讓 apply_patch 在 workspace 目錄之外進行寫入/刪除時，才將其設為 false。

`exec`

在工作區中執行 shell 指令。核心參數：

command（必填）
yieldMs（逾時後自動背景執行，預設 10000）
background（立即背景執行）
timeout（秒；超過即終止程序，預設 1800）
elevated（bool；若啟用/允許提升模式，則在主機上執行；僅在代理程式處於沙箱時才會改變行為）
host（sandbox | gateway | node）
security（deny | allowlist | full）
ask（off | on-miss | always）
node（host=node 的節點 id/名稱）
需要真正的 TTY？設定 pty: true。 Set pty: true. Set pty: true.

注意事項：

背景執行時會回傳 status: "running" 與 sessionId。
Use process to poll/log/write/kill/clear background sessions.
若 process 被拒絕，exec 會同步執行並忽略 yieldMs/background。
elevated 受 tools.elevated 與任何 agents.list[].tools.elevated 覆寫所控管（兩者皆須允許），且是 host=gateway + security=full 的別名。
elevated only changes behavior when the agent is sandboxed (otherwise it’s a no-op).
host=node 可指向 macOS 配套應用程式或無介面的節點主機（openclaw node run）。
閘道器/節點核准與允許清單：Exec approvals。

`process`

管理背景 exec 工作階段。核心動作：

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

注意事項：

poll returns new output and exit status when complete.
log 支援以行為基礎的 offset/limit（省略 offset 以擷取最後 N 行）。
process 以代理程式為作用域；其他代理程式的工作階段不可見。

`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 啟用。
Responses are cached (default 15 min).
設定方式請見 Web tools。

`web_fetch`

從 URL 擷取並抽取可讀內容（HTML → markdown/text）。核心參數：

url（必填）
extractMode（markdown | text）
maxChars（截斷過長頁面）

注意事項：

透過 tools.web.fetch.enabled 啟用。
maxChars 會受 tools.web.fetch.maxCharsCap 限制（預設 50000）。
Responses are cached (default 15 min).
對於大量 JS 的網站，請優先使用 browser 工具。
設定方式請見 Web tools。
可選的反機器人備援請見 Firecrawl。

`browser`

控制由 OpenClaw 管理的專用 browser。核心動作：

status、start、stop、tabs、open、focus、close
snapshot（aria/ai）
screenshot（回傳 image 區塊 + MEDIA:<path>）
act（UI 動作：click/type/press/hover/drag/select/fill/resize/wait/evaluate）
navigate、console、pdf、upload、dialog

設定檔管理：

profiles — 列出所有 browser 設定檔與狀態
create-profile — 建立新設定檔並自動配置連接埠（或 cdpUrl）
delete-profile — 停止 browser、刪除使用者資料、從設定中移除（僅本機）
reset-profile — 終止設定檔連接埠上的孤兒程序（僅本機）

常用參數：

profile（選用；預設為 browser.defaultProfile）
target（sandbox | host | node）
node（選用；指定特定節點 id/名稱）注意事項：
需要 browser.enabled=true（預設為 true；設定 false 以停用）。
所有動作皆接受選用的 profile 參數以支援多實例。
省略 profile 時，會使用 browser.defaultProfile（預設為 “chrome”）。
Profile names: lowercase alphanumeric + hyphens only (max 64 chars).
Port range: 18800-18899 (~100 profiles max).
Remote profiles are attach-only (no start/stop/reset).
若連線了具備 browser 能力的節點，工具可能會自動路由至該節點（除非你固定 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（present、eval、snapshot、A2UI）。核心動作：

present、hide、navigate、eval
snapshot（回傳 image 區塊 + 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

注意事項：

Camera/screen commands require the node app to be foregrounded.
影像會回傳 image 區塊 + 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（主要或備援），或可由預設模型 + 已設定的驗證推斷出隱含影像模型時可用（盡力配對）。
Uses the image model directly (independent of the main chat model).

`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 投票為直連。
When a message tool call is bound to an active chat session, sends are constrained to that session’s target to avoid cross-context leaks.

`cron`

管理 Gateway 閘道器的 cron 工作與喚醒。核心動作：

status、list
add、update、remove、run、runs
wake（佇列系統事件 + 選用立即心跳）

注意事項：

add 需要完整的 cron 工作物件（與 cron.add RPC 相同結構）。
update 使用 { jobId, patch }（為相容性接受 id）。

`gateway`

Restart or apply updates to the running Gateway process (in-place). 核心動作：

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`

List sessions, inspect transcript history, or send to another session. 核心參數：

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 是標準的直接聊天鍵；全域/未知會被隱藏。
messageLimit > 0 會擷取每個工作階段的最後 N 則訊息（會過濾工具訊息）。
當 timeoutSeconds > 0 時，sessions_send 會等待最終完成。
傳遞/公告會在完成後進行，且為盡力而為；status: "ok" 確認的是代理程式執行完成，而非公告已送達。
sessions_spawn 會啟動子代理程式執行，並將公告回覆張貼回請求者聊天。
sessions_spawn 為非阻塞，會立即回傳 status: "accepted"。
sessions_send 會執行回覆往返（回覆 REPLY_SKIP 以停止；最大回合由 session.agentToAgent.maxPingPongTurns 設定，0–5）。
往返後，目標代理程式會執行 公告步驟；回覆 ANNOUNCE_SKIP 以抑制公告。

`agents_list`

列出目前工作階段可用 sessions_spawn 指定的代理程式 id。注意事項：

結果受每個代理程式的允許清單限制（agents.list[].subagents.allowAgents）。
當設定 ["*"] 時，工具會包含所有已設定的代理程式並標記 allowAny: true。

參數（共用）

由 Gateway 閘道器支援的工具（canvas、nodes、cron）：

gatewayUrl（預設 ws://127.0.0.1:18789）
gatewayToken（若啟用驗證）
timeoutMs

Note: when gatewayUrl is set, include gatewayToken explicitly. Tools do not inherit config or environment credentials for overrides, and missing explicit credentials is an error. Browser 工具：

profile（選用；預設為 browser.defaultProfile）
target（sandbox | host | node）
node（選用；固定特定節點 id/名稱）

建議的代理程式流程

Browser 自動化：

browser → status / start
snapshot（ai 或 aria）
act（click/type/press）
如需視覺確認，使用 screenshot

Canvas 繪製：

canvas → present
a2ui_push（選用）
snapshot

節點目標設定：

nodes → status
在選定的節點上執行 describe
notify / run / camera_snap / screen_record

安全性

避免直接使用 system.run；僅在明確取得使用者同意時，使用 nodes → run。
尊重使用者對相機/螢幕擷取的同意。
在呼叫媒體指令前，使用 status/describe 以確保權限。

工具如何呈現給代理程式

工具會透過兩個平行管道揭露：

系統提示文字：人類可讀的清單 + 指引。
Tool schema: the structured function definitions sent to the model API.

That means the agent sees both “what tools exist” and “how to call them.” 這表示代理同時能看到「有哪些工具可用」以及「如何呼叫它們」。如果某個工具 doesn’t appear in the system prompt or the schema, the model cannot call it.

概覽

內建工具

瀏覽器

智慧體協作

技能

擴充功能

自動化

媒體與裝置

工具

工具（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`

參數（共用）

建議的代理程式流程

安全性

工具如何呈現給代理程式

概覽

內建工具

瀏覽器

智慧體協作

技能

擴充功能

自動化

媒體與裝置

​工具（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

​參數（共用）

​建議的代理程式流程

​安全性

​工具如何呈現給代理程式

工具（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`

參數（共用）

建議的代理程式流程

安全性

工具如何呈現給代理程式