SpyBara
Go Premium

plugins/troubleshooting.md 2026-09-24 22:57 UTC to 2026-09-25 23:58 UTC

This page contains 1064 additions and 0 deletions.

2026
Fri 25 23:58

排除外掛程式故障

修復 Claude Code 中的外掛程式錯誤。找到您看到的確切訊息，按照 /plugin 執行、安裝和組織政策的階段分組。

此頁面列出 Claude Code 外掛程式和市集的錯誤訊息和症狀，市集是 Claude Code 安裝外掛程式的目錄。每個項目都提供原因、一個修復方法，以及修復後您會看到的內容。

如果訊息命名了外掛程式或市集，該項目會顯示一個佔位符，例如 <name>。

無論您是安裝外掛程式、建置外掛程式、託管市集，還是為組織管理外掛程式，都可以使用此頁面。

搜尋您看到的確切訊息。每個訊息都列在產生它的階段下，這不一定是您執行的命令。例如，安裝可能因為市集遺失而失敗，所以該訊息在 新增市集 下。

找到 `/plugin` 執行的位置

/plugin 是您在執行中的 Claude Code 終端機工作階段內輸入的命令，它會開啟互動式面板。本節中的條目涵蓋您可以輸入它但它無法執行的位置，以及不存在的命令拼寫。

`/plugin isn't available in this environment`

您在 Claude Code 終端機工作階段以外的地方輸入了 /plugin，Claude 回覆了這一行，而不是開啟任何東西。

您會在沒有終端機來繪製 /plugin 面板的工作階段中收到此回覆：非互動模式，使用 claude -p、Agent SDK、Claude 桌面應用程式的 Code 標籤、VS Code 擴充功能面板，以及 claude.ai/code 上的瀏覽器。

在 VS Code 擴充功能面板中，只有 /plugin 行後面跟著某些內容（例如 /plugin install <plugin>@<marketplace>）會收到此回覆。單獨輸入 /plugin 或 /plugins 會開啟 管理外掛程式 對話框。

改為從您所在的表面安裝外掛程式：

  • Claude 桌面應用程式、本機或 SSH 工作階段：按一下提示旁邊的 + 按鈕，然後按 外掛程式，然後按 新增外掛程式 以開啟 外掛程式瀏覽器
  • VS Code 擴充功能：使用 安裝外掛程式 下的 VS Code 標籤
  • 網路上的 Claude Code，或桌面雲端工作階段：雲端工作階段沒有外掛程式瀏覽器。請參閱 安裝外掛程式 下的 雲端工作階段 標籤，了解雲端工作階段載入的內容
  • 您有權存取的終端機：執行 claude 並在那裡輸入 /plugin，或在您的 shell 中執行 claude plugin install <plugin>@<marketplace>，而不啟動工作階段

當終端機安裝成功時，/plugin 會列印以 ✓ Installed <plugin>. 開頭的安裝摘要，而 claude plugin install 會列印 Successfully installed plugin: <plugin>@<marketplace>。

`zsh: no such file or directory: /plugin`

您在 shell 提示符處輸入了 /plugin ...，shell 報告不存在名為 /plugin 的檔案。Bash 報告 bash: /plugin: No such file or directory。

/plugin 是您在 Claude Code 工作階段內輸入的命令，而不是在 shell 提示符處。啟動工作階段並在那裡輸入相同的命令：

claude

然後，在 Claude Code 提示符處：

/plugin install <plugin>@<marketplace>

成功的安裝會列印以 ✓ Installed <plugin>. 開頭的摘要。如果安裝本身隨後失敗，其訊息在 新增市集 或 安裝外掛程式 下。

若要從 shell 安裝而不啟動工作階段，請改為執行 claude plugin install <plugin>@<marketplace>。

`The term '/plugin' is not recognized as the name of a cmdlet`

您在 PowerShell 提示符處輸入了 /plugin ...，而 /plugin 是 Claude Code 命令，不是程式。Bash 和 Zsh 報告 它們自己的這個錯誤形式。

改為使用以下任一方式：

  • 執行 claude，然後在 Claude Code 提示符處輸入 /plugin
  • 在 PowerShell 中執行 claude plugin install <plugin>@<marketplace>，而不啟動工作階段

`claude: command not found` after `claude plugin ...`

您在 shell 中執行了 claude plugin install ...，shell 根本找不到 claude。在 Windows 上，訊息是 'claude' is not recognized as the name of a cmdlet 或 'claude' is not recognized as an internal or external command。

原因不是外掛程式命令。要麼 Claude Code 未安裝，要麼其安裝目錄不在此 shell 中的 PATH 上。遵循 command not found: claude after installation，然後重試外掛程式命令。

`Unknown command` and command spellings that don't exist

您輸入了您在某處看到的外掛程式命令，並在工作階段中收到 Unknown command: /<name>，或從 shell 中的 claude 二進位檔案收到 error: unknown command '<name>' 或 error: unknown option '<flag>'。

有幾個命令拼寫在使用中，Claude Code 沒有。下表將每個對應到真實命令。外掛程式命令參考 列出每個子命令和旗標。

您輸入 Claude Code 說什麼 改為使用
claude plugin add <source> error: unknown command 'add' claude plugin marketplace add <source> 以新增市集，或 claude plugin install <plugin>@<marketplace> 以安裝外掛程式
claude plugin install <plugin> --project error: unknown option '--project' claude plugin install <plugin>@<marketplace> --scope project
/install <plugin> Unknown command: /install /plugin install <plugin>@<marketplace>
/plugin add <source> /plugin 面板在 Discover 標籤上開啟 /plugin marketplace add <source>
marketplace.anthropic.com 作為來源 Invalid marketplace source format. Try: owner/repo, https://..., or ./path anthropics/claude-plugins-official 用於官方市集

這些拼寫看起來不對但有效：

  • claude plugins 是 claude plugin 的別名
  • claude plugin remove 是 claude plugin uninstall 的別名
  • /plugins 和 /marketplace 在工作階段中開啟與 /plugin 相同的面板

新增市集

市集是您從 git 儲存庫、URL 或本機路徑新增到 Claude Code 的目錄。這些條目涵蓋當新增失敗或稍後重新整理失敗時您收到的訊息。

`Marketplace "claude-plugins-official" not found`

您在工作階段中執行了 /plugin install <plugin>@claude-plugins-official，Claude Code 報告它沒有該名稱的市集。

官方市集尚未在此機器上註冊。Claude Code 通常在您第一次啟動互動式終端機工作階段時自行註冊它。如果您只透過 VS Code 擴充功能使用 Claude Code，它還沒有執行，並且它會跳過或延遲該步驟：

  • 當政策阻止來源時
  • 當設定 CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL 時
  • 在失敗的嘗試之後，等待重試

claude plugin shell 命令永遠不會為您註冊它。

新增它，然後重試安裝：

/plugin marketplace add anthropics/claude-plugins-official

Claude Code 列印 Successfully added marketplace: claude-plugins-official，而 /plugin marketplace list 顯示市集及其來源。

對於此訊息中的任何其他市集名稱，請參閱 Marketplace "<name>" not found。

相同的字串也出現在 /plugin Errors 標籤中，面板的載入失敗清單，當您的設定中列出的外掛程式命名您尚未新增的市集時。

`Marketplace "" not found`

您在工作階段中執行了 /plugin install <plugin>@<name>，通常來自某人傳送給您的安裝行，Claude Code 報告它沒有該名稱的市集。

如果名稱以 claudeai- 開頭，市集託管在 claude.ai 上，您可以使用 claude plugin marketplace add --claudeai <name> 從 shell 按名稱新增它。請參閱 從 claude.ai 新增市集。

對於任何其他名稱，安裝行命名市集但不說明市集託管在何處，Claude Code 沒有索引來查詢市集名稱。詢問傳送該行的人市集的來源，這是 GitHub owner/repo、git URL 或路徑。然後 新增市集 並再次執行安裝行。

某人傳送給您的市集是第三方的，所以 在安裝前檢查外掛程式。

如果您已經新增了市集，請根據 /plugin marketplace list 檢查拼寫。

`Invalid marketplace source format`

您執行了 /plugin marketplace add <source> 或 claude plugin marketplace add <source>，Claude Code 回覆 Invalid marketplace source format. Try: owner/repo, https://..., or ./path。

Claude Code 接受以下形式之一的來源：

  • GitHub owner/repo 速記
  • https:// 或 http:// URL
  • user@host:path SSH URL
  • 以 ./、../、/ 或 ~ 開頭的本機路徑

裸名稱（例如 claude-plugins-official）不符合任何一個。裸主機名稱（例如 marketplace.anthropic.com）也不符合。

以接受的形式之一重新輸入來源：

/plugin marketplace add anthropics/claude-plugins-official

當新增成功時，Claude Code 列印 Successfully added marketplace: <name>。

`'' is not a valid GitHub owner/repo shorthand`

您傳遞了一個包含斜線但不是 owner/repo 的來源，例如 github.com/owner/repo 或 gitlab.example.com/group/project 路徑。Claude Code 拒絕了它，並提供了接受的形式清單。

owner/repo 速記僅限 GitHub，必須遵循 GitHub 的命名規則，因此主機名稱或額外的路徑段會失敗。以符合市集託管位置的形式傳遞來源：

  • 任何主機上的儲存庫：完整的複製 URL
  • 託管的 marketplace.json：其 https:// URL
  • 本機簽出：./path 或絕對路徑

例如，若要透過其複製 URL 新增官方市集，請在工作階段中：

/plugin marketplace add https://github.com/anthropics/claude-plugins-official.git

成功的新增會列印 Successfully added marketplace: <name>。

`Path does not exist: `

您傳遞了本機路徑給 marketplace add，該路徑處沒有任何內容。相對路徑相對於您的目前目錄解析。

檢查訊息中的已解析路徑。然後從相對路徑開始的目錄執行命令，或傳遞市集目錄的絕對路徑。成功的新增會列印 Successfully added marketplace: <name>。

Claude Code 接受包含 .claude-plugin/marketplace.json 的目錄，或指向 .json 檔案的路徑。指向任何其他檔案的路徑會失敗，並顯示 File path must point to a .json file (marketplace.json)。

`Marketplace file not found at /.claude-plugin/marketplace.json`

Claude Code 複製或下載了市集，但在其內部的預期路徑中找不到 marketplace.json。新增命令將其報告為 Failed to add marketplace: Marketplace file not found at ...。

預設位置是儲存庫根目錄中的 .claude-plugin/marketplace.json，市集參考 列出接受的位置。

修復因所有者和其他人而異：

  • 您擁有市集：將檔案放在該位置並重新新增市集
  • 其他人託管它：詢問所有者確切的來源他們發佈

`SSH authentication failed` or `HTTPS authentication failed`

您從 git 儲存庫新增或更新了市集，複製失敗，並顯示 Failed to clone marketplace repository: 後跟以下其中一行。

首先檢查儲存庫本身：拼寫錯誤的 owner/repo、不存在的儲存庫或您看不到的私人儲存庫也會以此訊息結尾。在瀏覽器中開啟儲存庫 URL，或在終端機中執行 git ls-remote <url>，以確認它存在且您有權存取。

如果儲存庫是正確的，原因是認證。Claude Code 執行 git 時禁用互動式提示，因此它無法像您的終端機那樣要求您輸入密碼、金鑰密碼或認證。如果 git 需要提示，您會看到 fatal: Cannot prompt because user interactivity has been disabled 或 terminal prompts disabled 在原始錯誤中。只有已經非互動式工作的認證才會成功：

  • SSH：ssh -T git@<host> 必須成功而不提示密碼，並且主機必須已在 known_hosts 中
  • HTTPS：您的認證助手必須為主機保存令牌。對於 GitHub，執行 gh auth login 和 gh auth setup-git。對於另一個主機，在您的 git 認證助手中儲存個人存取令牌。使用 git ls-remote <url> 測試

一旦 git ls-remote 在您的終端機中成功執行而不提示，請再次執行新增或更新。成功的新增會列印 Successfully added marketplace: <name>。成功的更新會從您的 shell 列印 Successfully updated marketplace: <name>，或在工作階段中列印 ✔ Updated 1 marketplace。

若要讓 Claude Code 跳過 GitHub owner/repo 來源的 SSH，請設定 CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1。沒有它，當 github.com 的 SSH 金鑰看起來已配置時，Claude Code 會透過 SSH 複製這些來源，並在 SSH 複製失敗時回退到 HTTPS。

有關背景自動更新可以和不能對您的認證做什麼，請參閱 背景自動更新對認證的作用。

`SSH host key is not in your known_hosts file`

您從您從未連接過的主機透過 SSH 新增了市集，複製失敗，並顯示此行和 ssh -T git@<host> 提示。對於金鑰已更改的主機，訊息是 SSH host key has changed，並改為提供 ssh-keygen -R <host> 提示。

Claude Code 使用 StrictHostKeyChecking=yes 複製，因此它拒絕您尚未接受其金鑰的主機，而不是自動接受金鑰。從您的終端機連接一次以接受指紋，然後重試：

ssh -T git@github.com

對於公開儲存庫，改為使用其 https:// URL 新增市集，以完全避免 SSH。

`Command 'git' not found or is in an unsafe location`

在 Windows 上，您新增了市集，Claude Code 報告 Failed to clone marketplace repository: Command 'git' not found or is in an unsafe location (current directory)。

Claude Code 在您的 PATH 上查找 git，並拒絕執行僅在目前目錄中找到的。若要修復它，請安裝 Git 並重試：

1

安裝 Git for Windows

安裝 Git for Windows，使 git 在您的 PATH 上。

2

開啟新終端機

開啟新終端機，使更新的 PATH 適用。

3

確認 git 執行

確認 git --version 列印版本。

4

重試新增

再次執行 marketplace add 命令。

`Git clone timed out after 120s`

您新增或更新了市集，它失敗，並顯示 Git clone timed out after 120s，後跟設定 CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS 的提示。

複製市集和重新複製一個以更新它，預設情況下獲得 120 秒。對於大型儲存庫或緩慢連接，提高限制。該值以毫秒為單位：

export CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS=300000

然後在同一 shell 中重試。

如果儲存庫是 monorepo，使用 claude plugin marketplace add <source> --sparse <paths> 限制簽出到您命名的目錄。

Marketplace updates keep failing offline

您在市集的 git 主機無法到達的環境中工作，每個工作階段都在背景中重複失敗的重新整理。您現有的市集簽出保持原位，啟動不會延遲。

每個工作階段，對於 開啟自動更新 的市集，Claude Code 在背景中檢查市集的 git 主機是否有新提交。當該檢查無法到達主機時，它會嘗試再次複製市集，離線時該複製也會失敗。

設定此變數以跳過重新複製嘗試，並在檢查無法到達主機時繼續使用現有簽出：

export CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1

設定變數後，Claude Code 僅對已包含 .claude-plugin/marketplace.json 的簽出跳過重新複製。從未複製或其複製中途停止的市集仍會獲得複製嘗試，因此在線上新增一次。

對於完全離線部署，改為在映像建置時使用 CLAUDE_CODE_PLUGIN_SEED_DIR 預先填充外掛程式目錄，遵循 種子容器和 CI。

Marketplace add fails on a GitHub Enterprise Server host

您從 GitHub Enterprise Server (GHES) URL 新增了市集，並收到政策錯誤，或您從 claude.ai 新增了它，並收到 GitHub 存取錯誤。

兩種情況都在 GHES 頁面上：

安裝外掛程式

您新增了市集並執行了安裝，安裝停止並顯示訊息，而不是安裝任何內容。這些條目涵蓋這些訊息。它們也涵蓋稍後出現在 /plugin Errors 標籤中的相關訊息，或當外掛程式或其市集無法找到、讀取或信任時的空白 Discover 標籤。

`Plugin "" not found in marketplace ""`

您執行了 /plugin install <name>@<marketplace> 或 claude plugin install <name>@<marketplace>，外掛程式名稱不在您機器上該市集目錄的副本中。

當您根本沒有新增市集時，claude plugin install 在您的 shell 中列印相同的訊息。如果 claude plugin marketplace update <marketplace> 然後回答 Marketplace '<marketplace>' not found，首先新增市集。

`not found in marketplace` with a refresh hint

提示讀取 Your local copy may be out of date — try claude plugin marketplace update <marketplace> 或 The marketplace couldn't be refreshed (...)。Claude Code 在查詢前沒有重新整理市集，例如當您離線時，所以您的目錄副本可能已過時。使用市集的名稱重新整理，然後再次安裝：

/plugin marketplace update <marketplace>

claude plugin marketplace update 列印 Successfully updated marketplace: <name>，而 /plugin marketplace update 顯示 ✔ Updated 1 marketplace。如果重試的安裝列印相同的訊息，請按照 not found in marketplace with no hint 描述檢查名稱。Claude Code 何時在安裝前重新整理市集 列出重新整理不執行的其他情況。

`not found in marketplace` with no hint

名稱是最可能的問題。開啟 /plugin，前往 Discover，並從清單中複製名稱。

在 v2.1.232 之前，Claude Code 僅在查詢未命中後重新整理命名的市集，並且僅當為其開啟自動更新時。

`Plugin "" not found in any marketplace`

您執行了 /plugin install <name>，沒有 @marketplace，沒有註冊的市集有該外掛程式。claude plugin install <name> 報告 Plugin "<name>" not found in any configured marketplace。

沒有市集名稱，claude plugin install 搜尋它已有的目錄，不會首先重新整理它們，而 /plugin install 僅重新整理開啟自動更新的市集。命名市集，Claude Code 在查詢外掛程式前重新整理它：

/plugin install <name>@<marketplace>

當安裝成功時，您在工作階段中看到 ✓ Installed <plugin>.，或從 claude plugin install 看到 Successfully installed plugin: <plugin>@<marketplace>。

如果您不知道哪個市集列出外掛程式，請執行 /plugin marketplace list 以取得您擁有的市集，並在 /plugin 中瀏覽 Discover 以查找外掛程式名稱。

`Plugin '@' is already installed globally`

您為已在使用者範圍或由受管設定安裝的外掛程式執行了 /plugin install，Claude Code 拒絕了 Use '/plugin' to manage existing plugins.。如果您輸入了沒有 @<marketplace> 的外掛程式名稱，訊息會省略 globally。

外掛程式已在每個專案中可用，因此沒有任何內容要新增。若要變更其 範圍、啟用或停用它，或配置它，請開啟 /plugin 並前往 Installed。

僅在專案或本機範圍安裝的外掛程式不會觸發此訊息。Claude Code 允許您也在使用者範圍安裝它，因此它在其他專案中可用。

claude plugin install 在您的 shell 中列印不同的訊息。對於已在目標範圍安裝的外掛程式，它列印 Plugin "<name>@<marketplace>" is already installed (scope: user) 並以退出代碼 0 退出。如果其快取目錄遺失，相同的命令會重新下載它。

`This plugin uses a source type your Claude Code version does not support`

您安裝了一個外掛程式，其市集條目使用此版本 Claude Code 無法擷取的來源類型，Claude Code 停止並顯示此訊息和 Update Claude Code and try again.

更新 Claude Code，然後重試安裝。來源類型在 市集參考 上。

`Plugin archive integrity check failed`

您安裝了一個作為 zip 存檔分發的外掛程式，Claude Code 拒絕了它，並顯示此行和 The archive was not installed.。外掛程式的市集條目使用帶有 sha256 釘選的 archive 來源，下載的檔案的摘要與釘選不符。

完整訊息如下所示：

Plugin archive integrity check failed for https://artifacts.example.com/claude-plugins/my-plugin.zip: expected sha256 6bfa50e3d2e00c052b46abe51fff89346ac803e45771f76dcf6df1ab74cca5e1, got ac52220c0914ef8ca6a602e4a7362f88d30fb021110f72a6d15b68c3fe7df2b7. The archive was not installed. Verify the sha256 in the marketplace entry, or that the URL serves the intended file.

修復因發佈者和安裝程式而異：

  • 您發佈外掛程式：重新計算 URL 提供的確切檔案的摘要，並更新市集條目中的 sha256。使用 shasum -a 256 my-plugin.zip 或 PowerShell 中的 Get-FileHash -Algorithm SHA256 my-plugin.zip
  • 您安裝外掛程式：在工作階段中執行 /plugin marketplace update <name> 以重新整理目錄，以防條目已更正，然後重試安裝。如果重新整理後摘要仍然不同，請詢問市集所有者在安裝前他們釘選了哪個檔案

`Marketplace "" is registered from an untrusted source`

您之前新增的市集停止載入，其外掛程式也停止載入。此行出現在 /plugin Errors 標籤或下一次重新整理時。

市集以 為官方 Anthropic 市集保留 的名稱註冊，但其註冊來源不是 anthropics GitHub 儲存庫。每次市集載入或重新整理時都會重新檢查保留的名稱，因此市集和從它安裝的外掛程式停止載入。

完整訊息命名保留的名稱和修復：

Marketplace "claude-community" is registered from an untrusted source: The name 'claude-community' is reserved for official Anthropic marketplaces. Only repositories from 'github.com/anthropics/' can use this name. To fix it, remove the marketplace and re-add it from the official source.

修復因使用者和發佈者而異：

  • 您使用市集：在您的 shell 中，執行 claude plugin marketplace remove <name>，然後從官方 github.com/anthropics 儲存庫再次新增市集
  • 您發佈了在其名稱變為保留前使用該名稱的第三方市集：重新命名它，並要求使用者從您的來源重新新增它

在 v2.1.205 之前，Claude Code 僅在您新增市集時檢查名稱，因此在其名稱變為保留前註冊的條目保持載入。

`Plugin has a corrupt manifest file` or `has an invalid manifest file`

Claude Code 擷取了外掛程式，然後無法讀取其 .claude-plugin/plugin.json。在 shell 中，此行中的 <name> 可以是臨時目錄名稱；Failed to install plugin "<name>@<marketplace>" 前綴帶有外掛程式的真實名稱。措辭說明哪個檢查失敗：

  • corrupt manifest file，後跟 JSON parse error:：檔案不是有效的 JSON
  • invalid manifest file，後跟 Validation errors:：檔案解析但失敗架構，例如 name: Invalid input 用於遺失的必需欄位

claude plugin install 報告為 Failed to install plugin "<name>@<marketplace>": 並以代碼 1 退出。

外掛程式的作者必須修復檔案，在那之前無法安裝外掛程式：

  • 如果那是您：在您的 shell 中執行 claude plugin validate <plugin-directory> 以查看相同的錯誤及其違規路徑，然後修復檔案
  • 如果不是您：向市集所有者報告訊息

`Plugin directory not found at path: `

/plugin 中的 Errors 標籤顯示這個用於啟用的外掛程式，其市集按相對路徑列出，例如 ./plugins/my-plugin，當市集內該路徑處沒有目錄時。如果您維護市集，請更正條目的 source 路徑或還原資料夾。否則，向市集所有者報告訊息。

Marketplace directory not found at path: <path> 表示市集自己的目錄遺失。對於您從本機路徑新增的市集，該目錄已移動或已刪除。還原它，或移除市集並從其新位置再次新增它。

`No plugins available` or `No marketplaces configured`

您開啟了 /plugin，Discover 標籤為空，或 claude plugin marketplace list 列印 No marketplaces configured。

沒有市集註冊，因此沒有目錄可顯示。在工作階段中，新增官方市集 anthropics/claude-plugins-official：

/plugin marketplace add anthropics/claude-plugins-official

Claude Code 列印 Successfully added marketplace: claude-plugins-official，而 Discover 列出其外掛程式。Anthropic 市集 頁面列出您可以新增的其他市集。

`Marketplace "" is already added from a different source`

您確認透過 /plugin install <plugin> --marketplace <source> 新增市集，Claude Code 從該來源擷取的目錄與您已從不同來源新增的市集具有相同的名稱。Claude Code 保留現有市集而不是替換它，外掛程式未安裝。

完整訊息如下所示：

Marketplace "acme-tools" is already added from a different source (github:acme/plugins). To use this source instead, remove that marketplace first with /plugin marketplace remove acme-tools.

選擇您想要的來源：

  • 您已新增的市集：使用 /plugin install <plugin>@<name> 按名稱從它安裝
  • 新來源：執行 /plugin marketplace remove <name>，然後重試安裝

`Cannot add marketplace "": its network source differs from the one declared for it in settings`

您執行了 marketplace add，該來源的目錄與設定檔已在 extraKnownMarketplaces 下以不同來源宣告的市集具有相同的名稱。Claude Code 拒絕新增並註冊任何內容。

訊息以修復結尾：來源必須符合設定中為此名稱宣告的來源，或您變更宣告。將您傳遞的來源與該名稱的 extraKnownMarketplaces 條目進行比較，包括其 ref、path 和 headers，然後執行以下其中一項：

  • 使用宣告的來源：從設定條目命名的來源新增市集
  • 使用新來源：編輯或移除 extraKnownMarketplaces 條目，然後再次新增市集。如果受管設定宣告它，請詢問您的管理員

`Failed to install: ()`

您在 /plugin 功能表中選擇了要安裝的外掛程式，沒有任何一個安裝，功能表關閉並顯示失敗的摘要。

某些原因（例如失敗複製後的 git 輸出）僅顯示其第一行。當這樣的原因被縮短時，摘要以 Installing a plugin from its details (Enter) in /plugin shows its full error. 結尾

該做什麼取決於摘要是否縮短了原因：

  • 修復括號中原因命名的內容
  • 當原因被縮短時，執行 /plugin，在 Discover 標籤上選擇外掛程式，然後按 Enter 從其詳細資訊安裝它。如果安裝在那裡失敗，詳細資訊檢視會顯示整個錯誤

`Could not move the new copy of this plugin version into `

當您安裝外掛程式時，Claude Code 下載其檔案的新副本，並將其移動到 外掛程式快取 中該版本的資料夾。此訊息表示移動失敗，通常是因為另一個程式在安裝執行時使用了該資料夾。檔案系統代碼出現在括號中：

Could not move the new copy of this plugin version into /home/user/.claude/plugins/cache/acme-tools/formatter/1.2.0: the new copy or the version folder stayed busy while the install ran (ENOTEMPTY) — usually a scanner still reading the freshly downloaded files, another program using that folder, or another process re-creating it. The previously installed copy was moved back. Run the install again once other Claude Code sessions or programs using that folder have finished.

訊息說明了安裝前的副本發生了什麼，這告訴您外掛程式是否仍然有效：

  • The previously installed copy was moved back：您擁有的版本仍然安裝
  • had to be removed first、was not moved back 或 could not be moved back：該外掛程式版本在安裝成功前未安裝
  • 沒有這樣的句子：沒有較早的副本，因此版本未安裝

在 Windows 上，當另一個程式持有已安裝的副本本身時，訊息改為說該副本 could not be replaced，並且 It was not replaced and the new copy was discarded，因此您擁有的版本仍然安裝。

Left on disk 清單命名快取內的預留資料夾。稍後安裝該版本或外掛程式快取清理會移除它們，因此您不需要刪除它們。

若要修復安裝：

  • 關閉使用外掛程式資料夾（在 ~/.claude/plugins/cache 下）的其他 Claude Code 工作階段、編輯器和終端機，然後再次執行安裝
  • 當訊息說檢查外掛程式快取資料夾的權限時，還原您對其命名的資料夾的寫入權限並釋放磁碟空間，然後再次執行安裝

Dependency errors

宣告依賴項的外掛程式在無法滿足依賴項時可能無法安裝或安裝並保持停用。訊息在安裝時或載入時到達您：

  • 在安裝期間：拒絕作為安裝的錯誤訊息返回
  • 當外掛程式載入時：問題出現在 claude plugin list 和 /plugin Errors 標籤中，Claude Code 保持受影響的外掛程式停用，直到您解決它

下表列出每個訊息及其修復。若要作為作者宣告依賴項，請參閱 外掛程式依賴項。

訊息 含義 如何解決
Dependency "<dep>" is not installed 宣告的依賴項未安裝。 使用 claude plugin install <dep>@<marketplace> 在您的 shell 中安裝它，或卸載外掛程式。如果依賴項的市集尚未註冊，請新增它並在您的工作階段中執行 /reload-plugins，這會安裝它可以解決的遺失依賴項。
Dependency "<dep>" is disabled 依賴項已安裝但已關閉。 啟用依賴項，或卸載需要它的外掛程式。
Requires "<dep>" <range>, installed <version> 已安裝的依賴項版本超出外掛程式的宣告範圍。 將依賴項更新到範圍內的版本，或卸載外掛程式。
<Plugin or Dependency> "<name>" has conflicting version requirements 沒有版本滿足每個釘選它的範圍。訊息列出範圍。 卸載或更新其中一個衝突的外掛程式，或要求上游作者擴大其約束。
... has version requirements too complex to intersect 或 has an invalid version requirement 範圍不是有效的 semver，或無法相交組合的範圍。 修復無效範圍或簡化長 || 鏈。
... has no git tag satisfying <range> 依賴項的儲存庫在範圍內沒有 <name>--v* 標籤。 檢查上游是否使用該約定標記版本，或放寬範圍。
Dependency "<dep>" (required by <plugin>) is in <marketplace>, which is not in the allowlist 依賴項在不同的市集中，預設情況下跨市集解析已關閉。 在相同範圍自行安裝依賴項，在您的 shell 中使用 claude plugin install <dep>@<marketplace> 加上您安裝外掛程式的 --scope，然後重試。

若要以程式設計方式查看這些，請在您的 shell 中執行 claude plugin list --json。有問題的外掛程式帶有 errors 欄位及其訊息和 errorDetails 欄位，每個都有 type：前兩行是 dependency-unsatisfied，第三行是 dependency-version-unsatisfied。

外掛程式已安裝但無法運作

安裝成功，但外掛程式的技能、hooks 或伺服器沒有執行任何操作。從 外掛程式不出現或其技能不顯示 開始，它告訴您 Claude Code 報告它載入的位置，然後符合訊息。

Plugin doesn't appear or its skills don't show up

您安裝了外掛程式並輸入 / 期望其技能，或要求 Claude 使用它，但沒有任何反應。

在變更任何內容前檢查外掛程式的狀態：

1

確認外掛程式已安裝並啟用

執行 /plugin 並開啟 Installed。確認外掛程式已列出並啟用。claude plugin list 在您的 shell 中列印相同的清單，每個外掛程式的版本、範圍和 Status: ✔ enabled。

2

讀取 Errors 標籤

在同一面板中開啟 Errors 標籤。每個條目將訊息與指導行配對。本節其餘部分的大多數訊息來自該標籤。

3

如果您在此工作階段期間安裝，請重新載入

如果外掛程式已安裝且無錯誤，但您在此工作階段期間安裝了它，請執行 /reload-plugins。它列印 Reloaded: 及外掛程式、技能、代理、hooks 和伺服器的計數。當某些失敗時，它新增 N errors during load. Run /plugin for details.

如果外掛程式載入無錯誤且其技能仍未出現，下一步因您自己的外掛程式和其他人的而異：

  • 您正在建置的外掛程式：請參閱 外掛程式載入但其技能遺失
  • 某人發佈的外掛程式：在 /plugin 中開啟 Installed，並開啟外掛程式的詳細資訊窗格，其中列出外掛程式包含的內容。在那裡列出無技能的外掛程式在您輸入 / 時沒有任何內容可提供

`Run /reload-plugins to activate.`

/plugin 中的安裝摘要以 Run /reload-plugins to activate. 結尾，而不是 Plugin is now active.

Claude Code 在安裝期間沒有啟用外掛程式，要麼是因為啟用它會 使提示快取失效，要麼是因為啟用嘗試失敗。

您不需要輸入命令。面板關閉，Claude Code 為您執行 /reload-plugins，或將其排隊直到正在串流的回應完成。

讀取該重新載入列印的內容：

  • Reloaded: 及外掛程式、技能、代理、hooks 和伺服器的計數：外掛程式現在處於活動狀態。當某些無法載入時，該行新增 N errors during load. Run /plugin for details.
  • This reload changes MCP tools (...) — your next message will re-read the whole conversation instead of using the cache. Run /reload-plugins --force to apply.：重新載入會新增或移除外掛程式 MCP 伺服器，或 LSP 工具，並使您的提示快取失效。對於 LSP 情況，該行以 This reload adds the LSP tool 或 This reload removes the LSP tool 開頭。執行它時使用 --force 以啟用外掛程式，或啟動新工作階段

在 v2.1.268 之前，在安裝期間未啟用的安裝保持待處理，直到您自己執行 /reload-plugins。

在 v2.1.246 之前，該摘要中的技能計數僅包括外掛程式的 commands/ 條目，因此重新載入可以載入外掛程式的 SKILL.md 技能，仍然報告 0 skills。

`Plugin "" not cached at `

Errors 標籤顯示此行及指導 Run /plugin to refresh the plugin cache。Claude Code 有外掛程式的安裝記錄，但記錄指向的目錄遺失，例如在您清除快取後。

從您的 shell 重新安裝外掛程式。claude plugin install <name>@<marketplace> 重新下載外掛程式，其安裝目錄遺失，即使其記錄存在：

claude plugin install <name>@<marketplace>

然後在您的工作階段中執行 /reload-plugins。Errors 標籤條目消失，外掛程式回到 Installed 下。

`Disabled in ~/.claude/settings.json but still loads`

您在 ~/.claude/settings.json 中將外掛程式設定為 false，其在 claude plugin list 或 /plugin 中的行顯示此訊息，後跟啟用它的來源，例如 — project settings enable it, which overrides your user setting。該更高優先順序來源中的 true 正在覆蓋您的使用者設定。

若要在您的機器上選擇退出專案啟用的外掛程式，請在 .claude/settings.local.json 中將 id 設定為 false，其優先順序高於專案檔案。對於訊息可以命名的其他來源，請參閱 在使用者設定中停用但仍然載入。

如果 claude plugin list 改為將外掛程式標記為 required by your org，沒有設定檔涉及：您的組織在 claude.ai 上將該同步外掛程式標記為必需，即使您之前停用了它，它也會載入。請參閱 從 claude.ai 同步的外掛程式。

`Plugin "" is enabled in project settings but isn't installed here`

Errors 標籤顯示此行用於您的專案的 .claude/settings.json 啟用的外掛程式，指導 Run claude plugin install <name>@<marketplace> --scope project to install it for this project。

儲存庫的設定可以為打開它的每個人啟用外掛程式，但它們不會安裝它。當外掛程式來自外部來源（例如 GitHub 儲存庫或 npm 套件）時，Claude Code 在您自己安裝它之前不會下載它。從指導行在您的 shell 中執行命令，然後重新載入：

claude plugin install <name>@<marketplace> --scope project

在您的工作階段中執行 /reload-plugins 後，Errors 標籤條目消失，外掛程式列在 Installed 下。

如果您的組織為您預先安裝外掛程式，它會透過受管設定執行此操作。請參閱 預先安裝和要求外掛程式。

`Failed to load hooks from ` and hooks that don't fire

外掛程式的 hooks 不執行。要麼 Errors 標籤顯示它們的載入失敗，hooks 載入且您在文字記錄中看到 <Event> hook error 通知，要麼 hook 載入無錯誤且永遠不會觸發。

Hooks fail to load

Errors 標籤顯示以下其中一個訊息：

  • Failed to load hooks from <path>: <reason>：hooks/hooks.json 不是有效的 JSON 或失敗 hooks 架構。原因命名解析或驗證錯誤。修復檔案。若要在發佈外掛程式前在 hooks/hooks.json 中捕捉 JSON 語法問題，請在您的 shell 中執行 claude plugin validate <plugin-directory>
  • hooks path not found: <path>：清單的 hooks 欄位命名在相對於外掛程式根目錄的該路徑處不存在的檔案。修復路徑或新增檔案

`hook error` notices in the transcript

形式為 ... hook error: Failed with non-blocking status code: <stderr> 的通知表示 hook 執行且其命令失敗。例如，Stop hook error: Failed with non-blocking status code: /bin/sh: node: command not found 表示 Claude Code 產生的 shell 找不到 node。安裝它，或確保它在您啟動 claude 的終端機的 PATH 上。

對於任何其他錯誤，從外掛程式目錄自行執行 hook 的命令以查看完整輸出，或使用 偵錯記錄 捕捉完整 stderr。

Hook loads but never fires

如果 hook 載入無錯誤但永遠不會觸發，請檢查其定義，然後觀看它執行：

1

檢查事件名稱

事件名稱區分大小寫，因此確認您的名稱完全符合，例如 PostToolUse。

2

檢查匹配器

確認 hook 的 matcher 符合工具名稱。

3

故意觸發事件

對於 PostToolUse hook，要求 Claude 編輯檔案。

4

讀取偵錯日誌

開啟 偵錯日誌，其記錄哪些 hooks 符合。執行的 hook 會出現在那裡及其退出代碼。

`Invalid MCP server config for ""` and MCP servers that don't start

外掛程式捆綁了 MCP 伺服器，Errors 標籤顯示 Invalid MCP server config for "<server>": <error>，或伺服器已列出但 /mcp 永遠不會顯示它已連接。

`Invalid MCP server config for "": `

伺服器的配置通過架構檢查，但 Claude Code 無法為此工作階段解決它。冒號後的文字命名原因並決定修復：

  • Missing environment variables: <names>：在啟動 Claude Code 的 shell 中設定這些變數，然後啟動新工作階段
  • URL is unset or invalid：URL 使用的 ${user_config.*} 選項未設定。執行 /plugin configure <plugin> 以設定它
  • has an invalid MCP url 或 headersHelper for MCP server '<server>' references ${user_config.*}：外掛程式自己的配置有問題。修復您外掛程式的 MCP 配置中的 url 或 headersHelper，或如果外掛程式不是您的，向外掛程式的作者報告。headersHelper 情況在 外掛程式命令參考 user_config 下有自己的條目

Server is configured but never connects

執行 /mcp 以查看伺服器的狀態。當伺服器健康時，/mcp 將其列為已連接。

若要讀取伺服器在啟動時列印的錯誤，請執行 claude --debug 並在 ~/.claude/debug/<session-id>.txt 開啟日誌。--debug 旗標不會列印到終端機。

.mcp.json 中失敗架構的伺服器條目不會出現在 Errors 標籤中。Claude Code 丟棄該伺服器，並僅在該偵錯日誌中記錄 Invalid MCP server config for <server> in <path>。若要在不載入外掛程式的情況下找到條目，請在外掛程式目錄上在您的 shell 中執行 claude plugin validate，它將其報告為錯誤。

在 v2.1.281 之前，claude plugin validate 沒有檢查 .mcp.json。

Server works with `--plugin-dir` but fails after install

您是外掛程式的作者，伺服器在您使用 --plugin-dir 從其來源目錄載入外掛程式時啟動，但在安裝後失敗。

Claude Code 將已安裝的外掛程式複製到其快取中，因此僅從來源目錄工作的路徑會中斷。使用 ${CLAUDE_PLUGIN_ROOT} 在外掛程式內寫入路徑。

對於到達外掛程式目錄外的路徑，請參閱 外掛程式參考的外掛程式目錄外的檔案未找到。

Language server doesn't start, uses too much memory, or reports wrong diagnostics

您安裝了 程式碼智慧外掛程式，Claude 沒有看到診斷，或語言伺服器使用太多記憶體或報告不是真實的錯誤。

Language server doesn't start

外掛程式連接到您單獨安裝的語言伺服器二進位檔案，Claude Code 從您的 PATH 按命令名稱產生它。

/plugin Errors 標籤顯示失敗及其原因，例如 Executable not found in $PATH: "<binary>"，而 claude --debug 將其記錄為 LSP server <name> failed to start: <reason>。

安裝二進位檔案並確認它在您啟動 claude 的終端機的 PATH 上，例如使用 which typescript-language-server。然後啟動新工作階段。

Language server uses too much memory

語言伺服器（例如 rust-analyzer 和 pyright）索引整個專案。使用 /plugin disable <plugin> 在工作階段中停用外掛程式，並改為依賴 Claude 的內建搜尋工具。

False positive diagnostics in a monorepo

未為工作區配置的語言伺服器可以報告內部套件的未解決匯入。Claude Code 端沒有任何內容要修復，診斷不會阻止 Claude 編輯程式碼。

建立外掛程式

您正在開發外掛程式，並使用 --plugin-dir 載入它或從本機市集安裝它。這些項目涵蓋您在開發外掛程式時遇到的失敗。若要在每次變更後執行檢查，請參閱測試和偵錯。

兩個也會影響外掛程式使用者的失敗在外掛程式已安裝但無法運作下有其項目：

`commands path not found: `

Errors 標籤顯示 commands path not found: <absolute path>，並提供指導 Check that the path in your manifest or marketplace config is correct。skills、agents 和 hooks 也會出現相同訊息。

Claude Code 從您的 plugin.json 或市集項目解析了一個路徑，相對於外掛程式根目錄，但在該處找不到任何內容。訊息中的路徑是它檢查的絕對路徑，因此請將其與磁碟上的內容進行比較。修正路徑或建立目錄，然後執行 /reload-plugins。

資訊清單中的路徑相對於外掛程式根目錄，並以 ./ 開頭。解析到外掛程式根目錄外的路徑會改為報告為 <component> path escapes plugin directory，並被捨棄。

`--plugin-dir` 在市集根目錄不會載入 `plugins/` 下的外掛程式

您啟動了 claude --plugin-dir <path>，沒有看到錯誤，但外掛程式的 skills、agents 和 hooks 不存在。

--plugin-dir 採用外掛程式的根目錄，即包含 .claude-plugin/plugin.json 和元件目錄（例如 skills/）的目錄。如果您改為指向市集根目錄，Claude Code 不會讀取 marketplace.json，因此 plugins/ 下的外掛程式不會載入，您也看不到錯誤。在 v2.1.281 之前，Claude Code 將市集根目錄載入為一個以該目錄命名的空外掛程式。將旗標指向外掛程式目錄本身：

claude --plugin-dir ./my-marketplace/plugins/my-plugin

然後在 /plugin 中開啟 Installed，外掛程式的詳細資訊窗格會列出其元件。

外掛程式參考其目錄外的檔案找不到

外掛程式使用 --plugin-dir 從其來源目錄運作，但安裝後失敗，出現關於路徑（例如 ../shared-utils）的錯誤。

Claude Code 將已安裝的外掛程式複製到其快取中，並從該處載入它，因此到達外掛程式自身目錄外的路徑在快取中指向空無。將共用檔案移到外掛程式目錄內，或透過其內的符號連結參考它們。如需快取位置和路徑解析方式，請參閱在磁碟上尋找外掛程式。

`${CLAUDE_PLUGIN_ROOT}` 在 Windows 上顯示正斜線

在 Windows 上，外掛程式 hook 接收 ${CLAUDE_PLUGIN_ROOT} 為 C:/Users/you/... 而不是 C:\Users\you\...，預期反斜線的指令碼會中斷。

Claude Code 在 Windows 上透過 Git Bash 執行 shell 形式的 hooks，並刻意以正斜線 Win32 形式替換外掛程式根目錄。Bash 內建、MSYS 工具和原生 Windows 二進位檔都接受該形式。

如果您的指令碼需要反斜線，請將 hook 切換為保留原生路徑的其中一種形式，如執行形式和 shell 形式下所述：

  • 執行形式的 hook，它使用 args 陣列直接產生程序
  • 具有 "shell": "powershell" 的 hook

外掛程式載入但其 skills 遺失

您的外掛程式列在 Installed 下，沒有錯誤，但當您輸入 / 時，不會提供其 skills。

Skills 從外掛程式根目錄的 skills/ 載入，命令從外掛程式根目錄的 commands/ 載入。只有 plugin.json 屬於 .claude-plugin/ 內，.claude-plugin/ 內的 skills/ 目錄不會被掃描。將目錄移到外掛程式根目錄，並執行 /reload-plugins。之後，外掛程式的詳細資訊窗格在 /plugin 中列出 skills，輸入 / 會提供它們。

每個 skill 是包含 SKILL.md 的目錄。資訊清單中指向 SKILL.md 檔案而不是其目錄的 skills 項目會報告為 path is a file; skills entries must be directories containing SKILL.md。

Skill 載入但 Claude 從不叫用該 skill

您外掛程式的 skill 在您輸入其 /<plugin>:<skill> 命令時執行，但 Claude 從不在回應純文字請求時叫用它。

按順序檢查這些原因：

  • Skill 設定 disable-model-invocation: true：設定該欄位後，只有您可以叫用該 skill。建立您的第一個外掛程式中的範本 skill 會設定它。從您想要 Claude 自行叫用的 skill 中移除該行。控制誰叫用 skill 涵蓋該欄位
  • 描述不符合人們的提問方式：完成Skill 未觸發中的檢查
  • 描述被截斷：安裝許多 skills 時，Claude Code 會縮短描述以符合列表的字元預算，這可能會去除 Claude 需要匹配請求的關鍵字。請參閱Skill 描述被截短

若要測量 skill 在現實提示中觸發的頻率，而不是逐一檢查，請使用 tool_used: Skill 評分器撰寫評估案例，並在每次描述變更後使用 claude plugin eval 執行它。

` is not a plugin or skill folder` 來自 `claude plugin eval init`

您從不是外掛程式根目錄的目錄（例如您的主目錄或保留外掛程式在子目錄中的儲存庫根目錄）執行了 claude plugin eval init。init 在工作目錄下寫入套件，因此它會停止，而不是建立外掛程式永遠看不到的 evals/ 目錄。

變更到外掛程式的根目錄，即保存 .claude-plugin/plugin.json 或 skill 的 SKILL.md 的目錄，然後再次執行命令。若要刻意在其他地方搭建套件，請傳遞 --eval-dir。請參閱使用評估測試外掛程式。

`userConfig` 對話框從不出現

您的外掛程式宣告 userConfig 選項，但安裝時不會出現設定對話框。

互動式安裝會顯示對話框，而 shell 命令改為將值作為旗標：

  • 在工作階段中的 /plugin install，或 /plugin 中的 Discover 標籤：對話框是此互動式安裝的一部分
  • 在您的 shell 中的 claude plugin install：永遠不會提示 userConfig 值。它會儲存您傳遞的任何 --config KEY=VALUE 值，當選項保持未設定時，它會列印 N userConfig options not yet set — run /plugin configure <plugin>@<marketplace> in Claude Code, or pass --config KEY=VALUE. 當任何未設定的選項是必需的時，(M required) 跟隨 not yet set。

如果您從 shell 安裝，請使用 --config 傳遞值，每個選項一個旗標：

claude plugin install my-plugin@my-marketplace --config api_url=https://example.com

當每個選項都設定時，安裝輸出不會包含 not yet set 行。若要之後改為開啟對話框，請在工作階段中執行 /plugin configure my-plugin@my-marketplace。

如果您傳遞資訊清單未宣告的 --config 鍵，外掛程式仍會安裝，命令會列印 ⚠ Installed, but --config not applied: --config key "<key>" isn't declared in this plugin's userConfig. 後面跟著外掛程式確實宣告的鍵。

`claude plugin validate` 報告錯誤

您執行了 claude plugin validate <path>，或在工作階段中執行了 /plugin validate <path>，它列印了 Found N errors 和 Validation failed，然後以代碼 1 結束。

驗證器讀取您提供的路徑處的資訊清單：外掛程式目錄的 .claude-plugin/plugin.json，或市集目錄的 .claude-plugin/marketplace.json。對於市集，它在項目自身資訊清單中的問題前加上項目索引，如 plugins[1] plugin.json → json: ...。

該表涵蓋停止驗證的訊息和兩個警告 No frontmatter block found 和 Unknown field '<key>'，只有在您傳遞 --strict 時才會停止。其他警告，例如遺失描述，未列出。

訊息 原因 修正
File not found: <path> 路徑沒有資訊清單，或不存在。 針對外掛程式或市集根目錄（包含 .claude-plugin/ 的目錄）執行命令。
No manifest found in directory. Expected .claude-plugin/marketplace.json or .claude-plugin/plugin.json 目錄沒有 .claude-plugin/ 資訊清單。 建立資訊清單，或指向正確的目錄。
Invalid JSON syntax: <parse error> 資訊清單或 hooks/hooks.json 不是有效的 JSON。 修正 JSON。在您修正 hooks/hooks.json 之前，工作階段會載入外掛程式而不包含該檔案中的 hooks。
Path not found: <path>. The runtime loader will report this as a load failure. 資訊清單中的元件路徑不存在。 修正路徑或建立目錄。
Path contains ".." which could be a path traversal attempt: <path> 元件路徑逃逸外掛程式目錄。 使用外掛程式根目錄內的路徑。
Path is a file; skills entries must be directories containing SKILL.md skills 項目指向 SKILL.md 而不是其目錄。 指向父目錄，或 . 表示根層級 SKILL.md。
No frontmatter block found 或 YAML frontmatter failed to parse: <error> Skill、agent 或命令檔案有遺失或無效的 YAML frontmatter。 在 --- 分隔符之間新增或修正 frontmatter。驗證外掛程式目錄時報告。
Unknown field '<key>' 資訊清單有結構描述未定義的欄位。 移除它，或使用訊息建議的名稱。Claude Code 在載入時忽略未知欄位。

在每次修正後再次執行命令，直到它不列印任何錯誤。

plugin.json 欄位在資訊清單參考上，市集層級訊息在市集驗證錯誤下。

`Plugin has conflicting manifests`

外掛程式無法載入，出現 Plugin <name> has conflicting manifests: both plugin.json and marketplace entry specify components.

外掛程式有其自身的 plugin.json，其市集項目設定 strict: false 同時也宣告 commands、agents、skills、hooks、outputStyles 或 themes 中的任何一個。從項目中移除這些欄位，或在項目中設定 strict: true，以便 Claude Code 將它們附加到 plugin.json。請參閱嚴格模式。

`Warning: No commands found in plugin custom directory`

當外掛程式載入時，claude --debug 日誌在 ~/.claude/debug/<session-id>.txt 記錄 Warning: No commands found in plugin <name> custom directory: <path>. Expected .md files or SKILL.md in subdirectories. 工作階段或 Errors 標籤中不會出現任何內容。

資訊清單中的 commands 路徑存在，但不包含 .md 檔案，也不包含子目錄中的 SKILL.md。新增命令檔案，或從資訊清單中移除路徑。

託管市集

您發佈市集，使用者報告錯誤，或您自己的驗證失敗。這些條目適用於市集所有者。

Plugins with relative paths fail in URL-based marketplaces

使用者使用 https://example.com/marketplace.json URL 新增了您的市集。其 source 是相對路徑（例如 ./plugins/my-plugin）的外掛程式安裝失敗，並顯示 its marketplace entry path does not stay inside the marketplace directory。已安裝的外掛程式無法載入，並顯示 Plugin source path refused。兩個訊息都有 錯誤參考條目。

當使用者使用 URL 新增市集時，Claude Code 僅下載 marketplace.json 檔案本身。它不會從該伺服器按相對路徑擷取外掛程式檔案，因此相對路徑中的條目指向從未擷取的目錄。為每個條目提供 Claude Code 可以自行擷取的來源，例如 GitHub 儲存庫：

{ "name": "my-plugin", "source": { "source": "github", "repo": "owner/repo" } }

或者，在 git 儲存庫中託管市集，並告訴使用者使用儲存庫 URL 新增它。對於 git 來源，Claude Code 複製整個儲存庫，因此相對路徑解析。來源類型在 市集參考 上。

Marketplace validation errors

您從市集目錄執行了 claude plugin validate .，它報告了市集檔案本身的錯誤或警告。

claude plugin validate 也驗證其 source 是本機路徑的每個條目，並在條目的 version 與外掛程式自己的清單不同時警告。

下表列出市集級別訊息。條目級別訊息是 claude plugin validate reports errors 下的外掛程式訊息，前綴為 plugins[N] plugin.json →。

訊息 種類 修復
Duplicate plugin name "<name>" found in marketplace 錯誤 為每個外掛程式提供唯一的 name。
Path contains "..": <path> 在 plugins[N].source 下 錯誤 使用相對於市集根目錄的路徑，沒有 .. 段。
Marketplace name cannot contain control or bidirectional-formatting characters 錯誤 從名稱中移除字元，例如逃逸或換行符。
Plugin name cannot contain control or bidirectional-formatting characters 錯誤 從外掛程式 name 中移除字元。
Marketplace has no plugins defined 警告 至少新增一個條目到 plugins。
No marketplace description provided 警告 新增頂級 description。
Plugin name "<name>" is not kebab-case 在 plugins[N] plugin.json → name 下 警告 重新命名為小寫字母、數字和連字號。Claude Code 接受其他形式，但 claude.ai 市集同步拒絕它們。
Entry declares version "<a>" but <path>/plugin.json says "<b>" 警告 更新條目以符合 plugin.json，在安裝時是權威的。
Marketplace name "<name>" is reserved in Claude Desktop 警告 重新命名市集。Claude Desktop 的受管市集同步拒絕任何大小寫的 org、org-provisioned 和 unknown。
Marketplace name "<name>" is not accepted by Claude Desktop 或 Plugin name "<name>" is not accepted by Claude Desktop 警告 重新命名為最多 128 個字元的字母、數字、.、_ 和 -，以字母或數字開頭。

在 v2.1.247 之前，包含控制或雙向格式化字元的市集名稱報告為 Marketplace name impersonates an official Anthropic/Claude marketplace。

被您的組織阻止

您的組織部署受管設定，限制外掛程式，命令被拒絕，並顯示政策訊息。這些條目命名每個拒絕背後的設定，因此您知道要求管理員什麼。對於管理員端，請參閱 為您的組織管理外掛程式。

`Marketplace source '' is blocked by enterprise policy`

您執行了 /plugin marketplace add、update 或安裝，Claude Code 拒絕了此行。對於 GitHub 或 git 來源，主機跟隨括號中的來源，如 'github:owner/repo' (github.com)。

您的管理員在受管設定中設定了 blockedMarketplaces 或 strictKnownMarketplaces，此來源不被允許。要求您的管理員允許來源，或新增訊息列出的允許來源之一。

將訊息的其餘部分與看到的內容相符，以查看什麼類型的政策阻止了來源：

  • Allowed sources: <list>：阻止來自 strictKnownMarketplaces 允許清單而不是 blockedMarketplaces 阻止清單
  • No external marketplaces are allowed.：strictKnownMarketplaces 允許清單為空
  • 提示速記假設 github.com 的 Tip:：允許清單允許 git 主機按主機名稱，您傳遞的 owner/repo 速記指向 github.com。如果儲存庫位於您的內部主機上，使用其完整 URL 再次新增它，例如 git@your-git-host.com:owner/repo.git

您在政策變得更具限制性之前新增的市集停止重新整理，因為政策在每次重新整理時適用。

`Marketplace "" is not in the allowed marketplace list`

Errors 標籤顯示此行，或 Marketplace "<name>" is blocked by enterprise policy，用於您已註冊的市集。

相同的受管設定，阻止 市集來源，在載入時適用。strictKnownMarketplaces 不包括此市集，或 blockedMarketplaces 命名它，因此 Claude Code 停止載入它及其外掛程式。對於允許清單變體，指導行顯示允許的來源，或 Contact your administrator to configure allowed marketplace sources。對於阻止清單變體，它讀取 This marketplace source is explicitly blocked by your administrator。

`Plugin "" is blocked by your organization's policy and cannot be installed`

安裝被拒絕，並顯示此行，啟用時顯示相同的行，以 cannot be enabled 結尾，或安裝或更新時顯示命名原因的行：Plugin "<name>" is from marketplace "<marketplace>", which is blocked by your organization's policy，或 Plugin "<name>" depends on "<dep>", which is blocked by your organization's policy。

受管設定阻止此外掛程式、其市集或它需要的依賴項。詢問您的管理員哪個條目適用。被阻止的依賴項表示外掛程式在依賴項的市集被允許前無法安裝。

`--plugin-dir is disabled by your organization's managed settings (disableSideloadFlags)`

您使用 --plugin-dir、--plugin-url、--agents 或 --mcp-config 啟動了 claude。Claude Code 以此訊息退出，並顯示 Plugins, custom agents, and MCP servers can only be loaded from sources your administrator has approved.

您的管理員在受管設定中設定了 disableSideloadFlags，這會關閉從任意路徑載入外掛程式、代理和伺服器的旗標。改為從核准的市集載入外掛程式，或要求您的管理員移除設定。

/plugin Errors 標籤中的相關訊息是 --plugin-dir copy of "<name>" ignored: plugin is locked by managed settings。受管設定按名稱啟用或停用該外掛程式，Claude Code 忽略您的 --plugin-dir 副本，因此旗標無法覆蓋政策。

`Plugins from ~/.claude/skills/ are blocked by your organization's managed settings`

您執行了 claude plugin init 或 claude plugin enable，它停止並顯示此行。訊息命名 strictKnownMarketplaces or blockedMarketplaces，並要求您的管理員將 {"source":"skills-dir"} 新增到 strictKnownMarketplaces 或從 blockedMarketplaces 中移除它。

skills-dir 來源代表 Claude Code 從您的 ~/.claude/skills/ 目錄載入的外掛程式。要求您的管理員進行訊息命名的變更。

`Command-sourced plugins are disabled by your organization's managed settings`

您安裝或更新了具有 command 來源的外掛程式，它停止並顯示此行和 The plugin was not installed or updated and its command was not run.

您的管理員設定了 disableCommandPluginSources，因此 Claude Code 拒絕執行市集宣告的產生外掛程式的命令。單獨設定 allowManagedHooksOnly 在 disableCommandPluginSources 未設定時具有相同的效果。詢問您的管理員外掛程式是否可以從政策允許的來源類型發佈。

`Marketplace '' is seed-managed`

您執行了 claude plugin marketplace update <name>，它失敗，並顯示 Marketplace '<name>' is seed-managed (<dir>) 和要求您詢問管理員的提示。

操作員透過 CLAUDE_CODE_PLUGIN_SEED_DIR 預先填充此市集，Claude Code 將種子管理的市集視為唯讀。批量 marketplace update 跳過它並更新其他的。

若要變更市集的內容，請詢問維護種子映像的人員更新它。有關程序，請參閱 種子容器和 CI。

後續步驟