外掛

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

命令

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>                    # alias for inspectopenclaw 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 執行命令。追蹤會將各階段耗時 寫入標準錯誤，並讓 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"                      # search ClawHub pluginsopenclaw plugins install <package>                       # source auto-detectionopenclaw plugins install clawhub:<package>                # ClawHub onlyopenclaw plugins install npm:<package>                    # npm onlyopenclaw plugins install npm-pack:<path.tgz>               # local npm-pack tarballopenclaw plugins install git:github.com/<owner>/<repo>     # git repoopenclaw plugins install git:github.com/<owner>/<repo>@<ref>openclaw plugins install <path>                            # local path or archiveopenclaw plugins install -l <path>                         # link instead of copyopenclaw plugins install <plugin>@<marketplace>             # marketplace shorthandopenclaw plugins install <plugin> --marketplace <name>      # marketplace (explicit)openclaw plugins install <package> --force                  # overwrite existing installopenclaw plugins install <package> --pin                    # pin resolved npm versionopenclaw 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 不支援搭配 --force（連結的外掛會直接指向來源 路徑，因此沒有可就地覆寫的內容）、--marketplace 或 git: 安裝，且需要已存在的本機路徑。

列出

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、解除安裝、診斷及冷啟動外掛登錄使用。

當 OpenClaw 在設定中發現已發布的舊版 plugins.installs 記錄時，執行階段會將其視為相容性輸入讀取，而不改寫 openclaw.json。明確的外掛寫入操作與 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 的外掛擴充功能根目錄內。如果此外掛目前占用 memory 或 contextEngine 插槽，該插槽會重設為其預設值（記憶體為 memory-core，上下文引擎為 legacy）。

uninstall 會先列印即將移除內容的預覽，接著在變更前提示「要解除安裝外掛「」嗎？」。傳入 --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 openclaw-codex-app-server --acknowledge-clawhub-riskopenclaw plugins update openclaw-codex-app-server --dangerously-force-unsafe-install

更新會套用至託管外掛索引中受追蹤的外掛安裝項目，以及 hooks.internal.installs 中受追蹤的鉤子套件安裝項目。

檢查

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 會回報外掛載入錯誤、資訊清單／探索診斷、相容性通知，以及外掛插槽缺失等過時的外掛設定參照。當安裝樹與外掛設定均無問題時，會列印「未偵測到外掛問題。」如果仍有過時設定，但安裝樹在其他方面運作正常，摘要會明確指出此狀況，而不會暗示外掛完全健康。

如果設定的外掛存在於磁碟上，但遭載入器的路徑安全檢查封鎖，設定驗證會保留外掛項目，並將其回報為「存在但遭封鎖」。請修正前面的外掛封鎖診斷，例如路徑擁有權或所有人皆可寫入的權限，而非移除 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/* 套件遮蔽了內建外掛，診斷工具會移除該過時套件並重建登錄，讓啟動流程依據內建資訊清單進行驗證。診斷工具也會將主機的 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