工具與 Plugin

代理在產生文字以外所做的一切，都是透過工具完成。 工具是代理讀取檔案、執行命令、瀏覽網頁、傳送訊息，以及與裝置互動的方式。

# 工具、Skills 和 Plugin

OpenClaw 有三個彼此協作的層次：

# 內建工具

這些工具隨 OpenClaw 提供，無須安裝任何 Plugin 即可使用：

工具	功能	頁面
exec / process	執行 shell 命令、管理背景處理程序	Exec, Exec 核准
code_execution	執行沙盒化遠端 Python 分析	程式碼執行
browser	控制 Chromium 瀏覽器（導覽、點擊、截圖）	瀏覽器
web_search / x_search / web_fetch	搜尋網頁、搜尋 X 貼文、擷取頁面內容	網頁, 網頁擷取
read / write / edit	工作區中的檔案 I/O
apply_patch	多 hunk 檔案修補	套用修補
message	跨所有頻道傳送訊息	代理傳送
canvas	驅動 Node Canvas（呈現、eval、快照）
nodes	探索並指定已配對的裝置
cron / gateway	管理排程工作；檢查、修補、重新啟動或更新 Gateway
image / image_generate	分析或產生影像	影像產生
music_generate	產生音樂曲目	音樂產生
video_generate	產生影片	影片產生
tts	一次性文字轉語音轉換	TTS
sessions_* / subagents / agents_list	工作階段管理、狀態，以及子代理編排	子代理
session_status	輕量級 /status 風格回讀與工作階段模型覆寫	工作階段工具

對於影像工作，使用 image 進行分析，使用 image_generate 進行產生或編輯。如果你的目標是 openai/*、google/*、fal/* 或其他非預設影像提供者，請先設定該提供者的驗證/API 金鑰。

對於音樂工作，使用 music_generate。如果你的目標是 google/*、minimax/* 或其他非預設音樂提供者，請先設定該提供者的驗證/API 金鑰。

對於影片工作，使用 video_generate。如果你的目標是 qwen/* 或其他非預設影片提供者，請先設定該提供者的驗證/API 金鑰。

對於工作流程驅動的音訊產生，當 ComfyUI 之類的 Plugin 註冊了 music_generate 時，請使用它。這不同於文字轉語音的 tts。

session_status 是工作階段群組中的輕量級狀態/回讀工具。 它會回答關於目前工作階段的 /status 風格問題，並且可以 選擇性設定每個工作階段的模型覆寫；model=default 會清除該 覆寫。和 /status 一樣，它可以從最新轉錄使用量項目回填稀疏的 token/cache 計數器，以及 作用中執行階段模型標籤。

gateway 是僅限擁有者使用的 Gateway 操作執行階段工具：

• config.schema.lookup 用於在編輯前查詢一個路徑範圍的設定子樹
• config.get 用於取得目前設定快照 + 雜湊
• config.patch 用於包含重新啟動的部分設定更新
• config.apply 僅用於完整設定替換
• update.run 用於明確自我更新 + 重新啟動

對於部分變更，優先使用 config.schema.lookup，再使用 config.patch。只有在你刻意替換整個設定時才使用 config.apply。 如需更廣泛的設定文件，請閱讀設定和 設定參考。 此工具也會拒絕變更 tools.exec.ask 或 tools.exec.security； 舊版 tools.bash.* 別名會正規化為相同受保護的 exec 路徑。

# Plugin 提供的工具

Plugin 可以註冊額外工具。一些範例：

• Diffs — 差異檢視器與算繪器
• LLM Task — 用於結構化輸出的純 JSON LLM 步驟
• Lobster — 具型別且支援可恢復核准的工作流程執行階段
• 音樂產生 — 由工作流程支援提供者共享的 music_generate 工具
• OpenProse — 以 markdown 為優先的工作流程編排
• Tokenjuice — 壓縮嘈雜的 exec 和 bash 工具結果

Plugin 工具仍然使用 api.registerTool(...) 編寫，並在 Plugin manifest 的 contracts.tools 清單中宣告。OpenClaw 會在探索期間擷取已驗證的 工具描述元，並依 Plugin 來源與合約快取，因此 後續工具規劃可以略過 Plugin 執行階段載入。工具執行時仍會載入 擁有該工具的 Plugin，並呼叫即時註冊的實作。

# 工具設定

# 允許與拒絕清單

透過設定中的 tools.allow / tools.deny 控制代理可以呼叫哪些工具。 拒絕一律優先於允許。

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

當明確允許清單解析後沒有任何可呼叫工具時，OpenClaw 會以封閉方式失敗。 例如，tools.allow: ["query_db"] 只有在已載入的 Plugin 實際 註冊 query_db 時才會生效。如果沒有內建工具、Plugin 或 bundled MCP 工具符合 允許清單，執行會在模型呼叫前停止，而不是繼續成為 可能幻覺出工具結果的純文字執行。

# 工具設定檔

tools.profile 會在套用 allow/deny 前設定基礎允許清單。 每個代理的覆寫：agents.list[].tools.profile。

設定檔	包含內容
full	所有核心與選用 Plugin 工具；用於更廣泛命令/控制存取的無限制基準
coding	group:fs, group:runtime, group:web, group:sessions, group:memory, cron, image, image_generate, music_generate, video_generate
messaging	group:messaging, sessions_list, sessions_history, sessions_send, session_status
minimal	僅 session_status

coding 包含輕量級網頁工具（web_search、web_fetch、x_search）， 但不包含完整的瀏覽器控制工具。瀏覽器自動化可以驅動真實 工作階段與已登入的設定檔，因此請使用 tools.alsoAllow: ["browser"] 或每個代理的 agents.list[].tools.alsoAllow: ["browser"] 明確加入它。

coding 和 messaging 設定檔也允許在 Plugin 鍵 bundle-mcp 下設定的 bundled MCP 工具。當你 希望設定檔保留其一般內建工具但隱藏所有已設定 MCP 工具時，請加入 tools.deny: ["bundle-mcp"]。 minimal 設定檔不包含 bundled MCP 工具。

範例（預設使用最廣泛的工具表面）：

{
  tools: {
    profile: "full",
  },
}

# 工具群組

在允許/拒絕清單中使用 group:* 簡寫：

群組	工具
group:runtime	exec, process, code_execution（bash 可作為 exec 的別名）
group:fs	read, write, edit, apply_patch
group:sessions	sessions_list, sessions_history, sessions_send, sessions_spawn, sessions_yield, subagents, session_status
group:memory	memory_search, memory_get
group:web	web_search, x_search, web_fetch
group:ui	browser, canvas
group:automation	heartbeat_respond, cron, gateway
group:messaging	message
group:nodes	nodes
group:agents	agents_list, update_plan
group:media	image, image_generate, music_generate, video_generate, tts
group:openclaw	所有內建 OpenClaw 工具（不包含 Plugin 工具）

sessions_history 會傳回有界限且經安全篩選的回憶檢視。它會從 assistant 文字中移除 思考標籤、<relevant-memories> 鷹架、純文字工具呼叫 XML 酬載（包括 <tool_call>...</tool_call>、 <function_call>...</function_call>、<tool_calls>...</tool_calls>、 <function_calls>...</function_calls>，以及遭截斷的工具呼叫區塊）、 降級的工具呼叫鷹架、外洩的 ASCII／全形模型控制權杖， 以及格式錯誤的 MiniMax 工具呼叫 XML，然後套用 修訂／截斷，以及可能的超大型列預留位置，而不是作為 原始逐字稿傾印。

# 特定供應商限制

使用 tools.byProvider 限制特定供應商的工具，而不 變更全域預設值：

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