> ## Documentation Index > Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt > Use this file to discover all available pages before exploring further. # 外掛 管理閘道外掛、鉤子套件和相容套件組合。 安裝、啟用和疑難排解外掛的使用者指南。 安裝、列出、更新、解除安裝和發布的快速範例。 套件組合相容性模型。 資訊清單欄位和設定結構描述。 外掛安裝的安全強化。 ## 命令 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw plugins list [--enabled] [--verbose] [--json] openclaw plugins search [--limit ] [--json] openclaw plugins install [--link] [--force] [--pin] [--marketplace ] openclaw plugins inspect [--runtime] [--json] openclaw plugins inspect --all [--runtime] [--json] openclaw plugins info # inspect 的別名 openclaw plugins enable openclaw plugins disable openclaw plugins uninstall [--dry-run] [--keep-files] [--force] openclaw plugins update | --all [--dry-run] openclaw plugins registry [--refresh] [--json] openclaw plugins doctor openclaw plugins init [--name ] [--type tool|provider] [--directory ] openclaw plugins build [--entry ] [--check] openclaw plugins validate [--entry ] openclaw plugins marketplace entries [--offline] [--feed-profile ] [--json] openclaw plugins marketplace list [--json] openclaw plugins marketplace refresh [--feed-profile ] [--expected-sha256 ] [--json] ``` 若要調查緩慢的安裝、檢查、解除安裝或登錄檔重新整理，請使用 `OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1` 執行命令。追蹤會將各階段的計時寫入 stderr，並讓 JSON 輸出保持可解析。請參閱[偵錯](/zh-TW/help/debugging#plugin-lifecycle-trace)。 在 Nix 模式（`OPENCLAW_NIX_MODE=1`）中，`openclaw.json` 不可變。`install`、`update`、`uninstall`、`enable` 和 `disable` 都會拒絕執行。請改為編輯此安裝的 Nix 來源（nix-openclaw 使用 `programs.openclaw.config` 或 `instances..config`），然後重新建置。請參閱以代理程式為優先的[快速入門](https://github.com/openclaw/nix-openclaw#quick-start)。 隨附外掛會與 OpenClaw 一併提供。其中一些預設為啟用（例如隨附的模型供應商、隨附的語音供應商和隨附的瀏覽器外掛）；其他則需要 `plugins enable`。 原生 OpenClaw 外掛提供包含內嵌 JSON Schema 的 `openclaw.plugin.json`（`configSchema`，即使為空亦同）。相容套件組合則改用其自身的套件組合資訊清單。 `plugins list` 會顯示 `Format: openclaw` 或 `Format: bundle`。詳細的清單／資訊輸出還會顯示套件組合子類型（`codex`、`claude` 或 `cursor`）以及偵測到的套件組合功能。 ## 編寫 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw plugins init stock-quotes --name "Stock Quotes" cd stock-quotes npm run plugin:build npm run plugin:validate ``` `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` 會檢查產生的資訊清單、套件中繼資料和 目前進入點匯出是否仍然一致。完整的編寫工作流程請參閱[工具外掛](/zh-TW/plugins/tool-plugins)。 鷹架會寫入 TypeScript 原始碼，但會從已建置的 `./dist/index.js` 進入點產生中繼資料，因此此工作流程也適用於已發布的命令列介面。當進入點並非預設套件進入點時，請使用 `--entry `。在 CI 中使用 `plugins build --check`，可在產生的中繼資料過時時使其失敗，而不會 重寫檔案。 ### 供應商鷹架 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw plugins init acme-models --name "Acme Models" --type provider cd acme-models npm install npm run build npm test npm run validate ``` 供應商鷹架會建立通用的 OpenAI 相容模型供應商外掛， 其中包含 API 金鑰驗證的配管、執行 `clawhub package validate` 的 `npm run validate` 指令碼、ClawHub 套件中繼資料，以及可手動 分派的 GitHub Actions 工作流程，供日後透過 GitHub OIDC 進行受信任的發布。供應商鷹架不會產生 Skills，也不使用 `openclaw plugins build`/`validate`；這些命令用於工具 鷹架的產生中繼資料路徑。 發布前，請將預留位置 API 基底 URL、模型目錄、文件 路由、認證資訊文字和 README 內容替換為實際的供應商詳細資料。首次發布至 ClawHub 及設定受信任發布者時，請使用 產生的 README。 ## 安裝 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw plugins search "calendar" # 搜尋 ClawHub 外掛 openclaw plugins install @openclaw/ # 受信任的官方目錄 openclaw plugins install # 任意 npm 套件 openclaw plugins install clawhub: # 僅限 ClawHub openclaw plugins install npm: # 僅限 npm openclaw plugins install npm-pack: # 本機 npm-pack tarball openclaw plugins install git:github.com// # git 儲存庫 openclaw plugins install git:github.com//@ openclaw plugins install # 本機路徑或封存檔 openclaw plugins install -l # 建立連結而非複製 openclaw plugins install @ # 市集簡寫 openclaw plugins install --marketplace # 市集（明確指定） openclaw plugins install --force # 確認來源／覆寫現有項目 openclaw plugins install --pin # 鎖定解析出的 npm 版本 openclaw plugins install clawhub: --acknowledge-clawhub-risk openclaw plugins install --dangerously-force-unsafe-install ``` 測試設定期間安裝的維護者，可以使用受保護的環境變數覆寫自動外掛安裝 來源。請參閱 [外掛安裝覆寫](/zh-TW/plugins/install-overrides)。 在啟動切換期間，單純的套件名稱預設會從 npm 安裝；但若名稱符合隨附或官方外掛 ID，OpenClaw 會改用該本機／官方副本，而不會存取 npm 登錄檔。若你刻意想使用外部 npm 套件，請改用 `npm:`。ClawHub 請使用 `clawhub:`。請將安裝外掛視同執行程式碼；應優先使用鎖定版本。 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:` 的安裝提示。 ClawHub 是多數外掛的主要散布與探索介面。Npm 仍是受支援的備援和直接安裝路徑。OpenClaw 擁有的 `@openclaw/*` 外掛套件已再次發布至 npm；請在 [npmjs.com/org/openclaw](https://www.npmjs.com/org/openclaw) 或 [外掛清單](/zh-TW/plugins/plugin-inventory)查看目前清單。穩定版安裝使用 `latest`。 當 npm `beta` dist-tag 可用時，Beta 通道的安裝和更新會優先使用該標籤， 否則退回 `latest`。在延伸穩定通道上，使用單純／預設或 `latest` 意圖的官方 npm 外掛，會解析為與已安裝核心完全相同的版本。 確切版本鎖定和明確的非 `latest` 標籤、第三方套件以及 非 npm 來源都不會被重寫。 如果你的 `plugins` 區段由單一檔案的 `$include` 支援，`plugins install/update/enable/disable/uninstall` 會直接寫入該引入檔案，並保持 `openclaw.json` 不變。根層級引入、引入陣列和包含同層覆寫的引入會採取關閉式失敗，而非攤平。支援的形狀請參閱[設定引入](/zh-TW/gateway/configuration)。 如果安裝前設定無效，`plugins install` 通常會採取關閉式失敗，並要求你先執行 `openclaw doctor --fix`。在閘道啟動和熱重新載入期間，無效的外掛設定會像其他任何無效設定一樣採取關閉式失敗；`openclaw doctor --fix` 可隔離無效的外掛項目。唯一的既有設定例外，是針對明確選擇加入 `openclaw.install.allowInvalidConfigRecovery` 的外掛所提供的狹義隨附外掛復原路徑。 當現有主機設定有效，但新安裝外掛本身的設定不存在時，OpenClaw 會將安裝記錄為已停用，而不會寫入無效的已啟用項目。請設定 `plugins.entries..config`，然後執行 `openclaw plugins enable `。如果現有外掛設定項目存在但無效，安裝會失敗且不會重寫該項目。 `--force` 會在不提示的情況下確認非 ClawHub 來源。它不會略過 `security.installPolicy` 或其餘安裝安全檢查。當外掛或鉤子套件已安裝時，它也會重複使用現有目標，並在原處覆寫。請在審查任意 npm、本機、封存檔、git 或市集來源後，或刻意重新安裝相同 ID 時使用。若要例行升級已追蹤的 npm 外掛，應優先使用 `openclaw plugins update `。 如果你針對已安裝的外掛 ID 執行 `plugins install`，OpenClaw 會停止，並引導你使用 `plugins update ` 進行一般升級；若你確實想要從不同來源覆寫目前的安裝，則改用 `plugins install --force`。任意來源仍會顯示互動式來源警告；以非互動方式安裝時，必須在審查後傳入 `--force`。受信任的 ClawHub 和 OpenClaw 目錄來源不需要此旗標。搭配 `--link` 時，`--force` 會確認來源，但不會變更連結路徑的安裝模式。 `--pin` 僅適用於 npm 安裝，並會記錄解析後的確切 `@`。它不支援搭配 `git:` 安裝（請改為在規格中釘選參照，例如 `git:github.com/acme/plugin@v1.2.3`），也不支援搭配 `--marketplace`（市集安裝會保存市集來源中繼資料，而非 npm 規格）。 `--dangerously-force-unsafe-install` 已淘汰，現在不會執行任何操作。OpenClaw 不再針對外掛安裝執行內建的安裝階段危險程式碼封鎖。 需要主機特定的安裝政策時，請使用由操作者擁有的 `security.installPolicy` 介面。外掛 `before_install` 鉤子是外掛執行階段的生命週期鉤子，並非命令列介面安裝的主要政策邊界。 如果你發佈到 ClawHub 的外掛因登錄檔掃描而遭隱藏或封鎖，請依照 [ClawHub 發佈](/zh-TW/clawhub/publishing)中的發佈者步驟操作。`--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:` 明確指定僅透過 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:` 或 `npm:@latest`），OpenClaw 會在安裝前檢查解析後的套件中繼資料。如果最新穩定套件需要較新的 OpenClaw 外掛 API 或更高的主機最低版本，OpenClaw 會檢查較舊的穩定版本，並改為安裝最新的相容版本。確切版本和明確的 dist-tag 仍採嚴格模式：選取不相容的版本會失敗，並要求你升級 OpenClaw 或選擇相容版本。 如果裸安裝規格符合官方外掛 ID（例如 `diffs`），OpenClaw 會直接安裝目錄項目。若要安裝同名的 npm 套件，請使用明確的限定範圍規格（例如 `@scope/diffs`）。 使用 `git:` 直接從 git 儲存庫安裝。支援的形式：`git:github.com/owner/repo`、`git:owner/repo`、完整的 `https://`、`ssh://`、`git://`、`file://`，以及 `git@host:owner/repo.git` 複製 URL。加入 `@` 或 `#`，即可在安裝前取出分支、標籤或提交。 Git 安裝會複製到暫存目錄，並在有指定參照時取出該參照，接著使用一般的外掛目錄安裝程式，因此資訊清單驗證、操作者安裝政策、套件管理器安裝作業和安裝記錄的行為都與 npm 安裝相同。記錄的 git 安裝會包含來源 URL／參照與解析後的提交，讓 `openclaw plugins update` 日後可以重新解析來源。 從 git 安裝後，使用 `openclaw plugins inspect --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:`， 其中包括 `package-lock.json` 驗證、提升層級的相依套件掃描， 以及 npm 安裝記錄。一般封存檔路徑仍會以本機 封存檔形式安裝至外掛 extensions 根目錄下。 也支援 Claude 市集安裝。 ClawHub 安裝使用明確的 `clawhub:` 定位器： ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw plugins install clawhub:openclaw-codex-app-server openclaw plugins install clawhub:openclaw-codex-app-server@1.2.3 ``` 在啟動切換期間，符合 npm 安全命名規則的裸外掛規格預設會從 npm 安裝，除非它們符合官方外掛 ID： ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw plugins install openclaw-codex-app-server ``` 使用 `npm:` 明確指定僅透過 npm 解析： ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw plugins install npm:openclaw-codex-app-server openclaw plugins install npm:@openclaw/discord@2026.5.20 openclaw plugins install npm:@scope/plugin-name@1.0.1 ``` 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` 簡寫： ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw plugins marketplace list openclaw plugins install @ ``` 使用 `--marketplace` 明確傳入市集來源： ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw plugins install --marketplace openclaw plugins install --marketplace openclaw plugins install --marketplace https://github.com// openclaw plugins install --marketplace ./my-marketplace ``` * 來自 `~/.claude/plugins/known_marketplaces.json` 的 Claude 已知市集名稱 * 本機市集根目錄或 `marketplace.json` 路徑 * GitHub 儲存庫簡寫，例如 `owner/repo` * GitHub 儲存庫 URL，例如 `https://github.com/owner/repo` * git URL 對於從 GitHub 或 git 載入的遠端市集，外掛項目必須位於複製的市集儲存庫內。OpenClaw 接受來自該儲存庫的相對路徑來源，並拒絕遠端資訊清單中的 HTTP(S)、絕對路徑、git、GitHub 和其他非路徑外掛來源。 對於本機路徑和封存檔，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` 或 `/.openclaw/extensions` 中而載入；這些 自動探索的根目錄會載入外掛套件或套件組目錄，並將 頂層指令碼檔案視為本機輔助程式而略過。請改為在 `plugins.load.paths` 中明確列出獨立檔案。 相容套件組會安裝到一般外掛根目錄，並參與相同的列出／資訊／啟用／停用流程。目前支援套件組 Skills、Claude 命令 Skills、Claude `settings.json` 預設值、Claude `.lsp.json`／資訊清單宣告的 `lspServers` 預設值、Cursor 命令 Skills，以及相容的 Codex 鉤子目錄；其他偵測到的套件組功能會顯示於診斷／資訊中，但尚未接入執行階段執行。 使用 `-l`/`--link` 指向本機外掛目錄而不複製它（會加入 `plugins.load.paths`）： ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw plugins install -l ./my-plugin ``` `--link` 不支援搭配 `--marketplace` 或 `git:` 安裝，且 要求本機路徑已經存在。若要建立非互動式本機連結， 請在檢閱來源後傳入 `--force`；它會確認來源，但不會 複製或覆寫連結的目錄。 從工作區 extensions 根目錄探索到的工作區來源外掛，在明確啟用前不會 匯入或執行。進行本機開發時， 請執行 `openclaw plugins enable ` 或設定 `plugins.entries..enabled: true`；如果你的設定使用 `plugins.allow`，也請在其中加入相同的外掛 ID。此預設拒絕規則 也適用於頻道設定明確以工作區來源外掛為目標、 僅為設定而載入的情況；因此，只要該工作區外掛仍停用或未列入允許清單， 本機頻道外掛設定程式碼就不會執行。連結安裝和明確的 `plugins.load.paths` 項目，則會依其解析後的外掛來源遵循一般政策。請參閱 [設定外掛政策](/zh-TW/tools/plugin#configure-plugin-policy) 和[設定參考](/zh-TW/gateway/configuration-reference#plugins)。 在 npm 安裝中使用 `--pin`，可將解析後的確切規格（`name@version`）儲存至受管理的外掛索引，同時維持預設不釘選的行為。 ## 列出 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw plugins list openclaw plugins list --enabled openclaw plugins list --verbose openclaw plugins list --json ``` 僅顯示已啟用的外掛。 從表格檢視切換為逐一顯示外掛詳細資料的行，其中包含格式／來源／出處／版本／啟用中繼資料。 機器可讀的清單，以及登錄診斷資訊和套件相依項目安裝狀態。 `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 複製至 `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 --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..hooks.allowConversationAccess=true`。 ### 外掛索引 外掛安裝中繼資料是由機器管理的狀態，而不是使用者設定。安裝與更新作業會將其寫入使用中 OpenClaw 狀態目錄下的共用 SQLite 狀態資料庫。`installed_plugin_index` 資料列會儲存持久的 `installRecords` 中繼資料，包括外掛資訊清單損壞或遺失的記錄，以及由資訊清單衍生的冷登錄快取，供 `openclaw plugins update`、解除安裝、診斷與冷外掛登錄使用。 `plugins.installs` 是已淘汰的手動設定介面。執行階段與更新命令只會讀取 SQLite 的已安裝外掛索引。請執行 `openclaw doctor --fix`，將舊版設定記錄匯入索引並移除已淘汰的鍵，再進行一般執行階段作業。 ## 解除安裝 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw plugins uninstall openclaw plugins uninstall --dry-run openclaw plugins uninstall --keep-files openclaw plugins uninstall --force ``` `uninstall` 會從 `plugins.entries`、持久保存的外掛索引及外掛允許／拒絕清單中移除外掛記錄，並在適用時移除連結的 `plugins.load.paths` 項目。除非設定了 `--keep-files`，否則解除安裝也會移除所追蹤的受管理安裝目錄，但僅限於該目錄解析後位於 OpenClaw 的外掛 extensions 根目錄內。若外掛目前占用 `memory` 或 `contextEngine` 插槽，該插槽會重設為預設值（記憶體為 `memory-core`，內容引擎為 `legacy`）。 `uninstall` 會輸出即將移除之項目的預覽，接著在進行變更前提示 `Uninstall plugin ""?`。傳入 `--force` 可略過確認提示（適合指令碼與非互動式執行）；若未傳入，解除安裝需要互動式 TTY。`--dry-run` 會輸出相同的預覽，然後直接結束，不會提示或變更任何內容。 `--keep-config` 是 `--keep-files` 的已棄用別名，仍受支援。 ## 更新 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw plugins update openclaw plugins update --all openclaw plugins update --dry-run openclaw plugins update @openclaw/voice-call openclaw plugins update @acme/demo openclaw plugins update openclaw-codex-app-server --acknowledge-clawhub-risk openclaw plugins update openclaw-codex-app-server --dangerously-force-unsafe-install ``` 更新適用於受管理外掛索引中追蹤的外掛安裝，以及共用 SQLite 狀態中追蹤的掛鉤套件安裝。更新會重複使用使用者安裝外掛時已選擇的來源，因此不需要再次確認來源。 傳入外掛 ID 時，OpenClaw 會重複使用為該外掛記錄的安裝規格。這表示先前儲存的 dist-tag（例如 `@beta`）與明確固定的版本，仍會在之後執行 `update ` 時繼續使用。 執行 `update --dry-run` 時，明確固定的 npm 安裝會維持固定。若 OpenClaw 也能解析套件的登錄預設版本線，且該預設版本線比已安裝的固定版本新，試執行會回報固定版本，並輸出明確的 `@latest` 套件更新命令，以跟隨登錄的預設版本線。 這項指定目標的更新規則與大量 `openclaw plugins update --all` 維護路徑不同。大量更新仍會遵循一般追蹤的安裝規格，但可信任的官方 OpenClaw 外掛記錄可以同步至目前的官方目錄目標，而不是停留在過時且明確指定的官方套件。若有意保持明確指定或帶有標籤的官方規格不變，請使用指定目標的 `update `。 對於 npm 安裝，也可以傳入帶有 dist-tag 或確切版本的明確 npm 套件規格。OpenClaw 會將該套件名稱解析回所追蹤的外掛記錄、更新該已安裝外掛，並記錄新的 npm 規格，以供未來依 ID 更新時使用。 傳入不含版本或標籤的 npm 套件名稱，也會解析回所追蹤的外掛記錄。若外掛原先固定於確切版本，而你想將其移回登錄的預設發行版本線，請使用此方式。 指定目標的 `openclaw plugins update ` 會重複使用所追蹤的外掛規格，除非傳入新的規格。大量 `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 外掛來源會略過此發行版本信任提示。 ## 檢查 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw plugins inspect openclaw plugins inspect --runtime openclaw plugins inspect --json openclaw plugins inspect --all ``` 依預設，檢查功能不會匯入外掛執行階段，但會顯示識別資訊、載入狀態、來源、資訊清單功能、政策旗標、診斷資訊、安裝中繼資料、套件功能，以及偵測到的任何 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` 驗證。 每個外掛會依其在執行階段實際登錄的內容分類： | 形態 | 意義 | | ------------------- | ------------------------ | | `plain-capability` | 正好一種功能類型（例如僅提供者外掛） | | `hybrid-capability` | 超過一種功能類型（例如文字 + 語音 + 圖像） | | `hook-only` | 僅有掛鉤，沒有功能、工具、命令、服務或路由 | | `non-capability` | 有工具／命令／服務，但沒有功能 | 如需進一步瞭解功能模型，請參閱[外掛形態](/zh-TW/plugins/architecture#plugin-shapes)。 `--json` 旗標會輸出適合指令碼與稽核使用的機器可讀報告。`inspect --all` 會呈現涵蓋整個機群的表格，其中包含形態、功能種類、相容性通知、套件功能和掛鉤摘要欄。`info` 是 `inspect` 的別名。 ## 修復 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw plugins doctor ``` `doctor` 會回報外掛載入錯誤、資訊清單／探索診斷、相容性通知，以及過時的外掛設定參照，例如缺少外掛插槽。當安裝樹狀結構與外掛設定都沒有問題時，會輸出 `No plugin issues detected.`。如果仍有過時設定，但安裝樹狀結構在其他方面皆正常，摘要會如實說明，而不會暗示外掛完全正常。 如果已設定的外掛存在於磁碟上，但遭載入器的路徑安全檢查封鎖，設定驗證會保留該外掛項目，並將其回報為 `present but blocked`。請修正前述的外掛封鎖診斷，例如路徑擁有權或所有使用者皆可寫入的權限，而不要移除 `plugins.entries.` 或 `plugins.allow` 設定。 若發生模組形態失敗，例如缺少 `register`/`activate` 匯出，請使用 `OPENCLAW_PLUGIN_LOAD_DEBUG=1` 重新執行，以在診斷輸出中加入精簡的匯出形態摘要。 ## 登錄檔 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw plugins registry openclaw plugins registry --refresh openclaw plugins registry --json ``` 本機外掛登錄檔是 OpenClaw 持久保存的冷讀取模型，用於記錄已安裝外掛的身分、啟用狀態、來源中繼資料及貢獻項目的擁有權。一般啟動、提供者擁有者查詢、頻道設定分類與外掛清單，都能在不匯入外掛執行階段模組的情況下讀取該登錄檔。 使用 `plugins registry` 檢查持久保存的登錄檔是否存在、是否為最新或已過時。使用 `--refresh`，根據持久保存的外掛索引、設定原則及資訊清單／套件中繼資料重建登錄檔。這是修復路徑，不是執行階段啟用路徑。 `openclaw doctor --fix` 也會修復登錄檔周邊由系統管理的 npm 漂移。如果受管理的外掛 npm 專案或舊版扁平受管理 npm 根目錄下，存在孤立或復原的 `@openclaw/*` 套件並遮蔽內建外掛，Doctor 會移除該過時套件並重建登錄檔，使啟動程序改為依據內建資訊清單進行驗證。當具權威性的安裝記錄選定某個受管理的世代，但仍殘留較舊的扁平目錄或世代目錄時，Doctor 會停用這些過時樹狀結構，待閘道重新啟動後再予以清除。Doctor 也會將主機的 `openclaw` 套件重新連結至宣告 `peerDependencies.openclaw` 的受管理 npm 外掛中，讓 `openclaw/plugin-sdk/*` 等套件本機執行階段匯入在更新或修復 npm 後仍可解析。 ## 市集 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw plugins marketplace entries openclaw plugins marketplace entries --offline openclaw plugins marketplace entries --json openclaw plugins marketplace entries --feed-profile openclaw plugins marketplace entries --feed-url openclaw plugins marketplace list openclaw plugins marketplace list --json openclaw plugins marketplace refresh openclaw plugins marketplace refresh --feed-profile openclaw plugins marketplace refresh --feed-url openclaw plugins marketplace refresh --expected-sha256 --json ``` `plugins marketplace entries` 會列出已設定 OpenClaw 市集摘要來源中的項目。預設會嘗試使用託管摘要來源，並在失敗時改用最近一次接受的快照或內建資料。使用 `--feed-profile ` 讀取特定的已設定設定檔，使用 `--feed-url ` 讀取明確指定的託管摘要來源 URL，並使用 `--offline` 在不擷取摘要來源的情況下讀取最近一次接受的快照。 `plugins marketplace refresh` 會重新整理已設定的託管摘要來源快照，並回報 OpenClaw 接受的是託管資料、託管快照或內建備援資料。當呼叫端要求除非新的託管承載內容符合固定的總和檢查碼，否則命令必須失敗時，請使用 `--expected-sha256`。 市集 `list` 可接受本機市集路徑、`marketplace.json` 路徑、如 `owner/repo` 的 GitHub 簡寫、GitHub 儲存庫 URL 或 git URL。`--json` 會輸出解析後的來源標籤，以及剖析後的市集資訊清單與外掛項目。 市集重新整理會載入託管的 OpenClaw 市集摘要來源，並將 驗證後的回應持久保存為本機託管摘要來源快照。若未指定選項，會使用 已設定的預設摘要來源設定檔。使用 `--feed-profile ` 重新整理 特定的已設定設定檔，使用 `--feed-url ` 重新整理明確指定的託管 摘要來源 URL，使用 `--expected-sha256 ` 要求承載內容總和檢查碼相符 （`sha256:` 或純 64 字元十六進位摘要），並使用 `--json` 取得機器可讀輸出。明確指定的託管摘要來源 URL 不得包含 認證資訊、查詢字串或片段。未固定總和檢查碼的重新整理可回報 託管快照或內建備援結果，而不讓命令失敗。固定總和檢查碼的 重新整理除非接受新的託管承載內容，否則會失敗；而成功接受託管內容的 重新整理若 OpenClaw 無法持久保存驗證後的快照，也會失敗。 內建的 `clawhub-public` 設定檔預期承載內容身分為 `clawhub-official`。ClawHub 產生並交付其正式環境公開金鑰後， OpenClaw 會內建該金鑰。在此之前，內建設定檔 不會授予已簽署摘要來源的安裝授權。公開金鑰必須來自受信任的 發行或操作者管道，而不是摘要來源主機上的金鑰端點。 OpenClaw 會驗證 DSSE 信封，且當設定檔宣告 `feedId` 時， 要求解碼後的承載內容 ID 與其相符。內建的 `clawhub-public` 設定檔一律宣告其身分，以防止其他摘要來源的有效文件 透過該設定檔遭到重播。 在分階段推出期間，既有且省略 `feedId` 的自訂已簽署設定檔 會保留簽章驗證，但不繫結承載內容身分。新的自訂 設定檔應宣告 `feedId`。摘要來源設定檔的設定介面將 連同 Control UI 所需的呈現中繼資料另行提供；其 Doctor 診斷必須要求操作者提供缺少的身分，而且不得 從摘要來源 URL 推斷身分。此信任繫結不會還原已淘汰的 根層級 `marketplaces` 金鑰。 ## 相關內容 * [建置外掛](/zh-TW/plugins/building-plugins) * [命令列介面參考](/zh-TW/cli) * [ClawHub](/zh-TW/clawhub)