掌控 OpenClaw 工具：讓 AI Agent 只做該做的事

每次在開發 AI Agent 時，最頭痛的就是權限控制。給太少工具，Agent 什麼都做不了；給太多工具，又擔心它亂動你的檔案或亂發訊息。手動一個個設定 API 權限真的很累，如果沒有一套直覺的管理方式，你的設定檔很快就會變成一場災難。

OpenClaw 現在將工具（Tools）視為一等公民，取代了舊有的 openclaw-* skills。這些工具具備強型別，不需要透過 shell 執行，Agent 可以直接調用。這篇文章會教你如何優雅地控管這些能力。

需要準備的東西

• openclaw.json 設定檔
• OpenClaw 內建工具（如 browser, canvas, nodes, cron）

快速開始

要管理工具權限，最快的方法是使用 tools.profile。這能幫你快速套用一組預設的權限名單，而不需要手動列出每個工具名稱。

1. 選擇適合的 Profile

OpenClaw 提供了幾種預設組合：

• 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: 完全不限制（預設值）。

2. 全域設定與黑名單

如果你想讓 Agent 擁有寫程式的能力，但為了安全想禁用系統執行權限，可以在 openclaw.json 這樣寫：

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

3. 為特定 Agent 定製權限

你也可以在全域設定之外，為個別 Agent 覆寫權限。例如你的全域設定是 coding，但你想建立一個專門跑 Slack 的客服 Agent：

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

疑難排解

工具清單失效並出現警告？

如果你在 tools.allow 填寫的名稱都是未知或未載入的 Plugin，OpenClaw 會噴出警告。為了確保 Agent 不會完全癱瘓，它會忽略這份 allowlist 並讓核心工具保持可用。

為什麼設定了 allow 還是不能用？

請檢查你的 tools.deny。在 OpenClaw 的邏輯中，黑名單（deny）的優先級永遠高於白名單（allow）。另外，名稱比對是不分大小寫的。

如何一次禁用所有工具？

你可以使用萬用字元 *。例如 tools: { deny: ["*"] } 會阻斷所有工具傳送給模型。

---

如果你在設定過程遇到問題，可以直接詢問 AI Setup Assistant 獲取即時幫助。

下一步

• Agent 基礎設定指南
• 自定義 Plugin 開發

寫過 AI 應用的你一定知道，不同模型對 Tool 的處理能力差很大。有的模型用起來很順，有的卻會在特定 API 下胡言亂語，甚至在處理複雜參數時直接掛掉。如果你想讓全域配置保持簡潔，但又得針對某個模型「特別關照」來避免出錯，這就是 tools.byProvider 出場的時候了。

這種情況通常發生在你更換了底層模型，或者想在同一個 Agent 裡混合使用不同等級的 Provider。你不需要為了遷就某個比較弱的模型而閹割掉所有人的權限，只需要針對它進行精確的範圍限制即可。

需要準備的東西

• 基本的 tools 配置權限
• 專案中已定義的 agents.list（如果你需要針對特定 Agent 設定）
• 清楚你的 Provider 標籤（如 google-antigravity）或完整的 provider/model 路徑（如 openai/gpt-5.2）

快速開始

使用 tools.byProvider 可以讓你進一步限制特定 Provider 的工具權限，而不需要改動你的全域預設值。如果你有特定 Agent 需要特殊處理，也可以在 agents.list[].tools.byProvider 進行覆寫。

這項設定的生效順序是在基礎 Tool Profile 之後，但在 Allow/Deny 清單 之前。這意味著它只能用來「縮小」工具範圍，不能用來開啟全域設定中原本就禁止的工具。

範例 1：保持全域 Coding 設定，但對特定 Provider 使用 Minimal Profile

如果你發現某個模型處理複雜工具的能力較弱，可以將它降級到 minimal：

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

範例 2：針對不穩定的 Endpoint 縮減 Allowlist

當某個模型在特定的工具群組（如 runtime）表現不佳時，你可以精確地把它拿掉：

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

範例 3：針對特定 Agent 裡的 Provider 進行覆寫

你也可以在 Agent 層級做更細緻的控制：

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

疑難排解

• 設定了 byProvider 但工具沒增加？ 請記住 byProvider 只能用來進一步「縮小」範圍。如果該工具在全域的基礎 Profile 或 Allow 清單中本來就不存在，你無法透過 byProvider 把它加回來。
• 模型標籤不生效？ 請檢查你的 Key 格式。它支援 provider（例如 google-antigravity）或 provider/model（例如 openai/gpt-5.2）兩種寫法，確保拼字與你使用的 Gateway 設定一致。

想要更快速地完成配置嗎？試試我們的 AI Setup Assistant。

下一步

• Agent Configuration 完整指南
• 如何定義 Tool Profiles

每次在設定 Agent 或 Sandbox 的權限時，是不是覺得一個個列出工具名稱很麻煩？如果工具太多，設定檔會變得又長又難維護，漏掉一個可能就會讓整個 Workflow 報錯。

這就是為什麼我們需要 Tool groups。透過這些簡寫（Shorthands），你可以一次授權一整組相關的工具，讓設定變得乾淨俐落。

需要準備的東西

在開始之前，請確保你已經準備好：

• 基本的工具設定知識（global, agent, 或 sandbox 政策）
• 了解 tools.allow 與 tools.deny 的運作方式

快速開始

你可以直接在 tools.allow 或 tools.deny 中使用 group:* 格式的條目。這些簡寫會自動展開成多個對應的工具。

可用的 Tool 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）

設定範例

如果你只想讓 Agent 使用檔案系統工具和瀏覽器，可以這樣寫：

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

Plugins 與擴充工具

除了核心工具集，Plugins 還可以註冊額外的工具和 CLI 指令。你可以參考 Plugins 文件來了解如何安裝與設定，或是查看 Skills 了解工具使用引導是如何注入到 Prompt 中的。

有些 Plugin 會隨附自己的 Skills（例如 voice-call plugin）。

選配的 Plugin 工具

• Lobster: 這是一個帶有類型定義的 Workflow runtime，支援可恢復的審批流程（需要在 Gateway 主機上安裝 Lobster CLI）。
• LLM Task: 專門用於結構化 Workflow 輸出的 JSON-only LLM 步驟（支援選配的 schema 驗證）。

想要針對你的開發場景進行自動化配置嗎？試試我們的 AI Setup Assistant。

下一步

• Plugins 設定指南
• 了解 Skills 如何運作
• Lobster 工作流 runtime
• LLM Task 結構化輸出

你是不是也遇過這種狀況：寫了一個超聰明的 AI Agent，結果它除了陪你聊天，什麼事都做不了？這種感覺就像請了一個精通八國語言的秘書，但他卻連幫你開個網頁或改個檔案都辦不到。我們都希望 Agent 能像真正的夥伴一樣，直接處理那些瑣碎的開發任務，而不是只會給你建議。

這篇文章會帶你掃一遍 OpenClaw 的工具庫（Tool inventory），看看如何讓你的 Agent 獲得手腳，直接在你的工作空間裡大顯身手。

需要準備的東西

在開始之前，請確保你已經準備好以下東西（具體視你想用的工具而定）：

• 已安裝並設定好的 openclaw 環境
• Brave Search API Key（如果你要用 web_search）
• 啟用的 Gateway 或 Node 環境（用於遠端執行或 Canvas 操作）
• Playwright（如果你需要進階的瀏覽器 snapshot 功能）

快速開始

想讓你的 Agent 獲得執行指令的能力？最快的方法是從 exec 開始：

1. 在設定檔中確認 tools.exec 相關權限已開啟。
2. 如果是 OpenAI 模型，可以嘗試開啟實驗性的 apply_patch 功能：tools.exec.applyPatch.enabled: true。
3. 直接在對話中叫 Agent 幫你執行 ls 或 git status 看看效果。

---

工具清單總覽

apply_patch

這是一個用來在多個檔案中套用結構化補丁（Patch）的工具，非常適合處理跨檔案的多處修改。 注意： 這是實驗性功能，目前僅支援 OpenAI 模型，需透過 tools.exec.applyPatch.enabled 開啟。

exec

在工作空間中執行 Shell 指令。這是最核心的工具之一。

核心參數：

• command (必填)
• yieldMs (逾時後自動轉入背景執行，預設 10000)
• background (立即在背景執行)
• timeout (秒數；超過會殺掉行程，預設 1800)
• elevated (布林值；若開啟此模式，會在 Host 端執行)
• host (sandbox | gateway | node)
• security (deny | allowlist | full)
• ask (off | on-miss | always)
• node (當 host=node 時指定 Node ID)
• 需要真實的 TTY？請設定 pty: true。

開發筆記：

• 轉入背景執行時，會回傳 status: "running" 以及一個 sessionId。
• 你可以使用 process 工具來輪詢、查看日誌、寫入資料或殺掉背景工作。
• 如果不允許使用 process，則 exec 會同步執行並忽略 yieldMs。
• elevated 是 host=gateway + security=full 的別名，且必須在 tools.elevated 與 agents.list[].tools.elevated 同時允許時才有效。

process

用來管理背景執行的 exec 工作。

核心動作：

• list, poll, log, write, kill, clear, remove

開發筆記：

• poll 會回傳新的輸出，並在完成時回傳退出狀態。
• log 支援基於行的 offset 與 limit（省略 offset 則抓取最後 N 行）。

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 開啟。

web_fetch

從 URL 抓取並提取可讀內容（HTML 轉 Markdown 或純文字）。

核心參數：

• url (必填)
• extractMode (markdown | text)
• maxChars (截斷過長的頁面)

開發筆記：

• 需透過 tools.web.fetch.enabled 開啟。
• 回應內容會快取（預設 15 分鐘）。
• 對於大量使用 JS 的網站，建議改用 browser 工具。

browser

控制 OpenClaw 管理的專用瀏覽器。

核心動作：

• status, start, stop, tabs, open, focus, close
• snapshot (取得頁面結構，支援 aria 或 ai)
• screenshot (回傳圖片塊與 MEDIA:<path>)
• act (UI 操作：點擊、輸入、按壓、拖曳、填寫、等待、評估等)
• navigate, console, pdf, upload, dialog

設定檔（Profile）管理：

• profiles — 列出所有設定檔及其狀態。
• create-profile — 建立新設定檔並自動分配 Port。
• delete-profile — 停止瀏覽器並刪除資料。

開發筆記：

• 預設開啟 browser.enabled=true。
• snapshot 在安裝 Playwright 後預設使用 ai 模式。
• act 需要來自 snapshot 的 ref（例如數字 12 或 e12）。
• 儘量避免在 act 後使用 wait，除非沒有明確的 UI 狀態可以判斷。

canvas

操作 Node 的 Canvas（呈現、評估、快照、A2UI）。

核心動作：

• present, hide, navigate, eval
• snapshot (回傳圖片與路徑)
• a2ui_push, a2ui_reset

開發筆記：

• A2UI 目前僅支援 v0.8，不支援 createSurface。
• 測試指令：openclaw nodes canvas a2ui push --node <id> --text "Hello from A2UI"。

nodes

發現並控制配對的 Node；傳送通知；擷取鏡頭或螢幕。

核心動作：

• status, describe
• pending, approve, reject (配對管理)
• notify (系統通知)
• run (執行指令)
• camera_snap, location_get

範例 (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 (選填，覆蓋預設模型)

message

跨平台傳送訊息，支援 Discord, Google Chat, Slack, Telegram, WhatsApp, Signal, iMessage, MS Teams。

核心動作：

• send (文字、媒體、Adaptive Cards)
• poll (投票功能，支援 WhatsApp/Discord/MS Teams)
• react, read, edit, delete
• thread-create, channel-list, member-info

cron

管理 Gateway 的定時任務（Cron Jobs）。

核心動作：

• status, list, add, update, remove, wake

gateway

重啟或更新執行中的 Gateway 行程。

核心動作：

• restart, config.get, config.apply, update.run

sessions 工具組

管理會話、查看歷史紀錄或在不同會話間傳遞訊息。

• sessions_list: 列出會話。
• sessions_history: 查看對話紀錄。
• sessions_send: 傳送訊息給另一個會話。
• sessions_spawn: 產生一個子 Agent 任務。
• session_status: 查看或修改目前會話的模型設定。

---

疑難排解

• exec 指令沒反應？ 檢查 yieldMs 設定，如果是長時間執行的工作，它可能已經轉入背景。請使用 process list 確認。
• web_search 報錯？ 請確認你的 Brave API Key 是否正確設定，或者使用 openclaw configure 重新檢查。
• 瀏覽器無法啟動？ 確保 browser.enabled 為 true，且 Port 範圍 (18800-18899) 沒有被占用。
• apply_patch 失敗？ 確認你使用的是 OpenAI 模型，且已手動開啟 tools.exec.applyPatch.enabled。

如果你在設定過程中遇到任何困難，隨時可以詢問 AI Setup Assistant 獲取即時協助。

下一步

• Exec 權限審核與白名單
• 網頁工具進階設定
• 瀏覽器自動化指南
• 跨 Agent 協作 (Agent-to-Agent)

每次在整合不同工具到 Agent 時，最煩人的就是參數對不齊，或是漏掉一個 Token 導致連線失敗。如果你也曾經卡在「明明環境變數設了，但工具就是抓不到」這種坑裡，這篇整理能幫你快速搞清楚這些工具背後的運作邏輯。

需要準備的東西

在開始配置之前，請確保你已經準備好以下資訊：

• Gateway 連線資訊（URL 與 Token）
• 瀏覽器工具的 Profile 名稱（選填）
• 目標 Node 的 ID 或名稱（選填）

快速開始

要在你的專案中使用這些工具，最快的路徑是搞定基礎參數配置。

1. 配置 Gateway 工具

對於 canvas、nodes 或 cron 這些由 Gateway 驅動的工具，你需要設定：

• gatewayUrl: 預設為 ws://127.0.0.1:18789
• gatewayToken: 如果啟用了驗證，請務必填寫
• timeoutMs: 設定逾時時間

注意： 當你手動設定 gatewayUrl 時，必須同時顯式 (explicitly) 包含 gatewayToken。這些工具不會自動繼承環境變數或全域配置，漏掉憑證會直接導致報錯。

2. 設定 Browser 工具

如果你在使用瀏覽器工具，參數如下：

• profile: 選填，預設為 browser.defaultProfile
• target: 可選擇 sandbox、host 或 node
• node: 選填，用來指定特定的 Node ID 或名稱

推薦的 Agent 工作流

為了讓 Agent 運作更順暢，建議參考以下幾種標準流程：

瀏覽器自動化 (Browser automation)

1. 使用 browser → status / start 啟動
2. 透過 snapshot (ai 或 aria) 獲取頁面狀態
3. 執行 act (click/type/press) 進行操作
4. 如果需要視覺確認，最後執行 screenshot

Canvas 渲染 (Canvas render)

1. 使用 canvas → present
2. 視需求執行 a2ui_push
3. 透過 snapshot 獲取結果

節點目標定位 (Node targeting)

1. 使用 nodes → status 檢查狀態
2. 對選定的節點執行 describe
3. 執行 notify / run / camera_snap / screen_record

安全性建議 (Safety)

在開發過程中，安全性是不可忽視的一環：

• 避免直接調用 system.run；請使用 nodes → run，且必須在獲得用戶明確同意後才執行。
• 尊重用戶隱私，在擷取相機或螢幕畫面之前，務必取得用戶同意。
• 在調用媒體相關指令前，先使用 status/describe 確認權限。

工具是如何呈現給 Agent 的？

Agent 會透過兩個平行管道看到你的工具：

1. System prompt text: 一份人類可讀的列表與操作指南。
2. Tool schema: 發送給模型 API 的結構化 Function 定義。

這意味著 Agent 同時知道「有哪些工具可用」以及「如何調用它們」。如果一個工具沒有出現在 System prompt 或 Schema 中，模型就無法使用它。

疑難排解

問題：設定了 gatewayUrl 但工具回報驗證錯誤？ 解決方案： 請檢查你是否遺漏了 gatewayToken。在 Gateway 工具中，Credential 不會自動繼承，當你覆寫 URL 時，必須顯式傳入 Token。

---

還有疑問嗎？試試我們的 AI Setup Assistant 獲取即時協助。

下一步

• 瀏覽器工具進階配置
• 節點權限管理指南