外掛

管理閘道外掛、Hook 套件包與相容套件組合。

命令

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；Skills 請使用 openclaw skills search）。 --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