OpenClaw 外掛管理指南：安裝、更新與設定指令詳解

每次在設定開發環境時，最頭痛的就是管理各種外掛和擴充套件。你可能遇過版本對不起來，或是根本搞不清楚現在到底裝了哪些東西，這些瑣碎的管理工作總是打斷你的開發節奏。

openclaw plugins 就是為了幫你解決這些煩惱而生的。它讓你能夠輕鬆管理 Gateway 的 plugins、extensions、hook packs 以及相容的 bundles，讓你的開發流程保持順暢。

相關資源：

• Plugin 系統：Plugins
• Bundle 相容性：Plugin bundles
• Plugin manifest 與 schema：Plugin manifest
• 安全強化：Security

指令

openclaw plugins list
openclaw plugins install <path-or-spec>
openclaw plugins inspect <id>
openclaw plugins enable <id>
openclaw plugins disable <id>
openclaw plugins uninstall <id>
openclaw plugins doctor
openclaw plugins update <id>
openclaw plugins update --all
openclaw plugins marketplace list <marketplace>

內建的 plugins 會隨 OpenClaw 一起提供，但預設是停用的。你可以使用 plugins enable 來啟用它們。

原生 OpenClaw plugins 必須提供包含內嵌 JSON Schema 的 openclaw.plugin.json（即使 configSchema 是空的也一樣）。相容的 bundles 則使用它們自己的 bundle manifests。

plugins list 會顯示 Format: openclaw 或 Format: bundle。如果你使用 verbose 模式查看列表或資訊，還會顯示 bundle 的子類型（例如 codex, claude, 或 cursor）以及偵測到的 bundle 功能。

安裝

openclaw plugins install <package>                      # ClawHub first, then npm
openclaw plugins install clawhub:<package>              # ClawHub only
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)

單純的 package 名稱會先檢查 ClawHub，接著才是 npm。安全提示：請把安裝 plugin 當作在執行程式碼一樣謹慎，建議優先使用 pinned versions。

--dangerously-force-unsafe-install 是一個緊急選項，用於處理內建危險程式碼掃描器的誤判。它允許你在掃描器回報 critical 結果時繼續安裝，但它不會繞過 plugin 的 before_install hook 策略阻擋，也不會繞過掃描失敗的情況。

這個 CLI flag 適用於 openclaw plugins install。由 Gateway 支援的 skill 依賴安裝會使用對應的 dangerouslyForceUnsafeInstall 請求覆寫，而 openclaw skills install 則維持獨立的 ClawHub skill 下載與安裝流程。

plugins install 同時也是安裝在 package.json 中宣告 openclaw.hooks 的 hook packs 的入口。如果你需要過濾 hook 可見性或針對個別 hook 進行啟用，請使用 openclaw hooks，而不是用它來安裝 package。

Npm specs 僅限 registry-only（package 名稱加上選用的 exact version 或 dist-tag）。我們不支援 Git、URL、檔案路徑或 semver 範圍。為了安全起見，依賴安裝執行時會加上 --ignore-scripts。

單純的 specs 或 @latest 會保持在穩定版本。如果 npm 將這些解析為 prerelease 版本，OpenClaw 會停止執行並要求你明確選擇，例如使用 @beta、@rc 等標籤，或是像 @1.2.3-beta.4 這樣的精確 prerelease 版本。

如果安裝名稱剛好符合內建的 plugin id（例如 diffs），OpenClaw 會直接安裝該內建 plugin。如果你想安裝同名的 npm package，請使用明確的 scoped spec（例如 @scope/diffs）。

支援的壓縮檔格式包括：.zip, .tgz, .tar.gz, .tar。

我們也支援 Claude marketplace 的安裝方式。

ClawHub 安裝使用明確的 clawhub:<package> 定位符：

openclaw plugins install clawhub:openclaw-codex-app-server
openclaw plugins install clawhub:openclaw-codex-app-server@1.2.3

現在 OpenClaw 對於一般的 npm-safe plugin specs 也會優先選擇 ClawHub。只有在 ClawHub 沒有該 package 或版本時，才會退回到 npm：

openclaw plugins install openclaw-codex-app-server

OpenClaw 會從 ClawHub 下載 package 壓縮檔，檢查宣告的 plugin API 與最低 gateway 相容性，然後透過正常的壓縮檔路徑進行安裝。記錄下來的安裝資訊會保留 ClawHub 來源元數據，以便日後更新。

當 marketplace 名稱存在於 Claude 本地 registry 快取（位於 ~/.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 ./my-marketplace

Marketplace 來源可以是：

• ~/.claude/plugins/known_marketplaces.json 中的 Claude 已知 marketplace 名稱
• 本地 marketplace 根目錄或 marketplace.json 路徑
• GitHub 儲存庫簡寫，例如 owner/repo
• 一個 git URL

對於從 GitHub 或 git 載入的遠端 marketplaces，plugin 項目必須留在複製下來的 marketplace 儲存庫內。OpenClaw 接受該儲存庫的相對路徑來源，但會拒絕遠端 manifest 中的外部 git、GitHub、URL/壓縮檔以及絕對路徑的 plugin 來源。

對於本地路徑和壓縮檔，OpenClaw 會自動偵測：

• 原生 OpenClaw plugins (openclaw.plugin.json)
• Codex 相容 bundles (.codex-plugin/plugin.json)
• Claude 相容 bundles (.claude-plugin/plugin.json 或預設的 Claude 元件佈局)
• Cursor 相容 bundles (.cursor-plugin/plugin.json)

相容的 bundles 會安裝到正常的 extensions 根目錄，並參與相同的 list/info/enable/disable 流程。目前支援 bundle skills、Claude command-skills、Claude settings.json 預設值、Cursor command-skills 以及相容的 Codex hook 目錄；其他偵測到的 bundle 功能會顯示在診斷資訊中，但尚未整合到執行時期。

使用 --link 可以避免複製本地目錄（這會將其加入 plugins.load.paths）：

openclaw plugins install -l ./my-plugin

在 npm 安裝時使用 --pin 可以將解析出的精確 spec (name@version) 儲存在 plugins.installs 中，同時保持預設行為不固定版本。

卸載

openclaw plugins uninstall <id>
openclaw plugins uninstall <id> --dry-run
openclaw plugins uninstall <id> --keep-files

uninstall 會從 plugins.entries、plugins.installs、plugin 白名單以及相關的 plugins.load.paths 條目中移除 plugin 紀錄。對於啟用的 memory plugins，memory slot 會重設為 memory-core。

預設情況下，卸載也會移除活動狀態目錄下 plugin 根目錄中的安裝目錄。如果你想保留磁碟上的檔案，請使用 --keep-files。

我們支援 --keep-config 作為 --keep-files 的過時別名。

更新

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@beta

更新適用於 plugins.installs 中追蹤的安裝項目，以及 hooks.internal.installs 中追蹤的 hook-pack 安裝。

當你傳遞 plugin id 時，OpenClaw 會重複使用該 plugin 記錄的安裝 spec。這代表之前儲存的 dist-tags（如 @beta）和精確的 pinned versions 在之後執行 update <id> 時會繼續被使用。

對於 npm 安裝，你也可以傳遞帶有 dist-tag 或精確版本的明確 npm package spec。OpenClaw 會將該 package 名稱解析回追蹤的 plugin 紀錄，更新該已安裝的 plugin，並記錄新的 npm spec 以供日後基於 id 的更新使用。

當存在儲存的 integrity hash 且抓取到的 artifact hash 發生變化時，OpenClaw 會印出警告並在繼續之前要求確認。在 CI 或非互動式環境中，請使用全域的 --yes 來跳過提示。

檢查

openclaw plugins inspect <id>
openclaw plugins inspect <id> --json

對單一 plugin 進行深度檢查。顯示身份、載入狀態、來源、註冊的功能、hooks、tools、commands、services、gateway 方法、HTTP 路由、策略標記、診斷資訊以及安裝元數據。

每個 plugin 會根據其在執行時期實際註冊的內容進行分類：

• plain-capability — 單一能力類型（例如僅限 provider 的 plugin）
• hybrid-capability — 多種能力類型（例如文字 + 語音 + 圖片）
• hook-only — 僅有 hooks，沒有能力或介面
• non-capability — 有 tools/commands/services 但沒有能力

關於能力模型的更多資訊，請參考 Plugin shapes。

--json 標記會輸出適合腳本處理和審計的機器可讀報告。

info 是 inspect 的別名。

想要更快速地設定你的環境嗎？試試我們的 AI Setup Assistant。

下一步

• 深入了解 Plugin 體系結構
• 學習如何 開發你的第一個 Plugin
• 查看 安全性最佳實踐