外掛系統
終端使用者安裝、啟用和疑難排解外掛的指南。
管理外掛
安裝、列出、更新、解除安裝和發布的快速範例。
外掛套件組
套件組相容性模型。
外掛資訊清單
資訊清單欄位和設定結構描述。
安全性
外掛安裝的安全性強化。
指令
OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1 執行該指令。追蹤會將階段計時寫入 stderr，並保持 JSON 輸出可解析。請參閱偵錯。
在 Nix 模式中（
OPENCLAW_NIX_MODE=1），openclaw.json 是不可變的。install、update、uninstall、enable 和 disable 都會拒絕執行。請改為編輯此安裝的 Nix 來源（nix-openclaw 的 programs.openclaw.config 或 instances.<name>.config），然後重新建置。請參閱 agent-first 快速開始。隨附外掛會隨 OpenClaw 一起提供。部分預設啟用（例如隨附模型提供者、隨附語音提供者，以及隨附瀏覽器外掛）；其他則需要
plugins enable。原生 OpenClaw 外掛會提供 openclaw.plugin.json，其中含有內嵌 JSON Schema（configSchema，即使為空亦然）。相容套件組則改用自己的套件組資訊清單。plugins list 會顯示 Format: openclaw 或 Format: bundle。詳細列出/資訊輸出也會顯示套件組子類型（codex、claude 或 cursor），以及偵測到的套件組能力。作者
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，可在產生的中繼資料過期時失敗，而不重寫檔案。
提供者鷹架
clawhub package validate 的 npm run validate 指令碼、ClawHub 套件中繼資料，以及手動觸發的 GitHub Actions 工作流程，以便未來透過 GitHub OIDC 進行受信任發布。提供者鷹架不會產生 Skills，也不會使用 openclaw plugins build/validate；這些指令適用於工具鷹架的產生中繼資料路徑。
發布前，請將預留位置 API 基礎 URL、模型目錄、文件路由、認證文字和 README 文案替換為真實提供者詳細資訊。請使用產生的 README 進行首次 ClawHub 發布和受信任發布者設定。
安裝
plugins search 會查詢 ClawHub 中可安裝的 code-plugin 和 bundle-plugin 套件（不是 Skills；請使用 openclaw skills search 搜尋那些項目）。預設 --limit 為 20，上限為 100。它只會讀取遠端目錄：不檢查本機狀態、不變更設定、不安裝套件，也不載入外掛執行階段。結果包含 ClawHub 套件名稱、系列、通道、版本、摘要，以及像 openclaw plugins install clawhub:<package> 這樣的安裝提示。
ClawHub 是大多數外掛的主要散布與探索介面。npm 仍是受支援的備援和直接安裝路徑。OpenClaw 擁有的
@openclaw/* 外掛套件已再次發布到 npm；請參閱 npmjs.com/org/openclaw 上的目前清單，或外掛清冊。穩定版安裝使用 latest。Beta 通道的安裝與更新會在可用時優先使用 npm beta dist-tag，否則退回 latest。在延伸穩定通道上，具有裸/預設或 latest 意圖的官方 npm 外掛會解析為確切已安裝的核心版本。精確釘選和明確非 latest 標籤、第三方套件，以及非 npm 來源不會被重寫。設定包含與無效設定修復
設定包含與無效設定修復
如果你的
plugins 區段由單一檔案 $include 支援，plugins install/update/enable/disable/uninstall 會寫入該被包含的檔案，並讓 openclaw.json 保持不變。根包含、包含陣列，以及帶有同層覆寫的包含會失敗並關閉，而不會展平。支援的形狀請參閱設定包含。如果安裝期間設定無效，plugins install 通常會失敗並關閉，並告訴你先執行 openclaw doctor --fix。在閘道啟動和熱重新載入期間，無效外掛設定會像任何其他無效設定一樣失敗並關閉；openclaw doctor --fix 可以隔離無效的外掛項目。唯一記錄在文件中的安裝時例外，是針對明確選擇加入 openclaw.install.allowInvalidConfigRecovery 的外掛所提供的狹窄隨附外掛復原路徑。--force 與重新安裝相對於更新
--force 與重新安裝相對於更新
--force 會重用現有安裝目標，並就地覆寫已安裝的外掛或鉤子套件。當你有意從新的本機路徑、封存檔、ClawHub 套件或 npm 成品重新安裝同一個 ID 時使用。對於已追蹤 npm 外掛的例行升級，請優先使用 openclaw plugins update <id-or-npm-spec>。如果你對已安裝的外掛 ID 執行 plugins install，OpenClaw 會停止，並指向 plugins update <id-or-npm-spec> 進行一般升級，或在你確實想從不同來源覆寫目前安裝時，指向 plugins install <package> --force。--force 不支援與 --link 搭配使用。--pin 範圍
--pin 範圍
--pin 只套用於 npm 安裝，並記錄解析後的確切 <name>@<version>。它不支援 git: 安裝（請改為在規格中釘選 ref，例如 git:github.com/acme/plugin@v1.2.3），也不支援 --marketplace（市集安裝會持久保存市集來源中繼資料，而不是 npm 規格）。--dangerously-force-unsafe-install
--dangerously-force-unsafe-install
--dangerously-force-unsafe-install 已棄用，現在不會執行任何動作。OpenClaw 不再為外掛安裝執行內建的安裝期間危險程式碼封鎖。當需要主機特定的安裝政策時，請使用操作員擁有的 security.installPolicy 介面。外掛 before_install 鉤子是外掛執行階段生命週期鉤子，不是命令列介面安裝的主要政策邊界。如果你在 ClawHub 發布的外掛遭登錄檔掃描隱藏或封鎖，請使用 ClawHub 發布中的發布者步驟。--dangerously-force-unsafe-install 不會要求 ClawHub 重新掃描外掛，也不會讓遭封鎖的發行版本公開。--acknowledge-clawhub-risk
--acknowledge-clawhub-risk
社群 ClawHub 安裝會在下載前檢查所選發行版本的信任記錄。如果 ClawHub 停用該發行版本的下載、回報惡意掃描結果，或將該發行版本置於封鎖性審核狀態（隔離、撤銷），無論是否使用此旗標，OpenClaw 都會直接拒絕。對於非封鎖性的高風險掃描狀態或審核狀態，OpenClaw 會顯示信任詳細資訊，並在繼續前要求確認。只有在審閱 ClawHub 警告並決定不透過互動提示繼續後，才使用
--acknowledge-clawhub-risk。擱置或過期（尚未乾淨）的掃描結果會警告，但不需要確認。官方 ClawHub 套件和隨附 OpenClaw 外掛來源會完全略過此發行版本信任檢查。鉤子套件與 npm 規格
鉤子套件與 npm 規格
plugins install 也是安裝在 package.json 中公開 openclaw.hooks 之鉤子套件的介面。請使用 openclaw hooks 取得篩選後的鉤子可見性和逐鉤子啟用功能，而不是用於套件安裝。Npm 規格僅限登錄檔（套件名稱加上選用的精確版本或 dist-tag）。Git/URL/file 規格與 semver 範圍會被拒絕。為了安全，即使你的 shell 有全域 npm 安裝設定，依賴項安裝仍會在每個外掛一個受管理的 npm 專案中搭配 --ignore-scripts 執行。受管理的外掛 npm 專案會繼承 OpenClaw 套件層級的 npm overrides，因此主機安全性釘選也會套用到提升的外掛依賴項。使用 npm:<package> 讓 npm 解析明確化。裸套件規格在啟動轉換期間也會直接從 npm 安裝，除非它們符合官方外掛 ID。符合內建外掛的原始 @openclaw/* 規格會先解析為映像檔擁有的內建副本，然後才回退到 npm。例如，openclaw plugins install @openclaw/discord@2026.5.20 --pin 會使用目前 OpenClaw 建置中的內建 Discord 外掛，而不是建立受管理的 npm 覆寫。若要強制使用外部 npm 套件，請使用 openclaw plugins install npm:@openclaw/discord@2026.5.20 --pin。裸規格與 @latest 會停留在穩定軌道。OpenClaw 日期戳記修正版，例如 2026.5.3-1，在這項檢查中算作穩定版。如果 npm 將任一形式解析為預發行版，OpenClaw 會停止並要求你使用預發行標籤（@beta/@rc）或精確的預發行版本（@1.2.3-beta.4）明確選擇加入。對於沒有精確版本的 npm 安裝（npm:<package> 或 npm:<package>@latest），OpenClaw 會在安裝前檢查解析出的套件中繼資料。如果最新的穩定套件需要較新的 OpenClaw 外掛 API 或最低主機版本，OpenClaw 會檢查較舊的穩定版本，並改為安裝最新的相容發行版。精確版本與明確的 dist-tag 會保持嚴格：不相容的選擇會失敗，並要求你升級 OpenClaw 或選擇相容版本。如果裸安裝規格符合官方外掛 ID（例如 diffs），OpenClaw 會直接安裝目錄項目。若要安裝同名的 npm 套件，請使用明確的 scoped 規格（例如 @scope/diffs）。Git 儲存庫
Git 儲存庫
使用
git:<repo> 直接從 git 儲存庫安裝。支援的形式：git:github.com/owner/repo、git:owner/repo、完整的 https://、ssh://、git://、file://，以及 git@host:owner/repo.git 複製 URL。新增 @<ref> 或 #<ref>，可在安裝前簽出分支、標籤或提交。Git 安裝會複製到暫存目錄，在提供要求的 ref 時簽出該 ref，然後使用一般外掛目錄安裝程式，因此資訊清單驗證、操作者安裝政策、套件管理器安裝工作與安裝記錄的行為都會像 npm 安裝一樣。記錄的 git 安裝包含來源 URL/ref 加上解析出的提交，因此 openclaw plugins update 之後可以重新解析來源。從 git 安裝後，使用 openclaw plugins inspect <id> --runtime --json 驗證執行階段註冊，例如閘道方法與命令列介面命令。如果外掛使用 api.registerCli 註冊了命令列介面根目錄，請透過 OpenClaw 根命令列介面直接執行該命令，例如 openclaw demo-plugin ping。封存檔
封存檔
支援的封存檔：
.zip、.tgz、.tar.gz、.tar。原生 OpenClaw 外掛封存檔必須在解壓出的外掛根目錄包含有效的 openclaw.plugin.json；只包含 package.json 的封存檔會在 OpenClaw 寫入安裝記錄前被拒絕。當檔案是 npm-pack tarball，且你想使用與登錄檔安裝相同的每外掛受管理 npm 專案路徑時，請使用 npm-pack:<path.tgz>，
包括 package-lock.json 驗證、提升的依賴項掃描，
以及 npm 安裝記錄。一般封存檔路徑仍會作為本機
封存檔安裝在外掛 extensions 根目錄下。也支援 Claude 市集安裝。clawhub:<package> 定位器：
npm: 讓僅限 npm 的解析明確化：
.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 簡寫：
--marketplace 明確傳入市集來源：
- 市集來源
- 遠端市集規則
- 來自
~/.claude/plugins/known_marketplaces.json的 Claude 已知市集名稱 - 本機市集根目錄或
marketplace.json路徑 - GitHub 儲存庫簡寫，例如
owner/repo - GitHub 儲存庫 URL，例如
https://github.com/owner/repo - git URL
- 原生 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 中明確列出獨立檔案。
相容套件組合會安裝到一般外掛根目錄，並參與相同的列表/資訊/啟用/停用流程。今天支援套件組合 Skills、Claude command-skills、Claude
settings.json 預設值、Claude .lsp.json / 資訊清單宣告的 lspServers 預設值、Cursor command-skills，以及相容的 Codex hook 目錄；其他偵測到的套件組合能力會顯示在診斷/資訊中，但尚未接入執行階段執行。-l/--link 指向本機外掛目錄而不複製它（新增
到 plugins.load.paths）：
--link 不支援搭配 --force（連結外掛會直接指向來源
路徑，因此沒有任何可就地覆寫的內容）、--marketplace，或
git: 安裝，且它需要一個已存在的本機路徑。
從工作區 extensions 根目錄探索到的工作區來源外掛，在明確啟用前
不會匯入或執行。對於本機開發，
請執行
openclaw plugins enable <plugin-id> 或設定
plugins.entries.<plugin-id>.enabled: true；如果你的設定使用
plugins.allow，也請在其中包含相同的外掛 ID。這項失敗關閉規則
也適用於通道設定明確針對工作區來源外掛進行
僅設定載入時，因此在該工作區外掛仍停用或排除於允許清單之外時，本機通道外掛設定程式碼
不會執行。連結安裝
與明確的 plugins.load.paths 項目會依其
解析出的外掛來源遵循一般政策。請參閱
設定外掛政策
與設定參考。在 npm 安裝上使用 --pin，可將解析出的精確規格（name@version）儲存在受管理的外掛索引中，同時保留預設的未釘選行為。列表
只顯示已啟用的外掛。
從表格檢視切換為每個外掛的詳細行，包含格式/來源/起源/版本/啟用中繼資料。
機器可讀的清冊，加上登錄檔診斷與套件依賴項安裝狀態。
plugins list 會先讀取持久化的本機外掛登錄檔，並在登錄檔遺失或無效時使用僅從資訊清單衍生的回退。它可用於檢查外掛是否已安裝、已啟用，並且對冷啟動規劃可見，但它不是對已執行中閘道程序的即時執行階段探測。變更外掛程式碼、啟用狀態、hook 政策或 plugins.load.paths 後，請重新啟動服務該通道的閘道，再預期新的 register(api) 程式碼或 hook 會執行。對於遠端/容器部署，請確認你重新啟動的是實際的 openclaw gateway run 子程序，而不只是包裝器程序。plugins list --json 會包含每個外掛來自 package.json
dependencies 與 optionalDependencies 的 dependencyStatus。OpenClaw 會檢查這些套件
名稱是否存在於外掛一般 Node node_modules 查找路徑中；它
不會匯入外掛執行階段程式碼、執行套件管理器，或修復遺失的
依賴項。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 映像檔內的內建外掛工作，請將外掛
來源目錄 bind-mount 到相符的封裝來源路徑上，例如
/app/extensions/synology-chat。OpenClaw 會先於
/app/dist/extensions/synology-chat 探索該掛載的來源覆蓋層；單純複製的來源目錄
會保持無作用，因此一般封裝安裝仍會使用編譯後的 dist。
對於執行階段 hook 偵錯：
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 中繼資料，包括損壞或缺少外掛 manifest 的記錄，以及由 manifest 衍生、供 openclaw plugins update、解除安裝、診斷與冷外掛登錄使用的冷登錄快取。
當 OpenClaw 在設定中看到已發布的舊版 plugins.installs 記錄時，執行階段讀取會將它們視為相容性輸入，而不重寫 openclaw.json。明確的外掛寫入與 openclaw doctor --fix 會將這些記錄移入外掛索引，並在允許寫入設定時移除該設定鍵；如果任一寫入失敗，設定記錄會被保留，確保安裝中繼資料不會遺失。
解除安裝
uninstall 會在適用時從 plugins.entries、持久化外掛索引、外掛允許/拒絕清單項目，以及連結的 plugins.load.paths 項目中移除外掛記錄。除非設定 --keep-files，否則解除安裝也會移除受追蹤的受管理安裝目錄，但前提是它解析後位於 OpenClaw 的外掛 extensions 根目錄內。如果該外掛目前擁有 memory 或 contextEngine 插槽，該插槽會重設為預設值（記憶體為 memory-core，脈絡引擎為 legacy）。
uninstall 會列印將移除內容的預覽，然後在變更前提示 Uninstall plugin "<id>"?。傳入 --force 可略過確認提示（適合指令碼與非互動式執行）；若未使用它，解除安裝需要互動式 TTY。--dry-run 會列印相同預覽，並在不提示或變更任何內容的情況下結束。
--keep-config 支援作為 --keep-files 的已棄用別名。更新
hooks.internal.installs 中受追蹤的鉤子套件安裝。
解析外掛 id 與 npm 規格
解析外掛 id 與 npm 規格
當你傳入外掛 id 時，OpenClaw 會重用該外掛記錄的安裝規格。這表示先前儲存的 dist-tag（例如
@beta）與精確釘選版本，會在後續 update <id> 執行中繼續使用。在 update <id> --dry-run 期間，精確釘選的 npm 安裝會維持釘選。如果 OpenClaw 也能解析該套件的登錄預設線，且該預設線比已安裝的釘選版本更新，試執行會回報該釘選，並列印明確的 @latest 套件更新命令，以跟隨登錄預設線。該目標更新規則不同於大量 openclaw plugins update --all 維護路徑。大量更新仍會尊重一般受追蹤安裝規格，但受信任的官方 OpenClaw 外掛記錄可以同步到目前官方型錄目標，而不是停留在過時的精確官方套件上。當你刻意想讓精確或帶標籤的官方規格保持不變時，請使用目標式 update <id>。對於 npm 安裝，你也可以傳入包含 dist-tag 或精確版本的明確 npm 套件規格。OpenClaw 會將該套件名稱解析回受追蹤的外掛記錄、更新該已安裝外掛，並記錄新的 npm 規格供未來以 id 為基礎的更新使用。傳入不含版本或標籤的 npm 套件名稱，也會解析回受追蹤的外掛記錄。當外掛被釘選到精確版本，而你想將它移回登錄的預設發行線時，請使用此方式。Beta 通道更新
Beta 通道更新
目標式
openclaw plugins update <id-or-npm-spec> 會重用受追蹤的外掛規格，除非你傳入新的規格。大量 openclaw plugins update --all 在將受信任的官方外掛記錄同步到官方型錄目標時，會使用已設定的 update.channel，因此 beta 通道安裝可以留在 beta 發行線，而不會被靜默正規化為 stable/latest。openclaw update 也知道作用中的 OpenClaw 更新通道：在 beta 通道上，預設線 npm 與 ClawHub 外掛記錄會先嘗試 @beta。如果沒有外掛 beta 發行版本，它們會退回記錄的 default/latest 規格；npm 外掛在 beta 套件存在但安裝驗證失敗時也會退回。該退回會以警告回報，且不會導致核心更新失敗。精確版本與明確標籤會在目標式更新中維持釘選到該選擇器。版本檢查與完整性漂移
版本檢查與完整性漂移
在執行即時 npm 更新前，OpenClaw 會依 npm 登錄中繼資料檢查已安裝套件版本。如果已安裝版本與記錄的成品身分已符合解析後的目標，更新會略過，不會下載、重新安裝或重寫
openclaw.json。當存在已儲存的完整性雜湊，且擷取的成品雜湊發生變更時，OpenClaw 會將其視為 npm 成品漂移。互動式 openclaw plugins update 命令會列印預期與實際雜湊，並在繼續前要求確認。非互動式更新輔助工具會預設失敗關閉，除非呼叫端提供明確的繼續政策。更新時的 --dangerously-force-unsafe-install
更新時的 --dangerously-force-unsafe-install
--dangerously-force-unsafe-install 也會為了相容性在 plugins update 上被接受，但它已被棄用，且不再變更外掛更新行為。操作者 security.installPolicy 仍可阻擋更新；外掛 before_install 鉤子只會套用於外掛鉤子已載入的程序。更新時的 --acknowledge-clawhub-risk
更新時的 --acknowledge-clawhub-risk
由社群 ClawHub 支援的外掛更新，在下載替換套件前會執行與安裝相同的精確發行信任檢查。針對已審查、應在所選 ClawHub 發行版本具有高風險信任警告時繼續的自動化，請使用
--acknowledge-clawhub-risk。官方 ClawHub 套件與內建 OpenClaw 外掛來源會略過此發行信任提示。檢查
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 驗證。
每個外掛都會依其在執行階段實際註冊的內容分類：
| 形態 | 含義 |
|---|---|
plain-capability | 恰好一種能力類型（例如僅提供者的外掛） |
hybrid-capability | 超過一種能力類型（例如文字 + 語音 + 影像） |
hook-only | 只有鉤子，沒有能力、工具、命令、服務或路由 |
non-capability | 有工具/命令/服務，但沒有能力 |
--json 旗標會輸出適合指令碼與稽核的機器可讀報告。inspect --all 會呈現整體外掛群的表格，包含形態、能力種類、相容性通知、套件能力與鉤子摘要欄位。info 是 inspect 的別名。Doctor
doctor 會回報外掛載入錯誤、manifest/探索診斷、相容性通知，以及過時外掛設定引用，例如缺少的外掛插槽。當安裝樹與外掛設定乾淨時，它會列印 No plugin issues detected. 如果仍有過時設定，但安裝樹在其他方面健康，摘要會如此說明，而不是暗示整體外掛健康狀態完全正常。
如果已設定外掛存在於磁碟上，但被載入器的路徑安全檢查阻擋，設定驗證會保留該外掛項目，並將它回報為 present but blocked。請修正前面的受阻外掛診斷，例如路徑擁有權或 world-writable 權限，而不是移除 plugins.entries.<id> 或 plugins.allow 設定。
對於模組形態失敗，例如缺少 register/activate 匯出，請以 OPENCLAW_PLUGIN_LOAD_DEBUG=1 重新執行，以在診斷輸出中包含精簡的匯出形態摘要。
登錄
plugins registry 檢查持久化登錄是否存在、目前有效或過時。使用 --refresh 從持久化外掛索引、設定政策與 manifest/package 中繼資料重建它。這是修復路徑，不是執行階段啟用路徑。
openclaw doctor --fix 也會修復與登錄相鄰的受管理 npm 漂移：如果受管理外掛 npm 專案下的孤立或已復原 @openclaw/* 套件，或舊版扁平受管理 npm 根目錄，遮蔽了內建外掛，doctor 會移除該過時套件並重建登錄，讓啟動能依內建 manifest 驗證。Doctor 也會將主機 openclaw 套件重新連結到宣告 peerDependencies.openclaw 的受管理 npm 外掛中，讓套件本機執行階段匯入（例如 openclaw/plugin-sdk/*）在更新或 npm 修復後能解析。
市集
plugins marketplace entries 會列出已設定的 OpenClaw marketplace feed 中的項目。預設會嘗試使用託管的 feed，並在失敗時退回到最新接受的快照或內建資料。使用 --feed-profile <name> 讀取特定已設定的設定檔，使用 --feed-url <url> 讀取明確的託管 feed URL，並使用 --offline 在不擷取 feed 的情況下讀取最新接受的快照。
plugins marketplace refresh 會重新整理已設定的託管 feed 快照，並回報 OpenClaw 是否接受了託管資料、託管快照，或內建後援資料。當呼叫端需要命令在新的託管承載內容不符合固定校驗和時失敗，請使用 --expected-sha256。
Marketplace list 接受本機 marketplace 路徑、marketplace.json 路徑、像 owner/repo 這樣的 GitHub 簡寫、GitHub repo URL，或 git URL。--json 會列印解析後的來源標籤，以及剖析後的 marketplace manifest 和外掛項目。
Marketplace refresh 會載入託管的 OpenClaw marketplace feed，並將
驗證過的回應保存為本機託管 feed 快照。若未提供選項，會使用
已設定的預設 feed 設定檔。使用 --feed-profile <name> 重新整理
特定已設定的設定檔，使用 --feed-url <url> 重新整理明確的託管
feed URL，使用 --expected-sha256 <sha256> 要求相符的承載內容校驗和
（sha256:<hex> 或裸露的 64 字元十六進位摘要），並使用 --json 取得
機器可讀輸出。明確的託管 feed URL 不得包含
憑證、查詢字串或片段。未固定的重新整理可以回報
託管快照或內建後援結果，而不讓命令失敗。固定的
重新整理必須接受新的託管承載內容才會成功；若 OpenClaw 無法保存已驗證的快照，成功的託管
重新整理也會失敗。