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

外掛系統

安裝、啟用和疑難排解外掛的使用者指南。

管理外掛

安裝、列出、更新、解除安裝和發布的快速範例。

外掛套件組合

套件組合相容性模型。

外掛資訊清單

資訊清單欄位和設定結構描述。

安全性

外掛安裝的安全強化。

​
命令

若要調查緩慢的安裝、檢查、解除安裝或登錄檔重新整理，請使用 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），然後重新建置。請參閱以代理程式為優先的快速入門。
隨附外掛會與 OpenClaw 一併提供。其中一些預設為啟用（例如隨附的模型供應商、隨附的語音供應商和隨附的瀏覽器外掛）；其他則需要 plugins enable。原生 OpenClaw 外掛提供包含內嵌 JSON Schema 的 openclaw.plugin.json（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，可在產生的中繼資料過時時使其失敗，而不會 重寫檔案。

​
供應商鷹架

供應商鷹架會建立通用的 OpenAI 相容模型供應商外掛， 其中包含 API 金鑰驗證的配管、執行 clawhub package validate 的 npm run validate 指令碼、ClawHub 套件中繼資料，以及可手動 分派的 GitHub Actions 工作流程，供日後透過 GitHub OIDC 進行受信任的發布。供應商鷹架不會產生 Skills，也不使用 openclaw plugins build/validate；這些命令用於工具 鷹架的產生中繼資料路徑。 發布前，請將預留位置 API 基底 URL、模型目錄、文件 路由、認證資訊文字和 README 內容替換為實際的供應商詳細資料。首次發布至 ClawHub 及設定受信任發布者時，請使用 產生的 README。

​
安裝

測試設定期間安裝的維護者，可以使用受保護的環境變數覆寫自動外掛安裝 來源。請參閱 外掛安裝覆寫。
在啟動切換期間，單純的套件名稱預設會從 npm 安裝；但若名稱符合隨附或官方外掛 ID，OpenClaw 會改用該本機／官方副本，而不會存取 npm 登錄檔。若你刻意想使用外部 npm 套件，請改用 npm:<package>。ClawHub 請使用 clawhub:<package>。請將安裝外掛視同執行程式碼；應優先使用鎖定版本。
ClawHub 套件和 OpenClaw 的隨附／官方目錄是受信任的安裝 來源。新的任意 npm、npm-pack:、git、本機路徑／封存檔或 市集來源會顯示警告，並在繼續前要求確認。以非互動方式安裝任意來源時， 你必須先審查並信任該來源，再傳入 --force。必要時，同一個 旗標也會覆寫現有的安裝目標。正常更新已追蹤的安裝時 不需要此旗標。這項確認與 --acknowledge-clawhub-risk 分開，後者僅適用於有風險的 ClawHub 發行版本信任 警告。--force 不會略過 security.installPolicy 或其餘 安裝安全檢查。
plugins search 會向 ClawHub 查詢可安裝的 code-plugin 和 bundle-plugin 套件（不包含 Skills；請使用 openclaw skills search 查詢 Skills）。 預設 --limit 為 20，上限為 100。它只會讀取遠端目錄，不會 檢查本機狀態、變更設定、安裝套件或載入外掛執行階段。 結果包含 ClawHub 套件名稱、系列、通道、版本、 摘要，以及如 openclaw plugins install clawhub:<package> 的安裝提示。
ClawHub 是多數外掛的主要散布與探索介面。Npm 仍是受支援的備援和直接安裝路徑。OpenClaw 擁有的 @openclaw/* 外掛套件已再次發布至 npm；請在 npmjs.com/org/openclaw 或 外掛清單查看目前清單。穩定版安裝使用 latest。 當 npm beta dist-tag 可用時，Beta 通道的安裝和更新會優先使用該標籤， 否則退回 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 的外掛所提供的狹義隨附外掛復原路徑。當現有主機設定有效，但新安裝外掛本身的設定不存在時，OpenClaw 會將安裝記錄為已停用，而不會寫入無效的已啟用項目。請設定 plugins.entries.<id>.config，然後執行 openclaw plugins enable <id>。如果現有外掛設定項目存在但無效，安裝會失敗且不會重寫該項目。
--force 會在不提示的情況下確認非 ClawHub 來源。它不會略過 security.installPolicy 或其餘安裝安全檢查。當外掛或鉤子套件已安裝時，它也會重複使用現有目標，並在原處覆寫。請在審查任意 npm、本機、封存檔、git 或市集來源後，或刻意重新安裝相同 ID 時使用。若要例行升級已追蹤的 npm 外掛，應優先使用 openclaw plugins update <id-or-npm-spec>。如果你針對已安裝的外掛 ID 執行 plugins install，OpenClaw 會停止，並引導你使用 plugins update <id-or-npm-spec> 進行一般升級；若你確實想要從不同來源覆寫目前的安裝，則改用 plugins install <package> --force。任意來源仍會顯示互動式來源警告；以非互動方式安裝時，必須在審查後傳入 --force。受信任的 ClawHub 和 OpenClaw 目錄來源不需要此旗標。搭配 --link 時，--force 會確認來源，但不會變更連結路徑的安裝模式。
--pin 僅適用於 npm 安裝，並會記錄解析後的確切 <name>@<version>。它不支援搭配 git: 安裝（請改為在規格中釘選參照，例如 git:github.com/acme/plugin@v1.2.3），也不支援搭配 --marketplace（市集安裝會保存市集來源中繼資料，而非 npm 規格）。
--dangerously-force-unsafe-install 已淘汰，現在不會執行任何操作。OpenClaw 不再針對外掛安裝執行內建的安裝階段危險程式碼封鎖。需要主機特定的安裝政策時，請使用由操作者擁有的 security.installPolicy 介面。外掛 before_install 鉤子是外掛執行階段的生命週期鉤子，並非命令列介面安裝的主要政策邊界。如果你發佈到 ClawHub 的外掛因登錄檔掃描而遭隱藏或封鎖，請依照 ClawHub 發佈中的發佈者步驟操作。--dangerously-force-unsafe-install 不會要求 ClawHub 重新掃描外掛，也不會將遭封鎖的版本設為公開。
社群 ClawHub 安裝會在下載前檢查所選版本的信任記錄。如果 ClawHub 停用該版本的下載、回報惡意掃描發現，或將該版本置於封鎖性審核狀態（隔離、撤銷），無論是否使用此旗標，OpenClaw 都會直接拒絕。對於非封鎖性的高風險掃描狀態或審核狀態，OpenClaw 會顯示信任詳細資料，並在繼續前要求確認。僅在檢閱 ClawHub 警告並決定略過互動式提示繼續後，才使用 --acknowledge-clawhub-risk。待處理或過期（尚未確認無問題）的掃描結果會顯示警告，但不要求確認。ClawHub 官方套件和 OpenClaw 隨附的外掛來源會完全略過此版本信任檢查。
plugins install 也是安裝鉤子套件的介面；這類套件會在 package.json 中公開 openclaw.hooks。請使用 openclaw hooks 篩選鉤子的可見性並逐一啟用鉤子，而非安裝套件。Npm 規格僅限登錄檔（套件名稱加上選用的確切版本或 dist-tag）。Git／URL／檔案規格和 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 會維持在穩定版本軌道。像 2026.5.3-1 這類帶日期戳記的 OpenClaw 修正版，在此檢查中視為穩定版本。如果 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 套件，請使用明確的限定範圍規格（例如 @scope/diffs）。
使用 git:<repo> 直接從 git 儲存庫安裝。支援的形式：git:github.com/owner/repo、git:owner/repo、完整的 https://、ssh://、git://、file://，以及 git@host:owner/repo.git 複製 URL。加入 @<ref> 或 #<ref>，即可在安裝前取出分支、標籤或提交。Git 安裝會複製到暫存目錄，並在有指定參照時取出該參照，接著使用一般的外掛目錄安裝程式，因此資訊清單驗證、操作者安裝政策、套件管理器安裝作業和安裝記錄的行為都與 npm 安裝相同。記錄的 git 安裝會包含來源 URL／參照與解析後的提交，讓 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 安裝使用明確的 clawhub:<package> 定位器：
在啟動切換期間，符合 npm 安全命名規則的裸外掛規格預設會從 npm 安裝，除非它們符合官方外掛 ID：
使用 npm: 明確指定僅透過 npm 解析：
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 簡寫：
使用 --marketplace 明確傳入市集來源：
  • 來自 ~/.claude/plugins/known_marketplaces.json 的 Claude 已知市集名稱
  • 本機市集根目錄或 marketplace.json 路徑
  • GitHub 儲存庫簡寫，例如 owner/repo
  • GitHub 儲存庫 URL，例如 https://github.com/owner/repo
  • git URL
對於本機路徑和封存檔，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 中明確列出獨立檔案。
相容套件組會安裝到一般外掛根目錄，並參與相同的列出／資訊／啟用／停用流程。目前支援套件組 Skills、Claude 命令 Skills、Claude settings.json 預設值、Claude .lsp.json／資訊清單宣告的 lspServers 預設值、Cursor 命令 Skills，以及相容的 Codex 鉤子目錄；其他偵測到的套件組功能會顯示於診斷／資訊中，但尚未接入執行階段執行。
使用 -l/--link 指向本機外掛目錄而不複製它（會加入 plugins.load.paths）：
--link 不支援搭配 --marketplace 或 git: 安裝，且 要求本機路徑已經存在。若要建立非互動式本機連結， 請在檢閱來源後傳入 --force；它會確認來源，但不會 複製或覆寫連結的目錄。
從工作區 extensions 根目錄探索到的工作區來源外掛，在明確啟用前不會 匯入或執行。進行本機開發時， 請執行 openclaw plugins enable <plugin-id> 或設定 plugins.entries.<plugin-id>.enabled: true；如果你的設定使用 plugins.allow，也請在其中加入相同的外掛 ID。此預設拒絕規則 也適用於頻道設定明確以工作區來源外掛為目標、 僅為設定而載入的情況；因此，只要該工作區外掛仍停用或未列入允許清單， 本機頻道外掛設定程式碼就不會執行。連結安裝和明確的 plugins.load.paths 項目，則會依其解析後的外掛來源遵循一般政策。請參閱 設定外掛政策 和設定參考。在 npm 安裝中使用 --pin，可將解析後的確切規格（name@version）儲存至受管理的外掛索引，同時維持預設不釘選的行為。

​
列出

​
boolean
僅顯示已啟用的外掛。
​
boolean
從表格檢視切換為逐一顯示外掛詳細資料的行，其中包含格式／來源／出處／版本／啟用中繼資料。
​
boolean
機器可讀的清單，以及登錄診斷資訊和套件相依項目安裝狀態。
plugins list 會先讀取持久保存的本機外掛登錄；若登錄遺失或無效，則使用僅依資訊清單衍生的備援。它適合用來檢查外掛是否已安裝、已啟用，以及是否可供冷啟動規劃發現，但無法即時探查已在執行中的閘道處理程序。變更外掛程式碼、啟用狀態、掛鉤政策或 plugins.load.paths 後，必須重新啟動提供該頻道服務的閘道，新的 register(api) 程式碼或掛鉤才會執行。若為遠端／容器部署，請確認重新啟動的是實際的 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 映像檔中處理隨附外掛，請將外掛 原始碼目錄繫結掛載至相符的封裝原始碼路徑上，例如 /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，將舊版設定記錄匯入索引並移除已淘汰的鍵，再進行一般執行階段作業。

​
解除安裝

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 的已棄用別名，仍受支援。

​
更新

更新適用於受管理外掛索引中追蹤的外掛安裝，以及共用 SQLite 狀態中追蹤的掛鉤套件安裝。更新會重複使用使用者安裝外掛時已選擇的來源，因此不需要再次確認來源。
傳入外掛 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 套件名稱，也會解析回所追蹤的外掛記錄。若外掛原先固定於確切版本，而你想將其移回登錄的預設發行版本線，請使用此方式。
指定目標的 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 命令會輸出預期與實際雜湊，並在繼續前要求確認。非互動式更新輔助工具會採取失敗關閉，除非呼叫端提供明確的繼續政策。
為維持相容性，plugins update 也接受 --dangerously-force-unsafe-install，但它已棄用，且不再變更外掛更新行為。操作人員的 security.installPolicy 仍可阻擋更新；外掛 before_install 掛鉤只會套用於已載入外掛掛鉤的處理程序。
由社群 ClawHub 支援的外掛在更新時，會於下載替換套件前執行與安裝相同的確切發行版本信任檢查。若已審查的自動化作業應在所選 ClawHub 發行版本出現高風險信任警告時繼續，請使用 --acknowledge-clawhub-risk。官方 ClawHub 套件與隨附的 OpenClaw 外掛來源會略過此發行版本信任提示。

​
檢查

依預設，檢查功能不會匯入外掛執行階段，但會顯示識別資訊、載入狀態、來源、資訊清單功能、政策旗標、診斷資訊、安裝中繼資料、套件功能，以及偵測到的任何 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 驗證。 每個外掛會依其在執行階段實際登錄的內容分類： 如需進一步瞭解功能模型，請參閱外掛形態。
--json 旗標會輸出適合指令碼與稽核使用的機器可讀報告。inspect --all 會呈現涵蓋整個機群的表格，其中包含形態、功能種類、相容性通知、套件功能和掛鉤摘要欄。info 是 inspect 的別名。

​
修復

doctor 會回報外掛載入錯誤、資訊清單／探索診斷、相容性通知，以及過時的外掛設定參照，例如缺少外掛插槽。當安裝樹狀結構與外掛設定都沒有問題時，會輸出 No plugin issues detected.。如果仍有過時設定，但安裝樹狀結構在其他方面皆正常，摘要會如實說明，而不會暗示外掛完全正常。 如果已設定的外掛存在於磁碟上，但遭載入器的路徑安全檢查封鎖，設定驗證會保留該外掛項目，並將其回報為 present but blocked。請修正前述的外掛封鎖診斷，例如路徑擁有權或所有使用者皆可寫入的權限，而不要移除 plugins.entries.<id> 或 plugins.allow 設定。 若發生模組形態失敗，例如缺少 register/activate 匯出，請使用 OPENCLAW_PLUGIN_LOAD_DEBUG=1 重新執行，以在診斷輸出中加入精簡的匯出形態摘要。

​
登錄檔

本機外掛登錄檔是 OpenClaw 持久保存的冷讀取模型，用於記錄已安裝外掛的身分、啟用狀態、來源中繼資料及貢獻項目的擁有權。一般啟動、提供者擁有者查詢、頻道設定分類與外掛清單，都能在不匯入外掛執行階段模組的情況下讀取該登錄檔。 使用 plugins registry 檢查持久保存的登錄檔是否存在、是否為最新或已過時。使用 --refresh，根據持久保存的外掛索引、設定原則及資訊清單／套件中繼資料重建登錄檔。這是修復路徑，不是執行階段啟用路徑。 openclaw doctor --fix 也會修復登錄檔周邊由系統管理的 npm 漂移。如果受管理的外掛 npm 專案或舊版扁平受管理 npm 根目錄下，存在孤立或復原的 @openclaw/* 套件並遮蔽內建外掛，Doctor 會移除該過時套件並重建登錄檔，使啟動程序改為依據內建資訊清單進行驗證。當具權威性的安裝記錄選定某個受管理的世代，但仍殘留較舊的扁平目錄或世代目錄時，Doctor 會停用這些過時樹狀結構，待閘道重新啟動後再予以清除。Doctor 也會將主機的 openclaw 套件重新連結至宣告 peerDependencies.openclaw 的受管理 npm 外掛中，讓 openclaw/plugin-sdk/* 等套件本機執行階段匯入在更新或修復 npm 後仍可解析。

​
市集

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 金鑰。

​
相關內容