25 KiB
| read_when | sidebarTitle | summary | title | x-i18n | ||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Plugins | `openclaw plugins` 的 CLI 參考（列出、安裝、市集、解除安裝、啟用/停用、診斷） | Plugin |
|
管理 Gateway Plugin、hook 套件包與相容套件組。
安裝、啟用與疑難排解 Plugin 的終端使用者指南。 安裝、列出、更新、解除安裝與發布的快速範例。 套件組相容性模型。 資訊清單欄位與設定結構描述。 Plugin 安裝的安全強化。命令
openclaw plugins list
openclaw plugins list --enabled
openclaw plugins list --verbose
openclaw plugins list --json
openclaw plugins search <query>
openclaw plugins search <query> --limit 20
openclaw plugins search <query> --json
openclaw plugins install <path-or-spec>
openclaw plugins inspect <id>
openclaw plugins inspect <id> --runtime
openclaw plugins inspect <id> --json
openclaw plugins inspect --all
openclaw plugins info <id>
openclaw plugins enable <id>
openclaw plugins disable <id>
openclaw plugins registry
openclaw plugins registry --refresh
openclaw plugins uninstall <id>
openclaw plugins doctor
openclaw plugins update <id-or-npm-spec>
openclaw plugins update --all
openclaw plugins marketplace list <marketplace>
openclaw plugins marketplace list <marketplace> --json
若要調查緩慢的安裝、檢查、解除安裝或登錄重新整理，請搭配 OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1 執行命令。追蹤會將階段計時寫入 stderr，並讓 JSON 輸出保持可解析。請參閱偵錯。
原生 OpenClaw Plugin 必須提供 openclaw.plugin.json，並包含內嵌 JSON Schema（configSchema，即使是空的也一樣）。相容套件組則改用自己的套件組資訊清單。
plugins list 會顯示 Format: openclaw 或 Format: bundle。詳細列出/資訊輸出也會顯示套件組子類型（codex、claude 或 cursor）以及偵測到的套件組功能。
安裝
openclaw plugins search "calendar" # search ClawHub plugins
openclaw plugins install <package> # npm by default
openclaw plugins install clawhub:<package> # ClawHub only
openclaw plugins install npm:<package> # npm only
openclaw plugins install git:github.com/<owner>/<repo> # git repo
openclaw plugins install git:github.com/<owner>/<repo>@<ref>
openclaw plugins install <package> --force # overwrite existing install
openclaw plugins install <package> --pin # pin version
openclaw plugins install <package> --dangerously-force-unsafe-install
openclaw plugins install <path> # local path
openclaw plugins install <plugin>@<marketplace> # marketplace
openclaw plugins install <plugin> --marketplace <name> # marketplace (explicit)
openclaw plugins install <plugin> --marketplace https://github.com/<owner>/<repo>
plugins search 會查詢 ClawHub 中可安裝的 Plugin 套件，並印出可直接安裝的套件名稱。它會搜尋 code-plugin 與 bundle-plugin 套件，而不是 Skills。若要搜尋 ClawHub Skills，請使用 openclaw skills search。
如果安裝期間設定無效，`plugins install` 通常會封閉失敗，並告訴你先執行 `openclaw doctor --fix`。在 Gateway 啟動與熱重新載入期間，無效的 Plugin 設定會像任何其他無效設定一樣封閉失敗；`openclaw doctor --fix` 可以隔離無效的 Plugin 項目。唯一記載的安裝時例外，是針對明確選擇加入 `openclaw.install.allowInvalidConfigRecovery` 的 Plugin 所提供的狹窄隨附 Plugin 復原路徑。
如果你對已安裝的 Plugin id 執行 `plugins install`，OpenClaw 會停止並指引你使用 `plugins update <id-or-npm-spec>` 進行一般升級，或在你確實想從不同來源覆寫目前安裝時，使用 `plugins install <package> --force`。
此 CLI 旗標適用於 Plugin 安裝/更新流程。由 Gateway 支援的 skill 相依性安裝會使用對應的 `dangerouslyForceUnsafeInstall` 請求覆寫，而 `openclaw skills install` 仍是獨立的 ClawHub skill 下載/安裝流程。
如果你發布在 ClawHub 的 Plugin 被登錄掃描阻擋，請使用 [ClawHub](/zh-TW/tools/clawhub) 中的發布者步驟。
npm 規格是**僅限登錄**（套件名稱 + 選用的**精確版本**或 **dist-tag**）。Git/URL/file 規格與 semver 範圍會被拒絕。為了安全，即使你的 shell 有全域 npm 安裝設定，相依性安裝也會以專案本機方式搭配 `--ignore-scripts` 執行。
當你想明確使用 npm 解析時，請使用 `npm:<package>`。在啟動切換期間，裸套件規格也會直接從 npm 安裝。
裸規格與 `@latest` 會保持在穩定軌道。OpenClaw 日期戳記修正版（例如 `2026.5.3-1`）在此檢查中屬於穩定版本。如果 npm 將其中任一解析為預發行版本，OpenClaw 會停止並要求你以預發行標籤（例如 `@beta`/`@rc`）或精確預發行版本（例如 `@1.2.3-beta.4`）明確選擇加入。
如果裸安裝規格符合官方 Plugin id（例如 `diffs`），OpenClaw 會直接安裝目錄項目。若要安裝同名 npm 套件，請使用明確的 scoped 規格（例如 `@scope/diffs`）。
Git 安裝會 clone 到暫存目錄，在有要求的 ref 時將其取出，然後使用一般 Plugin 目錄安裝器。這表示資訊清單驗證、危險程式碼掃描、套件管理器安裝工作與安裝記錄的行為會像 npm 安裝一樣。已記錄的 git 安裝會包含來源 URL/ref 以及已解析的 commit，讓 `openclaw plugins update` 之後可以重新解析來源。
從 git 安裝後，請使用 `openclaw plugins inspect <id> --runtime --json` 驗證執行階段註冊，例如 gateway 方法與 CLI 命令。如果 Plugin 使用 `api.registerCli` 註冊了 CLI 根命令，請透過 OpenClaw 根 CLI 直接執行該命令，例如 `openclaw demo-plugin ping`。
也支援 Claude marketplace 安裝。
ClawHub 安裝會使用明確的 clawhub:<package> 定位器：
openclaw plugins install clawhub:openclaw-codex-app-server
openclaw plugins install clawhub:openclaw-codex-app-server@1.2.3
在啟動切換期間，裸 npm 安全 Plugin 規格預設會從 npm 安裝：
openclaw plugins install openclaw-codex-app-server
使用 npm: 可明確指定僅使用 npm 解析：
openclaw plugins install npm:openclaw-codex-app-server
openclaw plugins install npm:@scope/plugin-name@1.0.1
OpenClaw 會在安裝前檢查公告的 Plugin API / 最低 gateway 相容性。當選取的 ClawHub 版本發布 ClawPack 成品時，OpenClaw 會下載版本化 npm-pack .tgz，驗證 ClawHub digest 標頭與成品 digest，然後透過一般封存路徑安裝。沒有 ClawPack 中繼資料的較舊 ClawHub 版本仍會透過舊版套件封存驗證路徑安裝。已記錄的安裝會保留其 ClawHub 來源中繼資料、成品種類、npm integrity、npm shasum、tarball 名稱，以及 ClawPack digest 事實，以供之後更新。
未指定版本的 ClawHub 安裝會保留未指定版本的記錄規格，讓 openclaw plugins update 可以跟隨較新的 ClawHub 發行；明確版本或標籤選擇器（例如 clawhub:pkg@1.2.3 和 clawhub:pkg@beta）則會保持釘選到該選擇器。
Marketplace 簡寫
當 marketplace 名稱存在於 Claude 位於 ~/.claude/plugins/known_marketplaces.json 的本機登錄快取中時，請使用 plugin@marketplace 簡寫：
openclaw plugins marketplace list <marketplace-name>
openclaw plugins install <plugin-name>@<marketplace-name>
當你想明確傳入 marketplace 來源時，請使用 --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 plugins（
openclaw.plugin.json） - Codex 相容套件組合（
.codex-plugin/plugin.json） - Claude 相容套件組合（
.claude-plugin/plugin.json或預設 Claude 元件版面配置） - Cursor 相容套件組合（
.cursor-plugin/plugin.json）
列出
openclaw plugins list
openclaw plugins list --enabled
openclaw plugins list --verbose
openclaw plugins list --json
openclaw plugins search <query>
openclaw plugins search <query> --limit 20
openclaw plugins search <query> --json
plugins list --json 會包含每個 Plugin 來自 package.json
dependencies 和 optionalDependencies 的 dependencyStatus。OpenClaw 會檢查這些套件
名稱是否存在於該 Plugin 一般 Node node_modules 查找路徑上；它
不會匯入 Plugin runtime 程式碼、執行套件管理器，或修復缺失的
相依套件。
plugins search 是遠端 ClawHub 目錄查詢。它不會檢查本機
狀態、變更 config、安裝套件，或載入 Plugin runtime 程式碼。搜尋
結果包含 ClawHub 套件名稱、family、channel、版本、摘要，以及
安裝提示，例如 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會顯示來自模組載入檢查流程的已註冊 hooks 與診斷。Runtime 檢查永遠不會安裝相依套件；請使用openclaw doctor --fix清理舊版相依狀態，或安裝缺失且已設定的可下載 plugins。openclaw gateway status --deep --require-rpc會確認可連線的 Gateway、服務/程序提示、config 路徑，以及 RPC 健康狀態。- 非內建的對話 hooks（
llm_input、llm_output、before_agent_finalize、agent_end）需要plugins.entries.<id>.hooks.allowConversationAccess=true。
使用 --link 可避免複製本機目錄（會加入 plugins.load.paths）：
openclaw plugins install -l ./my-plugin
在 npm 安裝上使用 --pin，可將解析出的精確 spec（name@version）儲存在受管理的 Plugin 索引中，同時保留預設的未釘選行為。
Plugin 索引
Plugin 安裝中繼資料是由機器管理的狀態，不是使用者 config。安裝與更新會將它寫入作用中 OpenClaw 狀態目錄底下的 plugins/installs.json。其頂層 installRecords map 是安裝中繼資料的持久來源，其中包含毀損或缺失 Plugin manifest 的記錄。plugins 陣列是由 manifest 推導出的冷 registry 快取。該檔案包含請勿編輯警告，並由 openclaw plugins update、解除安裝、診斷，以及冷 Plugin registry 使用。
當 OpenClaw 在 config 中看到已出貨的舊版 plugins.installs 記錄時，會將它們移到 Plugin 索引並移除該 config key；如果任一寫入失敗，config 記錄會被保留，確保安裝中繼資料不會遺失。
解除安裝
openclaw plugins uninstall <id>
openclaw plugins uninstall <id> --dry-run
openclaw plugins uninstall <id> --keep-files
uninstall 會從 plugins.entries、持久化 Plugin 索引、Plugin 允許/拒絕清單項目，以及適用時已連結的 plugins.load.paths 項目中移除 Plugin 記錄。除非設定 --keep-files，解除安裝也會在追蹤的受管理安裝目錄位於 OpenClaw 的 Plugin extensions 根目錄內時移除該目錄。對於 Active Memory plugins，memory slot 會重設為 memory-core。
更新
openclaw plugins update <id-or-npm-spec>
openclaw plugins update --all
openclaw plugins update <id-or-npm-spec> --dry-run
openclaw plugins update @openclaw/voice-call
openclaw plugins update openclaw-codex-app-server --dangerously-force-unsafe-install
更新會套用到受管理 Plugin 索引中已追蹤的 Plugin 安裝，以及 hooks.internal.installs 中已追蹤的 hook-pack 安裝。
對於 npm 安裝，你也可以傳入含有 dist-tag 或精確版本的明確 npm 套件 spec。OpenClaw 會將該套件名稱解析回已追蹤的 Plugin 記錄、更新該已安裝 Plugin，並記錄新的 npm spec，供未來以 id 為基礎的更新使用。
傳入不含版本或 tag 的 npm 套件名稱，也會解析回已追蹤的 Plugin 記錄。當某個 Plugin 先前已釘選到精確版本，而你想將它移回 registry 的預設發行線時，請使用這個方式。
當已儲存 integrity hash，且抓取到的成品 hash 發生變化時，OpenClaw 會將其視為 npm 成品漂移。互動式 `openclaw plugins update` 命令會列印預期與實際 hash，並在繼續前要求確認。非互動式更新輔助程式會 fail closed，除非呼叫端提供明確的繼續政策。
檢查
openclaw plugins inspect <id>
openclaw plugins inspect <id> --runtime
openclaw plugins inspect <id> --json
Inspect 預設不會匯入 Plugin runtime，會顯示身分、載入狀態、來源、manifest 功能、政策旗標、診斷、安裝中繼資料、套件組合功能，以及任何偵測到的 MCP 或 LSP server 支援。加入 --runtime 可載入 Plugin 模組，並包含已註冊 hooks、tools、commands、services、gateway methods，以及 HTTP routes。Runtime 檢查會直接回報缺失的 Plugin 相依套件；安裝與修復仍留在 openclaw plugins install、openclaw plugins update，以及 openclaw doctor --fix 中進行。
Plugin 擁有的 CLI commands 會安裝為根層級 openclaw command groups。當 inspect --runtime 在 cliCommands 下顯示某個 command 後，請以 openclaw <command> ... 執行它；例如，註冊 demo-git 的 Plugin 可用 openclaw demo-git ping 驗證。
每個 Plugin 會依照它在 runtime 實際註冊的內容分類：
- plain-capability — 一種 capability 類型（例如僅 provider 的 Plugin）
- hybrid-capability — 多種 capability 類型（例如文字 + 語音 + 圖像）
- hook-only — 只有 hooks，沒有 capabilities 或 surfaces
- non-capability — tools/commands/services，但沒有 capabilities
如需 capability model 的更多資訊，請參閱 Plugin shapes。
`--json` 旗標會輸出適合 scripting 與 auditing 的機器可讀報告。`inspect --all` 會呈現全體範圍的表格，包含 shape、capability kinds、compatibility notices、bundle capabilities，以及 hook summary 欄位。`info` 是 `inspect` 的別名。Doctor
openclaw plugins doctor
doctor 會回報 Plugin 載入錯誤、manifest/discovery 診斷，以及相容性 notices。當一切正常時，它會印出 No plugin issues detected.
如果已設定的 Plugin 存在於磁碟上，但被 loader 的路徑安全檢查封鎖，config 驗證會保留該 Plugin 項目，並將它回報為 present but blocked。請修正前面的 blocked-plugin 診斷，例如路徑 ownership 或 world-writable permissions，而不是移除 plugins.entries.<id> 或 plugins.allow config。
對於缺少 register/activate exports 這類 module-shape 失敗，請使用 OPENCLAW_PLUGIN_LOAD_DEBUG=1 重新執行，以在診斷輸出中包含精簡的 export-shape 摘要。
Registry
openclaw plugins registry
openclaw plugins registry --refresh
openclaw plugins registry --json
本機 Plugin registry 是 OpenClaw 為已安裝 Plugin 身分、啟用狀態、來源中繼資料，以及貢獻 ownership 所持久化的冷讀取模型。一般啟動、provider owner 查找、channel setup 分類，以及 Plugin 清單都可以在不匯入 Plugin runtime 模組的情況下讀取它。
使用 plugins registry 檢查持久化 registry 是否存在、為最新或已過期。使用 --refresh 從持久化 Plugin 索引、設定政策，以及資訊清單/套件中繼資料重建它。這是修復路徑，不是執行階段啟用路徑。
openclaw doctor --fix 也會修復與 registry 相鄰的受管理 npm 漂移：如果受管理 Plugin npm 根目錄下有孤立或復原的 @openclaw/* 套件遮蔽了隨附 Plugin，doctor 會移除該過期套件並重建 registry，讓啟動流程能依據隨附資訊清單進行驗證。
市集
openclaw plugins marketplace list <source>
openclaw plugins marketplace list <source> --json
市集清單接受本機市集路徑、marketplace.json 路徑、像 owner/repo 這樣的 GitHub 簡寫、GitHub repo URL，或 git URL。--json 會印出解析後的來源標籤，以及剖析後的市集資訊清單與 Plugin 項目。