外掛套件組合

OpenClaw 可以從三個外部生態系統安裝外掛：Codex、Claude 和 Cursor。這些稱為 套件組合，是由內容與中繼資料組成的套件， OpenClaw 會將其對應至 Skills、鉤子和 MCP 工具等原生功能。

為何需要套件組合

許多實用的外掛是以 Codex、Claude 或 Cursor 格式發布。OpenClaw 不要求 作者將它們重寫為原生 OpenClaw 外掛，而是偵測這些格式，並將其支援的內容 對應至原生功能集。你可以安裝 Claude 命令套件或 Codex Skill 套件組合， 並立即使用。

安裝套件組合

# 本機目錄openclaw plugins install ./my-bundle # 封存檔openclaw plugins install ./my-bundle.tgz # Claude 市集openclaw plugins marketplace list <source>openclaw plugins install <plugin> --marketplace <source>

openclaw plugins listopenclaw plugins inspect <id>

openclaw gateway restart

OpenClaw 會從套件組合對應哪些內容

目前並非所有套件組合功能都能在 OpenClaw 中執行。以下列出已可運作的功能， 以及已偵測但尚未接通的功能。

目前支援

Skill 內容

• 套件組合的 Skill 根目錄會載入為一般 OpenClaw Skill 根目錄。
• Claude commands/ 根目錄會視為額外的 Skill 根目錄。
• Cursor .cursor/commands/ 根目錄會視為額外的 Skill 根目錄。

Claude Markdown 命令檔和 Cursor 命令 Markdown 都能透過一般的 OpenClaw Skill 載入器運作。

鉤子套件

套件組合鉤子根目錄僅在使用一般 OpenClaw 鉤子套件配置時才會運作： HOOK.md 加上 handler.ts 或 handler.js。目前主要適用於 與 Codex 相容的情況。

內嵌 OpenClaw 的 MCP

• 已啟用的套件組合可以提供 MCP 伺服器設定。
• OpenClaw 會將套件組合的 MCP 設定合併至有效的內嵌 OpenClaw 設定中，作為 mcpServers。
• OpenClaw 會在內嵌 OpenClaw 代理程式回合中公開支援的套件組合 MCP 工具， 方法是啟動 stdio 伺服器或連線至 HTTP 伺服器。
• coding 和 messaging 工具設定檔預設包含套件組合 MCP 工具； 可使用 tools.deny: ["bundle-mcp"] 讓代理程式或閘道選擇不使用。
• 套用套件組合預設值後，專案本機的內嵌代理程式設定仍會生效，因此 必要時工作區設定可以覆寫套件組合的 MCP 項目。
• 套件組合 MCP 工具目錄會在註冊前以確定性方式排序，因此 上游 listTools() 的順序變更不會造成提示快取工具區塊反覆變動。

傳輸方式

MCP 伺服器可以使用 stdio 或 HTTP 傳輸。

Stdio 會啟動子處理程序：

{  "mcp": {    "servers": {      "my-server": {        "command": "node",        "args": ["server.js"],        "env": { "PORT": "3000" }      }    }  }}

HTTP 會連線至正在執行的 MCP 伺服器；除非要求 streamable-http，否則預設為 sse：

{  "mcp": {    "servers": {      "my-server": {        "url": "http://localhost:3100/mcp",        "transport": "streamable-http",        "headers": {          "Authorization": "Bearer ${MY_SECRET_TOKEN}"        },        "connectionTimeoutMs": 30000      }    }  }}

• transport 接受 "streamable-http" 或 "sse"；省略時預設為 sse。
• type: "http" 是命令列介面原生的下游格式；在 OpenClaw 設定中請使用 transport: "streamable-http"。openclaw mcp set 和 openclaw doctor --fix 會正規化常見別名。
• 僅允許 http: 和 https: URL 配置。
• headers 值支援 ${ENV_VAR} 插值。
• 同時包含 command 和 url 的伺服器項目會遭拒絕。
• 工具說明和記錄中的 URL 認證資訊（使用者資訊和查詢參數）會經過遮蔽。
• connectionTimeoutMs 會覆寫 stdio 和 HTTP 傳輸預設的 30 秒連線逾時。 請求逾時預設為 60 秒，並可使用 requestTimeoutMs 覆寫。

工具命名

OpenClaw 會使用 serverName__toolName 格式的供應商安全名稱來註冊套件組合 MCP 工具。 例如，索引鍵為 "vigil-harbor" 的伺服器若公開 memory_search 工具， 會註冊為 vigil-harbor__memory_search。

• A-Za-z0-9_- 以外的字元會替換為 -。
• 會以非字母開頭的片段會加上字母前綴，因此像 12306 這類數字 伺服器索引鍵會轉換為供應商安全的工具前綴。
• 伺服器前綴上限為 30 個字元。
• 完整工具名稱上限為 64 個字元。
• 空白伺服器名稱會退回使用 mcp。
• 清理後發生衝突的名稱會以數字後綴加以區別。
• 最終公開的工具會依安全名稱進行確定性排序，讓重複的 內嵌代理程式回合維持快取穩定。
• 設定檔篩選會將同一套件組合 MCP 伺服器的所有工具視為 由 bundle-mcp 外掛擁有，因此設定檔允許／拒絕清單可以參照 個別公開的工具名稱或 bundle-mcp 外掛索引鍵。

內嵌 OpenClaw 設定

啟用套件組合時，Claude settings.json 會匯入為預設的內嵌 OpenClaw 設定。 OpenClaw 會先清理 shell 覆寫索引鍵再套用：

• shellPath
• shellCommandPrefix

內嵌 OpenClaw LSP

• 已啟用的 Claude 套件組合可以提供 LSP 伺服器設定。
• OpenClaw 會載入 .lsp.json，以及任何資訊清單宣告的 lspServers 路徑。
• 套件組合 LSP 設定會合併至有效的內嵌 OpenClaw LSP 預設值。
• 目前僅能執行支援且以 stdio 為基礎的 LSP 伺服器；不支援的 傳輸仍會顯示於 openclaw plugins inspect <id> 中。

已偵測但未執行

下列項目會被辨識並顯示於診斷資訊中，但 OpenClaw 不會執行：

• Claude agents、hooks/hooks.json 自動化、outputStyles
• Cursor .cursor/agents、.cursor/hooks.json、.cursor/rules
• Codex .app.json 中能力報告以外的中繼資料

套件組合格式

偵測優先順序

OpenClaw 會先檢查原生外掛格式：

1. openclaw.plugin.json，或具有 openclaw.extensions 的有效 package.json，會視為原生外掛
2. 套件組合標記（.codex-plugin/、.claude-plugin/，或預設 Claude/Cursor 配置），會視為套件組合

如果目錄同時包含兩種格式，OpenClaw 會使用原生路徑。這可防止 雙格式套件以套件組合形式被部分安裝。

執行階段相依性與清理

• 第三方相容套件組合在啟動時不會獲得 npm install 修復。 它們應透過 openclaw plugins install 安裝，並將所需的一切 隨附於已安裝的外掛目錄中。
• OpenClaw 擁有的隨附外掛，若非隨核心以輕量形式提供， 就可透過外掛安裝程式下載。閘道啟動時絕不會為它們執行套件管理器。
• openclaw doctor --fix 會移除過期的本機隨附外掛安裝記錄， 並且當設定仍參照可下載外掛，但本機外掛索引中缺少該外掛時，可將其復原。

安全性

套件組合的信任邊界比原生外掛更窄：

• OpenClaw 不會在處理程序內載入任意套件組合執行階段模組。
• Skills 和鉤子套件路徑必須保持在外掛根目錄內（會檢查邊界）。
• 讀取設定檔時會執行相同的邊界檢查。
• 支援的 stdio MCP 伺服器可能會以子處理程序啟動。

這使套件組合預設更安全，但你仍應就其公開的功能， 將第三方套件組合視為受信任內容。

疑難排解

相關內容

• 安裝與設定外掛
• 建置外掛 - 建立原生外掛
• 外掛資訊清單 - 原生資訊清單結構描述