外掛

管理閘道外掛、鉤子套件和相容套件組合。

命令

openclaw plugins list [--enabled] [--verbose] [--json]openclaw plugins search <query> [--limit <n>] [--json]openclaw plugins install <path-or-spec> [--link] [--force] [--pin] [--marketplace <source>]openclaw plugins inspect <id> [--runtime] [--json]openclaw plugins inspect --all [--runtime] [--json]openclaw plugins info <id>                    # inspect 的別名openclaw plugins enable <id>openclaw plugins disable <id>openclaw plugins uninstall <id> [--dry-run] [--keep-files] [--force]openclaw plugins update <id-or-npm-spec> | --all [--dry-run]openclaw plugins registry [--refresh] [--json]openclaw plugins doctoropenclaw plugins init <id> [--name <name>] [--type tool|provider] [--directory <path>]openclaw plugins build [--entry <path>] [--check]openclaw plugins validate [--entry <path>]openclaw plugins marketplace entries [--offline] [--feed-profile <name>] [--json]openclaw plugins marketplace list <source> [--json]openclaw plugins marketplace refresh [--feed-profile <name>] [--expected-sha256 <sha256>] [--json]

若要調查緩慢的安裝、檢查、解除安裝或登錄檔重新整理，請使用 OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1 執行命令。追蹤會將各階段的計時寫入 stderr，並讓 JSON 輸出保持可解析。請參閱偵錯。

編寫

openclaw plugins init stock-quotes --name "Stock Quotes"cd stock-quotesnpm run plugin:buildnpm run plugin:validate

plugins init 預設會建立最小化的 TypeScript 工具外掛。第一個 引數是外掛 ID；--name 設定顯示名稱。OpenClaw 會將此 ID 用於預設輸出目錄和套件命名。工具鷹架使用 defineToolPlugin，並產生 package.json 指令碼 plugin:build 和 plugin:validate，這些指令碼會先建置，再呼叫 openclaw plugins build/validate。

plugins build 會匯入已建置的進入點、讀取其靜態工具中繼資料、寫入 openclaw.plugin.json，並保持 package.json 的 openclaw.extensions 一致。 plugins validate 會檢查產生的資訊清單、套件中繼資料和 目前進入點匯出是否仍然一致。完整的編寫工作流程請參閱工具外掛。

鷹架會寫入 TypeScript 原始碼，但會從已建置的 ./dist/index.js 進入點產生中繼資料，因此此工作流程也適用於已發布的命令列介面。當進入點並非預設套件進入點時，請使用 --entry <path>。在 CI 中使用 plugins build --check，可在產生的中繼資料過時時使其失敗，而不會 重寫檔案。

供應商鷹架

openclaw plugins init acme-models --name "Acme Models" --type providercd acme-modelsnpm installnpm run buildnpm testnpm run validate

供應商鷹架會建立通用的 OpenAI 相容模型供應商外掛， 其中包含 API 金鑰驗證的配管、執行 clawhub package validate 的 npm run validate 指令碼、ClawHub 套件中繼資料，以及可手動 分派的 GitHub Actions 工作流程，供日後透過 GitHub OIDC 進行受信任的發布。供應商鷹架不會產生 Skills，也不使用 openclaw plugins build/validate；這些命令用於工具 鷹架的產生中繼資料路徑。

發布前，請將預留位置 API 基底 URL、模型目錄、文件 路由、認證資訊文字和 README 內容替換為實際的供應商詳細資料。首次發布至 ClawHub 及設定受信任發布者時，請使用 產生的 README。

安裝

openclaw plugins search "calendar"                      # 搜尋 ClawHub 外掛openclaw plugins install @openclaw/<package>            # 受信任的官方目錄openclaw plugins install <package>                       # 任意 npm 套件openclaw plugins install clawhub:<package>                # 僅限 ClawHubopenclaw plugins install npm:<package>                    # 僅限 npmopenclaw plugins install npm-pack:<path.tgz>               # 本機 npm-pack tarballopenclaw plugins install git:github.com/<owner>/<repo>     # git 儲存庫openclaw plugins install git:github.com/<owner>/<repo>@<ref>openclaw plugins install <path>                            # 本機路徑或封存檔openclaw plugins install -l <path>                         # 建立連結而非複製openclaw plugins install <plugin>@<marketplace>             # 市集簡寫openclaw plugins install <plugin> --marketplace <name>      # 市集（明確指定）openclaw plugins install <package> --force                  # 確認來源／覆寫現有項目openclaw plugins install <package> --pin                    # 鎖定解析出的 npm 版本openclaw plugins install clawhub:<package> --acknowledge-clawhub-riskopenclaw plugins install <package> --dangerously-force-unsafe-install

測試設定期間安裝的維護者，可以使用受保護的環境變數覆寫自動外掛安裝 來源。請參閱 外掛安裝覆寫。

plugins search 會向 ClawHub 查詢可安裝的 code-plugin 和 bundle-plugin 套件（不包含 Skills；請使用 openclaw skills search 查詢 Skills）。 預設 --limit 為 20，上限為 100。它只會讀取遠端目錄，不會 檢查本機狀態、變更設定、安裝套件或載入外掛執行階段。 結果包含 ClawHub 套件名稱、系列、通道、版本、 摘要，以及如 openclaw plugins install clawhub:<package> 的安裝提示。

ClawHub 安裝使用明確的 clawhub:<package> 定位器：

openclaw plugins install clawhub:openclaw-codex-app-serveropenclaw plugins install clawhub:openclaw-codex-app-server@1.2.3

在啟動切換期間，符合 npm 安全命名規則的裸外掛規格預設會從 npm 安裝，除非它們符合官方外掛 ID：

openclaw plugins install openclaw-codex-app-server

使用 npm: 明確指定僅透過 npm 解析：

openclaw plugins install npm:openclaw-codex-app-serveropenclaw plugins install npm:@openclaw/discord@2026.5.20openclaw plugins install npm:@scope/plugin-name@1.0.1

OpenClaw 會在安裝前檢查公告的外掛 API／最低閘道相容性。當所選 ClawHub 版本發佈 ClawPack 成品時，OpenClaw 會下載帶版本的 npm-pack .tgz、驗證 ClawHub 摘要標頭和成品摘要，然後透過一般封存檔路徑安裝。沒有 ClawPack 中繼資料的舊版 ClawHub 版本仍會透過舊版套件封存檔驗證路徑安裝。記錄的安裝會保留其 ClawHub 來源中繼資料、成品種類、npm 完整性、npm shasum、tarball 名稱和 ClawPack 摘要資訊，以供日後更新使用。 未指定版本的 ClawHub 安裝會保留未指定版本的記錄規格，讓 openclaw plugins update 可以跟進較新的 ClawHub 版本；clawhub:pkg@1.2.3 和 clawhub:pkg@beta 之類的明確版本或標籤選擇器，仍會釘選至該選擇器。

市集簡寫

當市集名稱存在於 Claude 的本機登錄檔快取 ~/.claude/plugins/known_marketplaces.json 中時，使用 plugin@marketplace 簡寫：

openclaw plugins marketplace list <marketplace-name>openclaw plugins install <plugin-name>@<marketplace-name>

使用 --marketplace 明確傳入市集來源：

openclaw plugins install <plugin-name> --marketplace <marketplace-name>openclaw plugins install <plugin-name> --marketplace <owner/repo>openclaw plugins install <plugin-name> --marketplace https://github.com/<owner>/<repo>openclaw plugins install <plugin-name> --marketplace ./my-marketplace

對於本機路徑和封存檔，OpenClaw 會自動偵測：

• 原生 OpenClaw 外掛（openclaw.plugin.json）
• Codex 相容套件組（.codex-plugin/plugin.json）
• Claude 相容套件組（.claude-plugin/plugin.json，或缺少該資訊清單檔案時的預設 Claude 元件配置）
• Cursor 相容套件組（.cursor-plugin/plugin.json）

受管理的本機安裝必須是外掛目錄或封存檔。獨立的 .js、 .mjs、.cjs 和 .ts 外掛檔案不會由 plugins install 複製到受管理的外掛 根目錄，也不會因為直接放置在 ~/.openclaw/extensions 或 <workspace>/.openclaw/extensions 中而載入；這些 自動探索的根目錄會載入外掛套件或套件組目錄，並將 頂層指令碼檔案視為本機輔助程式而略過。請改為在 plugins.load.paths 中明確列出獨立檔案。

使用 -l/--link 指向本機外掛目錄而不複製它（會加入 plugins.load.paths）：

openclaw plugins install -l ./my-plugin

--link 不支援搭配 --marketplace 或 git: 安裝，且 要求本機路徑已經存在。若要建立非互動式本機連結， 請在檢閱來源後傳入 --force；它會確認來源，但不會 複製或覆寫連結的目錄。

列出

openclaw plugins listopenclaw plugins list --enabledopenclaw plugins list --verboseopenclaw plugins list --json

若啟動記錄顯示 plugins.allow is empty; discovered non-bundled plugins may auto-load: ...， 請執行 openclaw plugins list --enabled --verbose，或使用列出的外掛 ID 執行 openclaw plugins inspect <id>，以確認外掛 ID，並將可信任的 ID 複製至 openclaw.json 中的 plugins.allow。若該 警告可列出所有已發現的外掛，它會輸出可直接貼上的 plugins.allow 程式碼片段，其中已包含這些 ID。若外掛在沒有安裝／載入路徑來源資訊的情況下載入，請檢查該外掛 ID，接著將 可信任的 ID 固定於 plugins.allow，或從可信任的來源重新安裝外掛， 讓 OpenClaw 記錄安裝來源資訊。

若要在封裝的 Docker 映像檔中處理隨附外掛，請將外掛 原始碼目錄繫結掛載至相符的封裝原始碼路徑上，例如 /app/extensions/synology-chat。OpenClaw 會先發現該掛載的原始碼覆疊層， 然後才是 /app/dist/extensions/synology-chat；僅複製原始碼目錄 不會產生作用，因此一般封裝安裝仍會使用已編譯的 dist。

若要偵錯執行階段掛鉤：

• openclaw plugins inspect <id> --runtime --json 會顯示模組載入檢查階段所登錄的掛鉤與診斷資訊。執行階段檢查絕不會安裝相依項目；請使用 openclaw doctor --fix 清理舊版相依項目狀態，或復原設定所參照但遺失且可下載的外掛。
• openclaw gateway status --deep --require-rpc 會確認可連線的閘道 URL／設定檔、服務／處理程序提示、設定路徑與 RPC 健全狀態。
• 非隨附的對話掛鉤（llm_input、llm_output、before_model_resolve、before_agent_reply、before_agent_run、before_agent_finalize、agent_end）需要 plugins.entries.<id>.hooks.allowConversationAccess=true。

外掛索引

外掛安裝中繼資料是由機器管理的狀態，而不是使用者設定。安裝與更新作業會將其寫入使用中 OpenClaw 狀態目錄下的共用 SQLite 狀態資料庫。installed_plugin_index 資料列會儲存持久的 installRecords 中繼資料，包括外掛資訊清單損壞或遺失的記錄，以及由資訊清單衍生的冷登錄快取，供 openclaw plugins update、解除安裝、診斷與冷外掛登錄使用。

plugins.installs 是已淘汰的手動設定介面。執行階段與更新命令只會讀取 SQLite 的已安裝外掛索引。請執行 openclaw doctor --fix，將舊版設定記錄匯入索引並移除已淘汰的鍵，再進行一般執行階段作業。

解除安裝

openclaw plugins uninstall <id>openclaw plugins uninstall <id> --dry-runopenclaw plugins uninstall <id> --keep-filesopenclaw plugins uninstall <id> --force

uninstall 會從 plugins.entries、持久保存的外掛索引及外掛允許／拒絕清單中移除外掛記錄，並在適用時移除連結的 plugins.load.paths 項目。除非設定了 --keep-files，否則解除安裝也會移除所追蹤的受管理安裝目錄，但僅限於該目錄解析後位於 OpenClaw 的外掛 extensions 根目錄內。若外掛目前占用 memory 或 contextEngine 插槽，該插槽會重設為預設值（記憶體為 memory-core，內容引擎為 legacy）。

uninstall 會輸出即將移除之項目的預覽，接著在進行變更前提示 Uninstall plugin "<id>"?。傳入 --force 可略過確認提示（適合指令碼與非互動式執行）；若未傳入，解除安裝需要互動式 TTY。--dry-run 會輸出相同的預覽，然後直接結束，不會提示或變更任何內容。

更新

openclaw plugins update <id-or-npm-spec>openclaw plugins update --allopenclaw plugins update <id-or-npm-spec> --dry-runopenclaw plugins update @openclaw/voice-callopenclaw plugins update @acme/demoopenclaw plugins update openclaw-codex-app-server --acknowledge-clawhub-riskopenclaw plugins update openclaw-codex-app-server --dangerously-force-unsafe-install

更新適用於受管理外掛索引中追蹤的外掛安裝，以及共用 SQLite 狀態中追蹤的掛鉤套件安裝。更新會重複使用使用者安裝外掛時已選擇的來源，因此不需要再次確認來源。

檢查

openclaw plugins inspect <id>openclaw plugins inspect <id> --runtimeopenclaw plugins inspect <id> --jsonopenclaw plugins inspect --all

依預設，檢查功能不會匯入外掛執行階段，但會顯示識別資訊、載入狀態、來源、資訊清單功能、政策旗標、診斷資訊、安裝中繼資料、套件功能，以及偵測到的任何 MCP 或 LSP 伺服器支援。JSON 輸出包含外掛資訊清單合約，例如 contracts.agentToolResultMiddleware 和 contracts.trustedToolPolicies，讓操作人員可在啟用或重新啟動外掛前稽核可信任介面的宣告。加入 --runtime 可載入外掛模組，並包含已登錄的掛鉤、工具、命令、服務、閘道方法和 HTTP 路由。執行階段檢查會直接回報遺失的外掛相依項目；安裝與修復仍由 openclaw plugins install、openclaw plugins update 和 openclaw doctor --fix 負責。

外掛擁有的命令列介面命令通常會安裝為根層級的 openclaw 命令群組，但外掛也可以在核心父命令下登錄巢狀命令，例如 openclaw nodes。在 inspect --runtime 顯示 cliCommands 下的命令後，請從列出的路徑執行該命令；例如，登錄 demo-git 的外掛可使用 openclaw demo-git ping 驗證。

每個外掛會依其在執行階段實際登錄的內容分類：

如需進一步瞭解功能模型，請參閱外掛形態。

修復

openclaw plugins doctor

doctor 會回報外掛載入錯誤、資訊清單／探索診斷、相容性通知，以及過時的外掛設定參照，例如缺少外掛插槽。當安裝樹狀結構與外掛設定都沒有問題時，會輸出 No plugin issues detected.。如果仍有過時設定，但安裝樹狀結構在其他方面皆正常，摘要會如實說明，而不會暗示外掛完全正常。

如果已設定的外掛存在於磁碟上，但遭載入器的路徑安全檢查封鎖，設定驗證會保留該外掛項目，並將其回報為 present but blocked。請修正前述的外掛封鎖診斷，例如路徑擁有權或所有使用者皆可寫入的權限，而不要移除 plugins.entries.<id> 或 plugins.allow 設定。

若發生模組形態失敗，例如缺少 register/activate 匯出，請使用 OPENCLAW_PLUGIN_LOAD_DEBUG=1 重新執行，以在診斷輸出中加入精簡的匯出形態摘要。

登錄檔

openclaw plugins registryopenclaw plugins registry --refreshopenclaw plugins registry --json

本機外掛登錄檔是 OpenClaw 持久保存的冷讀取模型，用於記錄已安裝外掛的身分、啟用狀態、來源中繼資料及貢獻項目的擁有權。一般啟動、提供者擁有者查詢、頻道設定分類與外掛清單，都能在不匯入外掛執行階段模組的情況下讀取該登錄檔。

使用 plugins registry 檢查持久保存的登錄檔是否存在、是否為最新或已過時。使用 --refresh，根據持久保存的外掛索引、設定原則及資訊清單／套件中繼資料重建登錄檔。這是修復路徑，不是執行階段啟用路徑。

openclaw doctor --fix 也會修復登錄檔周邊由系統管理的 npm 漂移。如果受管理的外掛 npm 專案或舊版扁平受管理 npm 根目錄下，存在孤立或復原的 @openclaw/* 套件並遮蔽內建外掛，Doctor 會移除該過時套件並重建登錄檔，使啟動程序改為依據內建資訊清單進行驗證。當具權威性的安裝記錄選定某個受管理的世代，但仍殘留較舊的扁平目錄或世代目錄時，Doctor 會停用這些過時樹狀結構，待閘道重新啟動後再予以清除。Doctor 也會將主機的 openclaw 套件重新連結至宣告 peerDependencies.openclaw 的受管理 npm 外掛中，讓 openclaw/plugin-sdk/* 等套件本機執行階段匯入在更新或修復 npm 後仍可解析。

市集

openclaw plugins marketplace entriesopenclaw plugins marketplace entries --offlineopenclaw plugins marketplace entries --jsonopenclaw plugins marketplace entries --feed-profile <name>openclaw plugins marketplace entries --feed-url <url>openclaw plugins marketplace list <source>openclaw plugins marketplace list <source> --jsonopenclaw plugins marketplace refreshopenclaw plugins marketplace refresh --feed-profile <name>openclaw plugins marketplace refresh --feed-url <url>openclaw plugins marketplace refresh --expected-sha256 <sha256> --json

plugins marketplace entries 會列出已設定 OpenClaw 市集摘要來源中的項目。預設會嘗試使用託管摘要來源，並在失敗時改用最近一次接受的快照或內建資料。使用 --feed-profile <name> 讀取特定的已設定設定檔，使用 --feed-url <url> 讀取明確指定的託管摘要來源 URL，並使用 --offline 在不擷取摘要來源的情況下讀取最近一次接受的快照。

plugins marketplace refresh 會重新整理已設定的託管摘要來源快照，並回報 OpenClaw 接受的是託管資料、託管快照或內建備援資料。當呼叫端要求除非新的託管承載內容符合固定的總和檢查碼，否則命令必須失敗時，請使用 --expected-sha256。

市集 list 可接受本機市集路徑、marketplace.json 路徑、如 owner/repo 的 GitHub 簡寫、GitHub 儲存庫 URL 或 git URL。--json 會輸出解析後的來源標籤，以及剖析後的市集資訊清單與外掛項目。

市集重新整理會載入託管的 OpenClaw 市集摘要來源，並將 驗證後的回應持久保存為本機託管摘要來源快照。若未指定選項，會使用 已設定的預設摘要來源設定檔。使用 --feed-profile <name> 重新整理 特定的已設定設定檔，使用 --feed-url <url> 重新整理明確指定的託管 摘要來源 URL，使用 --expected-sha256 <sha256> 要求承載內容總和檢查碼相符 （sha256:<hex> 或純 64 字元十六進位摘要），並使用 --json 取得機器可讀輸出。明確指定的託管摘要來源 URL 不得包含 認證資訊、查詢字串或片段。未固定總和檢查碼的重新整理可回報 託管快照或內建備援結果，而不讓命令失敗。固定總和檢查碼的 重新整理除非接受新的託管承載內容，否則會失敗；而成功接受託管內容的 重新整理若 OpenClaw 無法持久保存驗證後的快照，也會失敗。

內建的 clawhub-public 設定檔預期承載內容身分為 clawhub-official。ClawHub 產生並交付其正式環境公開金鑰後， OpenClaw 會內建該金鑰。在此之前，內建設定檔 不會授予已簽署摘要來源的安裝授權。公開金鑰必須來自受信任的 發行或操作者管道，而不是摘要來源主機上的金鑰端點。

OpenClaw 會驗證 DSSE 信封，且當設定檔宣告 feedId 時， 要求解碼後的承載內容 ID 與其相符。內建的 clawhub-public 設定檔一律宣告其身分，以防止其他摘要來源的有效文件 透過該設定檔遭到重播。

在分階段推出期間，既有且省略 feedId 的自訂已簽署設定檔 會保留簽章驗證，但不繫結承載內容身分。新的自訂 設定檔應宣告 feedId。摘要來源設定檔的設定介面將 連同 Control UI 所需的呈現中繼資料另行提供；其 Doctor 診斷必須要求操作者提供缺少的身分，而且不得 從摘要來源 URL 推斷身分。此信任繫結不會還原已淘汰的 根層級 marketplaces 金鑰。

相關內容

• 建置外掛
• 命令列介面參考
• ClawHub