Plugin 系統
安裝、啟用與疑難排解 Plugin 的終端使用者指南。
管理 Plugin
安裝、列出、更新、解除安裝與發布的快速範例。
Plugin 套件組合
套件組合相容性模型。
Plugin manifest
Manifest 欄位與設定結構描述。
安全性
Plugin 安裝的安全性強化。
命令
OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1 執行命令。追蹤會將階段計時寫入 stderr，並保持 JSON 輸出可解析。請參閱偵錯。
在 Nix 模式 (
OPENCLAW_NIX_MODE=1) 中，Plugin 生命週期變更操作會停用。請使用此安裝的 Nix 來源，而不是 plugins install、plugins update、plugins uninstall、plugins enable 或 plugins disable；若使用 nix-openclaw，請使用以 agent 優先的快速開始。內建 Plugin 會隨 OpenClaw 一起提供。有些預設啟用（例如內建模型提供者、內建語音提供者與內建瀏覽器 Plugin）；其他則需要
plugins enable。原生 OpenClaw Plugin 必須隨附 openclaw.plugin.json，並包含內嵌 JSON Schema（configSchema，即使為空亦然）。相容套件組合則使用自己的套件組合 manifest。plugins list 會顯示 Format: openclaw 或 Format: bundle。詳細清單/資訊輸出也會顯示套件組合子類型（codex、claude 或 cursor）以及偵測到的套件組合功能。安裝
plugins search 會查詢 ClawHub 中可安裝的 Plugin 套件，並列印可直接安裝的套件名稱。它會搜尋 code-plugin 與 bundle-plugin 套件，而不是 Skills。若要搜尋 ClawHub skills，請使用 openclaw skills search。
ClawHub 是大多數 Plugin 的主要發布與探索介面。Npm 仍是受支援的備援與直接安裝路徑。OpenClaw 擁有的
@openclaw/* Plugin 套件已重新發布到 npm；請在 npmjs.com/org/openclaw 或 Plugin 清單查看目前清單。穩定版安裝使用 latest。Beta 頻道的安裝與更新會在 npm beta dist-tag 可用時優先使用該標籤，然後才退回 latest。設定 include 與無效設定修復
設定 include 與無效設定修復
如果你的
plugins 區段由單一檔案 $include 支援，plugins install/update/enable/disable/uninstall 會寫入該 include 檔案，並保持 openclaw.json 不變。Root include、include 陣列，以及帶有同層覆寫的 include 會失敗關閉，而不是攤平成一般設定。支援的形狀請參閱設定 include。如果安裝期間設定無效，plugins install 通常會失敗關閉，並告知你先執行 openclaw doctor --fix。在 Gateway 啟動與 hot reload 期間，無效的 Plugin 設定會像其他無效設定一樣失敗關閉；openclaw doctor --fix 可以隔離無效的 Plugin 項目。唯一記載的安裝期間例外，是一條狹窄的內建 Plugin 復原路徑，僅適用於明確選擇加入 openclaw.install.allowInvalidConfigRecovery 的 Plugin。--force 與重新安裝相較於更新
--force 與重新安裝相較於更新
--force 會重用現有安裝目標，並就地覆寫已安裝的 Plugin 或 hook 套件。當你有意從新的本機路徑、封存檔、ClawHub 套件或 npm artifact 重新安裝相同 id 時使用它。若是已追蹤 npm Plugin 的例行升級，建議使用 openclaw plugins update <id-or-npm-spec>。如果你對已安裝的 Plugin id 執行 plugins install，OpenClaw 會停止，並指向 plugins update <id-or-npm-spec> 進行一般升級，或在你真的想從不同來源覆寫目前安裝時，指向 plugins install <package> --force。--pin 範圍
--pin 範圍
--pin 僅適用於 npm 安裝。它不支援 git: 安裝；當你想要釘選來源時，請使用明確的 git ref，例如 git:github.com/acme/plugin@v1.2.3。它不支援 --marketplace，因為 marketplace 安裝會保留 marketplace 來源中繼資料，而不是 npm spec。--dangerously-force-unsafe-install
--dangerously-force-unsafe-install
--dangerously-force-unsafe-install 是內建危險程式碼掃描器誤判時的破例選項。即使內建掃描器回報 critical 發現，它也允許安裝繼續，但它不會略過 Plugin before_install hook 政策封鎖，也不會略過掃描失敗。此 CLI 旗標適用於 Plugin 安裝/更新流程。Gateway 支援的 skill 相依項安裝會使用對應的 dangerouslyForceUnsafeInstall 請求覆寫，而 openclaw skills install 仍是獨立的 ClawHub skill 下載/安裝流程。如果你發布到 ClawHub 的 Plugin 被 registry 掃描封鎖，請使用 ClawHub 中的發布者步驟。Hook 套件與 npm specs
Hook 套件與 npm specs
plugins install 也是安裝在 package.json 中公開 openclaw.hooks 的 hook 套件的介面。請使用 openclaw hooks 取得經篩選的 hook 可見性與逐 hook 啟用，而不是用來安裝套件。Npm specs 僅限 registry（套件名稱 + 選用的精確版本或 dist-tag）。Git/URL/file specs 與 semver 範圍會被拒絕。為了安全，即使你的 shell 有全域 npm install 設定，相依項安裝也會以專案本機方式搭配 --ignore-scripts 執行。受管理的 Plugin npm root 會繼承 OpenClaw 的套件層級 npm overrides，因此主機安全性釘選也會套用到 hoisted Plugin 相依項。當你想明確指定 npm 解析時，請使用 npm:<package>。在 launch cutover 期間，裸套件 spec 也會直接從 npm 安裝。裸 specs 與 @latest 會留在穩定軌。OpenClaw 日期戳記修正版，例如 2026.5.3-1，在此檢查中屬於穩定版本。如果 npm 將其中任一者解析為預發行版本，OpenClaw 會停止並要求你使用預發行標籤（例如 @beta/@rc）或精確的預發行版本（例如 @1.2.3-beta.4）明確選擇加入。如果裸安裝 spec 符合官方 Plugin id（例如 diffs），OpenClaw 會直接安裝目錄項目。若要安裝同名 npm 套件，請使用明確的 scoped spec（例如 @scope/diffs）。Git 儲存庫
Git 儲存庫
使用
git:<repo> 直接從 git 儲存庫安裝。支援形式包含 git:github.com/owner/repo、git:owner/repo、完整 https://、ssh://、git://、file://，以及 git@host:owner/repo.git clone URL。加入 @<ref> 或 #<ref> 可在安裝前 checkout 分支、標籤或 commit。Git 安裝會 clone 到暫存目錄，在有提供時 checkout 要求的 ref，然後使用一般 Plugin 目錄安裝器。這表示 manifest 驗證、危險程式碼掃描、套件管理器安裝工作，以及安裝記錄都會像 npm 安裝一樣運作。記錄的 git 安裝包含來源 URL/ref 與解析出的 commit，因此 openclaw plugins update 之後可以重新解析該來源。從 git 安裝後，請使用 openclaw plugins inspect <id> --runtime --json 驗證執行階段註冊，例如 gateway methods 與 CLI 命令。如果 Plugin 使用 api.registerCli 註冊 CLI root，請透過 OpenClaw root CLI 直接執行該命令，例如 openclaw demo-plugin ping。封存檔
封存檔
支援的封存檔：
.zip、.tgz、.tar.gz、.tar。原生 OpenClaw Plugin 封存檔必須在解壓後的 Plugin root 包含有效的 openclaw.plugin.json；只包含 package.json 的封存檔會在 OpenClaw 寫入安裝記錄前被拒絕。當檔案是 npm-pack tarball，且你想測試 registry 安裝所使用的同一條受管理 npm-root 安裝路徑時，請使用 npm-pack:<path.tgz>，包含 package-lock.json 驗證、hoisted 相依項掃描，以及 npm 安裝記錄。一般封存檔路徑仍會作為本機封存檔安裝到 Plugin extensions root 底下。也支援 Claude marketplace 安裝。clawhub:<package> locator：
npm: 讓僅 npm 解析變得明確：
.tgz，驗證 ClawHub 摘要標頭和成品摘要，然後透過一般封存路徑安裝。沒有 ClawPack 中繼資料的舊版 ClawHub 版本仍會透過舊式套件封存驗證路徑安裝。已記錄的安裝會保留其 ClawHub 來源中繼資料、成品種類、npm integrity、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 repo 簡寫，例如
owner/repo - GitHub repo URL，例如
https://github.com/owner/repo - git URL
- 原生 OpenClaw Plugin（
openclaw.plugin.json） - Codex 相容套件組合（
.codex-plugin/plugin.json） - Claude 相容套件組合（
.claude-plugin/plugin.json或預設的 Claude 元件版面配置） - Cursor 相容套件組合（
.cursor-plugin/plugin.json）
相容套件組合會安裝到一般 Plugin 根目錄，並參與相同的 list/info/enable/disable 流程。目前支援套件組合 Skills、Claude command-skills、Claude
settings.json 預設值、Claude .lsp.json / manifest 宣告的 lspServers 預設值、Cursor command-skills，以及相容的 Codex hook 目錄；其他偵測到的套件組合能力會顯示在診斷/info 中，但尚未接入 runtime 執行。列出
只顯示已啟用的 Plugin。
從表格檢視切換為每個 Plugin 的詳細行，包含 source/origin/version/activation 中繼資料。
機器可讀的清單，加上登錄診斷與套件相依項安裝狀態。
plugins list 會先讀取持久化的本機 Plugin 登錄；當登錄遺失或無效時，會退回使用僅由 manifest 衍生的備用資料。它可用來檢查 Plugin 是否已安裝、已啟用，並且對冷啟動規劃可見，但它不是對已在執行中的 Gateway 程序進行即時 runtime 探測。變更 Plugin 程式碼、啟用狀態、hook 政策或 plugins.load.paths 後，請重新啟動服務該 channel 的 Gateway，才會預期新的 register(api) 程式碼或 hook 會執行。對於遠端/container 部署，請確認你重新啟動的是實際的 openclaw gateway run 子程序，而不只是包裝程序。plugins list --json 會包含每個 Plugin 來自 package.json
dependencies 和 optionalDependencies 的 dependencyStatus。OpenClaw 會檢查這些套件
名稱是否存在於該 Plugin 一般 Node node_modules 查找路徑中；它
不會匯入 Plugin runtime 程式碼、執行套件管理器，或修復遺失的
相依項。plugins search 是遠端 ClawHub catalog 查詢。它不會檢查本機
狀態、變更 config、安裝套件，或載入 Plugin runtime 程式碼。搜尋
結果會包含 ClawHub 套件名稱、family、channel、version、summary，以及
安裝提示，例如 openclaw plugins install clawhub:<package>。
若要在封裝好的 Docker 映像中處理內建 Plugin，請將 Plugin
來源目錄 bind-mount 到相符的封裝來源路徑上，例如
/app/extensions/synology-chat。OpenClaw 會先於 /app/dist/extensions/synology-chat 探索該掛載的來源
覆蓋；單純複製的來源
目錄會保持無作用，因此一般封裝安裝仍會使用已編譯的 dist。
對於 runtime hook 偵錯：
openclaw plugins inspect <id> --runtime --json會顯示來自模組載入檢查流程的已註冊 hook 和診斷。Runtime 檢查絕不會安裝相依項；使用openclaw doctor --fix清理舊式相依項狀態，或復原 config 中引用的遺失可下載 Plugin。openclaw gateway status --deep --require-rpc會確認可連線的 Gateway、服務/程序提示、config 路徑，以及 RPC 健康狀態。- 非內建 conversation hook（
llm_input、llm_output、before_model_resolve、before_agent_reply、before_agent_run、before_agent_finalize、agent_end）需要plugins.entries.<id>.hooks.allowConversationAccess=true。
--link 以避免複製本機目錄（會新增到 plugins.load.paths）：
--force 不支援搭配 --link，因為連結式安裝會重用來源路徑，而不是覆寫受管理的安裝目標。在 npm 安裝上使用 --pin，可在受管理的 Plugin index 中儲存解析後的精確規格（name@version），同時保持預設行為為不固定版本。Plugin index
Plugin 安裝中繼資料是由機器管理的狀態，不是使用者 config。安裝和更新會將它寫入有效 OpenClaw state 目錄下的plugins/installs.json。其頂層 installRecords map 是安裝中繼資料的持久來源，包含損壞或遺失 Plugin manifest 的記錄。plugins array 是由 manifest 衍生的冷登錄快取。此檔案包含請勿編輯警告，並供 openclaw plugins update、uninstall、診斷，以及冷 Plugin 登錄使用。
當 OpenClaw 在 config 中看到已隨附的舊式 plugins.installs 記錄時，runtime 讀取會將它們視為相容性輸入，而不會重寫 openclaw.json。明確的 Plugin 寫入和 openclaw doctor --fix 會在允許 config 寫入時，將這些記錄移入 Plugin index 並移除 config key；如果任一寫入失敗，config 記錄會被保留，避免安裝中繼資料遺失。
解除安裝
uninstall 會從 plugins.entries、持久化 Plugin index、Plugin allow/deny list 項目，以及適用時的已連結 plugins.load.paths 項目中移除 Plugin 記錄。除非設定了 --keep-files，uninstall 也會移除受追蹤的受管理安裝目錄，前提是該目錄位於 OpenClaw 的 Plugin extensions 根目錄內。對於 Active Memory Plugin，memory slot 會重設為 memory-core。
--keep-config 支援作為 --keep-files 的已棄用別名。更新
hooks.internal.installs 中受追蹤的 hook-pack 安裝。
解析 Plugin id 與 npm spec
解析 Plugin id 與 npm spec
當你傳入 Plugin id 時，OpenClaw 會重用該 Plugin 的已記錄安裝規格。這表示先前儲存的 dist-tag（例如
@beta）和精確固定版本，會在之後的 update <id> 執行中繼續使用。對於 npm 安裝，你也可以傳入帶有 dist-tag 或精確版本的明確 npm 套件規格。OpenClaw 會將該套件名稱解析回受追蹤的 Plugin 記錄，更新該已安裝的 Plugin，並記錄新的 npm 規格以供未來基於 id 的更新使用。傳入不含版本或標籤的 npm 套件名稱，也會解析回受追蹤的 Plugin 記錄。當 Plugin 固定到精確版本，而你想把它移回登錄的預設發行線時，請使用這種方式。Beta channel 更新
Beta channel 更新
openclaw plugins update 會重用受追蹤的 Plugin 規格，除非你傳入新的規格。openclaw update 另外知道有效的 OpenClaw 更新 channel：在 beta channel 上，預設線的 npm 和 ClawHub Plugin 記錄會先嘗試 @beta，如果沒有 Plugin beta 發行，則退回已記錄的 default/latest 規格。該退回會以警告回報，且不會使 core 更新失敗。精確版本和明確標籤會維持固定在該選擇器。版本檢查與完整性漂移
版本檢查與完整性漂移
在即時 npm 更新前，OpenClaw 會對照 npm registry 中繼資料檢查已安裝的套件版本。如果已安裝版本和已記錄的成品身分已經符合解析出的目標，更新會略過，不會下載、重新安裝或重寫
openclaw.json。當存在已儲存的 integrity hash 且擷取到的成品 hash 發生變化時，OpenClaw 會將其視為 npm 成品漂移。互動式 openclaw plugins update 命令會列印預期和實際 hash，並在繼續前要求確認。非互動式更新 helper 會預設關閉失敗，除非呼叫端提供明確的繼續政策。更新時使用 --dangerously-force-unsafe-install
更新時使用 --dangerously-force-unsafe-install
--dangerously-force-unsafe-install 也可在 plugins update 上使用，作為 Plugin 更新期間內建危險程式碼掃描誤判的緊急覆寫。它仍不會略過 Plugin before_install 政策封鎖或掃描失敗封鎖，而且只適用於 Plugin 更新，不適用於 hook-pack 更新。檢查
--runtime 以載入 Plugin 模組，並包含已註冊的 hook、tool、command、service、gateway method 和 HTTP route。Runtime 檢查會直接回報遺失的 Plugin 相依項；安裝和修復仍位於 openclaw plugins install、openclaw plugins update 和 openclaw doctor --fix。
Plugin 擁有的 CLI command 通常會安裝為根層級 openclaw command group，但 Plugin 也可能在 core parent 下註冊巢狀 command，例如 openclaw nodes。在 inspect --runtime 顯示 cliCommands 下的 command 後，請在列出的路徑執行它；例如，註冊 demo-git 的 Plugin 可以用 openclaw demo-git ping 驗證。
每個 Plugin 會依照它在 runtime 實際註冊的內容分類：
- plain-capability — 一種能力類型（例如，僅提供提供者的 Plugin）
- hybrid-capability — 多種能力類型（例如，文字 + 語音 + 圖片）
- hook-only — 只有 hook，沒有能力或介面
- non-capability — 工具/命令/服務，但沒有能力
--json 旗標會輸出適合用於指令碼和稽核的機器可讀報告。inspect --all 會呈現涵蓋整個機群的表格，包含形態、能力種類、相容性通知、套件能力，以及 hook 摘要欄位。info 是 inspect 的別名。診斷
doctor 會回報 Plugin 載入錯誤、manifest/探索診斷，以及相容性通知。當一切正常時，會印出 No plugin issues detected.
如果已設定的 Plugin 存在於磁碟上，但遭載入器的路徑安全檢查阻擋，設定驗證會保留該 Plugin 項目，並將其回報為 present but blocked。請修正前面的遭阻擋 Plugin 診斷，例如路徑擁有權或全域可寫權限，而不是移除 plugins.entries.<id> 或 plugins.allow 設定。
針對模組形態失敗，例如缺少 register/activate 匯出，請使用 OPENCLAW_PLUGIN_LOAD_DEBUG=1 重新執行，以在診斷輸出中包含精簡的匯出形態摘要。
登錄檔
plugins registry 檢查持久化登錄檔是否存在、是否為目前版本或是否過期。使用 --refresh 從持久化的 Plugin 索引、設定政策，以及 manifest/package 中繼資料重建它。這是修復路徑，不是 runtime 啟用路徑。
openclaw doctor --fix 也會修復與登錄檔相鄰的受管理 npm 漂移：如果受管理 Plugin npm 根目錄下的孤立或復原 @openclaw/* package 遮蔽了內建 Plugin，doctor 會移除該過期 package 並重建登錄檔，讓啟動能依照內建 manifest 驗證。Doctor 也會將主機 openclaw package 重新連結到宣告 peerDependencies.openclaw 的受管理 npm Plugin 中，因此更新或 npm 修復後，package 本機 runtime 匯入（例如 openclaw/plugin-sdk/*）仍可解析。
市集
marketplace.json 路徑、像 owner/repo 這樣的 GitHub 簡寫、GitHub repo URL，或 git URL。--json 會印出已解析的來源標籤，以及已剖析的 marketplace manifest 和 Plugin 項目。