工具（OpenClaw）

OpenClaw 提供一級代理工具，涵蓋瀏覽器、畫布、節點與排程等功能。這些工具取代了舊版 openclaw-* 技能：具備型別、不需要額外 shell 呼叫，代理可直接使用。

停用工具

你可以透過 openclaw.json 的 tools.allow / tools.deny 全域控制工具的啟停（deny 優先）。被禁止的工具不會傳送給模型供應商。

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

注意事項：

比對不分大小寫。
支援 * 萬用字元（"*" 表示所有工具）。
如果 tools.allow 只包含不認識或未載入的外掛工具名稱，OpenClaw 會記錄警告並忽略允許清單，以確保核心工具可用。

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

tools.profile 設定在 tools.allow/tools.deny 之前套用的基礎工具允許清單。每個代理可透過 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 設定檔，messaging 專屬的支援代理）：

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

供應商專屬工具策略

使用 tools.byProvider 可以針對特定供應商（或單一 provider/model）進一步限制工具，而不影響你的全域預設值。每個代理可透過 agents.list[].tools.byProvider 覆寫。

此策略在基礎工具設定檔之後、allow/deny 清單之前套用，因此只能收窄工具集合。供應商鍵值接受 provider（例如 google-antigravity）或 provider/model（例如 openai/gpt-5.2）格式。

範例（維持全域 coding 設定檔，但 Google Antigravity 用 minimal 工具）：

{
  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 中使用。

可用群組：

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 工具（不含供應商外掛）

範例（只允許檔案工具和瀏覽器）：

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

外掛與工具

外掛可以在核心工具集之外註冊額外工具（以及 CLI 指令）。請參閱外掛了解安裝與設定，以及技能了解工具使用指引如何注入提示詞中。部分外掛會隨工具一起提供專屬技能（例如語音通話外掛）。

選用外掛工具：

Lobster：具可恢復審批機制的型別化工作流程執行環境（需要在閘道主機上安裝 Lobster CLI）。
LLM Task：用於結構化工作流程輸出的 JSON 專用 LLM 步驟（可選 schema 驗證）。
Diffs：唯讀差異檢視器，支援文字或 unified patch 的前後對比，以及 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（布林值；在啟用/允許提升模式時於主機上執行；僅在代理處於沙箱時才會改變行為）
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 僅在代理處於沙箱時才會改變行為（否則無效）。
host=node 可以指向 macOS 伴隨應用程式或無頭節點主機（openclaw node run）。
閘道/節點的審批與允許清單：Exec 審批。

`process`

管理背景執行工作階段。

核心操作：

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

注意事項：

poll 回傳新輸出，完成時包含退出狀態。
log 支援基於行的 offset/limit（省略 offset 可取得最後 N 行）。
process 限定於每個代理的範圍內；其他代理的工作階段不可見。

`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 交替無進展的模式。
每個代理可覆寫：agents.list[].tools.loopDetection。

`web_search`

使用 Perplexity、Brave、Gemini、Grok 或 Kimi 搜尋網路。

核心參數：

query（必填）
count（1–10；預設來自 tools.web.search.maxResults）

注意事項：

需要所選供應商的 API 金鑰（建議使用 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 的網站，建議使用瀏覽器工具。
詳見 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 參考值）或 element（CSS 選擇器）來直接設定 <input type="file">。

`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_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 透過閘道路由 WhatsApp；其他頻道直接傳送。
poll 在 WhatsApp 和 MS Teams 使用閘道；Discord 投票直接執行。
當訊息工具呼叫綁定到活躍的聊天工作階段時，傳送會限制在該工作階段的目標，以避免跨上下文洩漏。

`cron`

管理閘道排程任務與喚醒。

核心操作：

status、list
add、update、remove、run、runs
wake（排入系統事件 + 選填立即心跳）

注意事項：

add 預期完整的 cron 任務物件（與 cron.add RPC 相同的 schema）。
update 使用 { jobId, patch }（也接受 id 以保持相容性）。

`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。
路徑在處理 plugins.entries.<id> 時可包含斜線分隔的外掛 id，例如 plugins.entries.pack/one.config。
使用 delayMs（預設 2000）以避免中斷正在進行的回覆。
config.schema 仍可供內部控制 UI 流程使用，但不透過代理 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 是標準直接聊天鍵值；global/unknown 會被隱藏。
messageLimit > 0 取得每個工作階段最後 N 筆訊息（工具訊息會被過濾）。
工作階段目標由 tools.sessions.visibility 控制（預設 tree：當前工作階段 + 衍生的子代理工作階段）。如果你為多位使用者運行共用代理，建議設定 tools.sessions.visibility: "self" 以防止跨工作階段瀏覽。
sessions_send 在 timeoutSeconds > 0 時會等待最終完成。
傳遞/公告在完成後執行，且為盡力而為；status: "ok" 確認代理執行已完成，不代表公告已送達。
sessions_spawn 支援 runtime: "subagent" | "acp"（subagent 為預設）。ACP 執行環境行為請參閱 ACP 代理。
使用 ACP 執行環境時，streamTo: "parent" 會將初始執行的進度摘要以系統事件形式路由回請求者工作階段，而非直接傳送給子工作階段。
sessions_spawn 啟動子代理執行並將公告回覆發送回請求者聊天。
- 支援一次性模式（mode: "run"）和持久式執行緒綁定模式（mode: "session" 搭配 thread: true）。
- 如果 thread: true 且省略 mode，模式預設為 session。
- mode: "session" 需要 thread: true。
- 如果省略 runTimeoutSeconds，OpenClaw 會使用 agents.defaults.subagents.runTimeoutSeconds（若有設定）；否則超時預設為 0（無超時）。
- Discord 執行緒綁定流程依賴 session.threadBindings.* 和 channels.discord.threadBindings.*。
- 回覆格式包含 Status、Result 和精簡的統計資訊。
- Result 是助理完成的文字；若缺少，則使用最新的 toolResult 作為後備。
手動完成模式的衍生會先嘗試直接傳送，如失敗則透過佇列路由後備並在暫時性失敗時重試（status: "ok" 表示執行已完成，不代表公告已送達）。
sessions_spawn 支援內嵌檔案附件（僅限子代理執行環境；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 執行回覆往返互動（回覆 REPLY_SKIP 可停止；最大輪次由 session.agentToAgent.maxPingPongTurns 控制，範圍 0–5）。
往返互動後，目標代理會執行公告步驟；回覆 ANNOUNCE_SKIP 可抑制公告。
沙箱限制：當前工作階段處於沙箱中且 agents.defaults.sandbox.sessionToolsVisibility: "spawned" 時，OpenClaw 會將 tools.sessions.visibility 限制為 tree。

`agents_list`

列出當前工作階段可透過 sessions_spawn 指定的代理 id。

注意事項：

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

參數（通用）

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

gatewayUrl（預設 ws://127.0.0.1:18789）
gatewayToken（啟用認證時需要）
timeoutMs

注意：設定 gatewayUrl 時，請明確包含 gatewayToken。工具不會為覆寫繼承設定或環境認證，缺少明確認證會導致錯誤。

瀏覽器工具：

profile（選填；預設為 browser.defaultProfile）
target（sandbox | host | node）
node（選填；固定特定節點 id/名稱）
疑難排解指南：
- Linux 啟動/CDP 問題：瀏覽器疑難排解（Linux）
- WSL2 閘道 + Windows 遠端 Chrome CDP：WSL2 + Windows + 遠端 Chrome CDP 疑難排解

建議的代理流程

瀏覽器自動化：

browser → status / start
snapshot（ai 或 aria）
act（click/type/press）
screenshot 若需要視覺確認

畫布渲染：

canvas → present
a2ui_push（選填）
snapshot

節點指定：

nodes → status
對選定節點執行 describe
notify / run / camera_snap / screen_record

安全性

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

工具如何呈現給代理

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

系統提示詞文字：人類可讀的清單與使用指引。
工具 schema：傳送給模型 API 的結構化函式定義。

這表示代理會同時看到「有哪些工具」和「如何呼叫它們」。如果某工具不在系統提示詞或 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

參數（通用）

建議的代理流程

安全性

工具如何呈現給代理

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