<name>。
无论您是安装插件、构建插件、托管市场还是为组织管理插件，都可以使用此页面。
这些情况在其他页面上有介绍：
- 为什么作用域、缓存和优先级的行为方式如此：阅读 Plugin loading reference
- 查找标志、字段或命令：使用 plugin commands reference、manifest reference 或 marketplace reference
查找 /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 会打开 Manage plugins 对话框。
从您所在的表面安装插件：
- Claude 桌面应用、本地或 SSH 会话：点击提示旁边的 + 按钮，然后点击 Plugins，然后点击 Add plugin 打开 插件浏览器
- VS Code 扩展：使用 安装插件 下的 VS Code 选项卡
- 网络上的 Claude Code 或桌面云会话：云会话没有插件浏览器。有关云会话加载的内容，请参阅 安装插件 下的 Cloud session 选项卡
- 您有权访问的终端：运行
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 提示符处。启动一个会话并在那里键入相同的命令：
✓ 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 进行操作，然后重试插件命令。
Unknown command 和不存在的命令拼写
您键入了在某处看到的插件命令，并在会话中收到 Unknown command: /<name>，或从 shell 中的 claude 二进制文件收到 error: unknown command '<name>' 或 error: unknown option '<flag>'。
有几种命令拼写在使用中，但 Claude Code 没有。下表将每一个映射到真实命令。插件命令参考 列出了每个子命令和标志。
这些拼写看起来不对但有效：
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 命令永远不会为您注册它。
添加它，然后重试安装：
Successfully added marketplace: claude-plugins-official，/plugin marketplace list 显示带有其源的市场。
对于此消息中的任何其他市场名称，请参阅 Marketplace "<name>" not found。
相同的字符串也出现在 /plugin Errors 选项卡中，即面板的加载失败列表，当您的设置中列出的插件命名您未添加的市场时。
Marketplace "<name>" not found
您在会话中运行了 /plugin install <plugin>@<name>，通常来自某人发送给您的安装行，Claude Code 报告它没有该名称的市场。
如果名称以 claudeai- 开头，市场托管在 claude.ai 上，您可以从 shell 中使用 claude plugin marketplace add --claudeai <name> 按名称添加它。请参阅 从 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://URLuser@host:pathSSH URL- 以
./、../、/或~开头的本地路径
claude-plugins-official）不匹配任何一个。裸主机名（例如 marketplace.anthropic.com）也不匹配。
以接受的形式之一重新键入源：
Successfully added marketplace: <name>。
'<source>' 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或绝对路径
Successfully added marketplace: <name>。
Path does not exist: <path>
您将本地路径传递给 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 <path>/.claude-plugin/marketplace.json
Claude Code 克隆或下载了市场，但在其内部的预期路径中找不到 marketplace.json。添加命令将其报告为 Failed to add marketplace: Marketplace file not found at ...。
默认位置是存储库根目录中的 .claude-plugin/marketplace.json，市场参考 列出了接受的位置。
修复因所有者和其他人而异：
- 您拥有市场：将文件放在该位置并重新添加市场
- 其他人托管它：向所有者询问他们发布的确切源
SSH authentication failed 或 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 克隆，因此它拒绝您尚未接受其密钥的主机，而不是自动接受密钥。从您的终端连接一次以接受指纹，然后重试：
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 秒。对于大型存储库或缓慢的连接，提高限制。该值以毫秒为单位：
- Bash 或 Zsh
- PowerShell
claude plugin marketplace add <source> --sparse <paths> 限制检出到您命名的目录。
市场更新在离线时持续失败
您在市场的 git 主机无法访问的环境中工作，每个会话都在后台重复失败的刷新。您现有的市场检出保持原位，启动不会延迟。 每个会话，对于 启用自动更新 的市场，Claude Code 在后台检查市场的 git 主机是否有新提交。当该检查无法到达主机时，它尝试再次克隆市场，离线时该克隆也失败。 设置此变量以跳过重新克隆尝试，并在检查无法到达主机时继续使用现有检出：- Bash 或 Zsh
- PowerShell
.claude-plugin/marketplace.json 的检出跳过重新克隆。从未克隆或其克隆停止中途的市场仍然获得克隆尝试，因此请在在线时添加一次。
对于完全离线部署，改为在镜像构建时使用 CLAUDE_CODE_PLUGIN_SEED_DIR 预填充插件目录，遵循 种子容器和 CI。
市场添加在 GitHub Enterprise Server 主机上失败
您从 GitHub Enterprise Server (GHES) URL 添加了市场并收到策略错误，或您从 claude.ai 添加了它并收到 GitHub 访问错误。 两种情况都在 GHES 页面上：- 策略错误 意味着您的组织限制了市场源，管理员需要为主机添加
hostPattern - claude.ai 上的 GitHub 访问错误 意味着您自己的 GitHub Enterprise 帐户尚未连接
安装插件
您添加了市场并运行了安装，安装停止并显示消息而不是安装任何东西。这些条目涵盖了这些消息。它们还涵盖了稍后出现在/plugin Errors 选项卡中的相关消息，或当插件或其市场无法找到、读取或信任时的空 Discover 选项卡。
Plugin "<name>" not found in marketplace "<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 带有刷新提示
提示读取 Your local copy may be out of date — try claude plugin marketplace update <marketplace> 或 The marketplace couldn't be refreshed (...)。Claude Code 在查找前没有刷新市场，例如当您离线时，所以您的目录副本可能已过时。使用市场的名称刷新，然后再次安装：
claude plugin marketplace update 打印 Successfully updated marketplace: <name>，/plugin marketplace update 显示 ✔ Updated 1 marketplace。如果重试的安装打印相同的消息，请按照 not found in marketplace 无提示 描述检查名称。Claude Code 何时在安装前刷新市场 列出了刷新不运行的其他情况。
not found in marketplace 无提示
名称是最可能的问题。打开 /plugin，转到 Discover，并从列表中复制名称。
在 v2.1.232 之前，Claude Code 仅在查找失败后刷新命名的市场，并且仅当为其启用了自动更新时。
Plugin "<name>" 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 在查找插件前刷新它：
✓ Installed <plugin>.，或从 claude plugin install 看到 Successfully installed plugin: <plugin>@<marketplace>。
如果您不知道哪个市场列出了插件，请运行 /plugin marketplace list 查看您拥有的市场，并在 /plugin 中浏览 Discover 查找插件名称。
Plugin '<name>@<marketplace>' is already installed globally
您为已在用户作用域或通过托管设置安装的插件运行了 /plugin install，Claude Code 拒绝了 Use '/plugin' to manage existing plugins.。如果您键入了没有 @<marketplace> 的插件名称，消息会省略 globally。
插件已在每个项目中可用，因此没有什么可添加的。要更改其 作用域、启用或禁用它，或配置它，请打开 /plugin 并转到 Installed。
仅在项目或本地作用域安装的插件不会触发此消息。Claude Code 允许您也在用户作用域安装它，因此它在其他项目中可用。
您的 shell 中的 claude plugin install 打印不同的消息。对于已在目标作用域安装的插件，它打印 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 源，下载文件的摘要与引脚不匹配。
完整消息如下所示：
- 您发布插件：重新计算 URL 提供的确切文件的摘要，并更新市场条目中的
sha256。使用shasum -a 256 my-plugin.zip，或在 PowerShell 中使用Get-FileHash -Algorithm SHA256 my-plugin.zip - 您安装插件：在会话中运行
/plugin marketplace update <name>以刷新目录以防条目已更正，然后重试安装。如果刷新后摘要仍然不同，请在安装前询问市场所有者他们引脚了哪个文件
Marketplace "<name>" is registered from an untrusted source
您之前添加的市场停止加载，其插件也停止加载。此行出现在 /plugin Errors 选项卡中或下一次刷新时。
市场以 为官方 Anthropic 市场保留 的名称注册，但其注册源不是 anthropics GitHub 存储库。每次市场加载或刷新时都会重新检查保留名称，因此市场和从它安装的插件停止加载。
完整消息命名保留名称和修复：
- 您使用市场：在您的 shell 中，运行
claude plugin marketplace remove <name>，然后从官方github.com/anthropics存储库再次添加市场 - 您发布在其名称成为保留之前使用该名称的第三方市场：重命名它并要求用户从您的源重新添加它
Plugin <name> has a corrupt manifest file 或 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:：文件不是有效的 JSONinvalid 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: <path>
/plugin 中的 Errors 选项卡显示这个用于启用的插件，其市场通过相对路径列出，例如 ./plugins/my-plugin，当市场内该路径处不存在目录时。如果您维护市场，请更正条目的 source 路径或恢复文件夹。否则，向市场所有者报告消息。
Marketplace directory not found at path: <path> 意味着市场自己的目录缺失。对于您从本地路径添加的市场，该目录已移动或被删除。恢复它，或删除市场并从其新位置再次添加它。
No plugins available 或 No marketplaces configured
您打开了 /plugin，Discover 选项卡为空，或 claude plugin marketplace list 打印 No marketplaces configured。
没有注册市场，因此没有目录可显示。在会话中，添加官方市场 anthropics/claude-plugins-official：
Successfully added marketplace: claude-plugins-official，Discover 列出其插件。Anthropic 市场 页面列出了您可以添加的其他市场。
Marketplace "<name>" is already added from a different source
您通过 /plugin install <plugin> --marketplace <source> 确认添加市场，Claude Code 从该源获取的目录与您已从不同源添加的市场具有相同的名称。Claude Code 保留现有市场而不是替换它，插件未安装。
完整消息如下所示：
- 您已添加的市场：使用
/plugin install <plugin>@<name>按名称从它安装 - 新源：运行
/plugin marketplace remove <name>，然后重试安装
Cannot add marketplace "<name>": 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> (<reason>)
您在 /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 <path>
当您安装插件时，Claude Code 下载其文件的新副本并将其移动到 插件缓存 中该版本的文件夹中。此消息意味着移动失败，通常是因为另一个程序在安装运行时使用了该文件夹。文件系统代码出现在括号中：
The previously installed copy was moved back：您拥有的版本仍然安装had to be removed first、was not moved back或could not be moved back：该插件版本在安装成功之前未安装- 没有这样的句子：没有早期副本，因此版本尚未安装
could not be replaced 并且 It was not replaced and the new copy was discarded，因此您拥有的版本仍然安装。
Left on disk 列表命名缓存内的搁置文件夹。稍后安装该版本或插件缓存清理会删除它们，因此您不需要删除它们。
要修复安装：
- 关闭使用插件文件夹的其他 Claude Code 会话、编辑器和终端（在
~/.claude/plugins/cache下），然后再次运行安装 - 当消息说检查插件缓存文件夹的权限时，恢复您对其命名的文件夹的写入权限并释放磁盘空间，然后再次运行安装
依赖项错误
声明依赖项的插件在无法满足依赖项时可能无法安装或安装并保持禁用。消息在安装时或加载时到达您：- 在安装期间：拒绝作为安装的错误消息返回
- 当插件加载时：问题出现在
claude plugin list和/pluginErrors 选项卡中，Claude Code 保持受影响的插件禁用，直到您解决它
要以编程方式查看这些，请在您的 shell 中运行
claude plugin list --json。有问题的插件携带带有消息的 errors 字段和带有每个 type 的 errorDetails 字段：前两行是 dependency-unsatisfied，第三行是 dependency-version-unsatisfied。
插件已安装但不工作
安装成功，但插件的技能、hooks 或服务器没有做任何事情。从 插件不出现或其技能不显示 开始，它告诉您 Claude Code 在哪里报告它加载的内容，然后匹配消息。插件不出现或其技能不显示
您安装了插件并键入/ 期望其技能，或要求 Claude 使用它，但什么都没有发生。
在更改任何内容之前检查插件的状态：
1
确认插件已安装并启用
运行
/plugin 并打开 Installed。确认插件已列出并启用。您的 shell 中的 claude plugin list 打印相同的列表，每个插件的版本、作用域和 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以激活插件，或启动新会话
/reload-plugins。
在 v2.1.246 之前，该摘要中的技能计数仅包括插件的 commands/ 条目，因此重新加载可以加载插件的 SKILL.md 技能并仍然报告 0 skills。
Plugin "<name>" not cached at <path>
Errors 选项卡显示此行，指导为 Run /plugin to refresh the plugin cache。Claude Code 有插件的安装记录，但记录指向的目录缺失，例如在您清除缓存后。
从您的 shell 重新安装插件。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 "<name>" 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 中运行命令，然后重新加载：
/reload-plugins 后，Errors 选项卡条目消失，插件列在 Installed 下。
如果您的组织为您预安装插件，它通过托管设置而不是这样做。请参阅 预安装和要求插件。
Failed to load hooks from <path> 和不触发的 hooks
插件的 hooks 不运行。要么 Errors 选项卡显示它们的加载失败，hooks 加载且您在成绩单中看到 <Event> hook error 通知，要么 hook 加载无错误且永远不触发。
Hooks 无法加载
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 通知
形式为 ... 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 加载但永远不触发
如果 hook 加载无错误但永远不触发，检查其定义然后观看它运行：1
检查事件名称
事件名称区分大小写，因此确认您的完全匹配，例如
PostToolUse。2
检查匹配器
确认 hook 的
matcher 匹配工具名称。3
故意触发事件
对于
PostToolUse hook，要求 Claude 编辑文件。4
阅读调试日志
打开 调试日志，它记录哪些 hooks 匹配。运行的 hook 显示在那里及其退出代码。
Invalid MCP server config for "<server>" 和不启动的 MCP 服务器
插件捆绑了 MCP 服务器，Errors 选项卡显示 Invalid MCP server config for "<server>": <error>，或服务器已列出但 /mcp 永远不显示它已连接。
Invalid MCP server config for "<server>": <error>
服务器的配置通过架构检查，但 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 下有其自己的条目
服务器已配置但永远不连接
运行/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。
服务器使用 --plugin-dir 工作但安装后失败
您是插件的作者，当您使用 --plugin-dir 从其源目录加载插件时服务器启动，但一旦插件安装就失败。
Claude Code 将已安装的插件复制到其缓存中，因此仅从源目录工作的路径会中断。使用 ${CLAUDE_PLUGIN_ROOT} 编写插件内的路径。
对于到达插件目录外的路径，请参阅 插件引用的文件在其目录外找不到。
语言服务器不启动、使用过多内存或报告错误的诊断
您安装了 代码智能插件，Claude 没有看到诊断，或语言服务器使用过多内存或报告不是真实的错误。语言服务器不启动
插件连接到您单独安装的语言服务器二进制文件，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。然后启动新会话。
语言服务器使用过多内存
语言服务器（例如rust-analyzer 和 pyright）索引整个项目。使用 /plugin disable <plugin> 在会话中禁用插件，改为依赖 Claude 的内置搜索工具。
monorepo 中的假阳性诊断
未为工作区配置的语言服务器可以报告内部包的未解析导入。Claude Code 端没有什么可修复的，诊断不会阻止 Claude 编辑代码。构建插件
你正在开发插件并使用--plugin-dir 加载它或从本地市场安装它。这些条目涵盖了你在开发插件时遇到的失败。要在每次更改后运行检查，请参阅测试和调试。
两个也会影响插件用户的失败在插件已安装但无法工作下有相应条目：
- 未触发的 hook：请参阅未触发的 hook
- 无法启动的 MCP 服务器：请参阅无法启动的 MCP 服务器
commands path not found: <path>
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 将市场根目录作为一个以该目录命名的空插件加载。将标志指向插件目录本身：
/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 形式的 hook，并故意以正斜杠 Win32 形式替换插件根目录。Bash 内置命令、MSYS 工具和本机 Windows 二进制文件都接受该形式。
如果你的脚本需要反斜杠，请将 hook 切换到保留本机路径的形式之一，如执行形式和 shell 形式下所述：
- 执行形式的 hook，它使用
args数组直接生成进程 - 带有
"shell": "powershell"的 hook
插件加载但其 skills 缺失
你的插件在 Installed 下列出，没有错误，但当你输入/ 时，不会提供其 skills。
Skills 从插件根目录的 skills/ 加载，commands 从插件根目录的 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 描述被截断
tool_used: Skill grader 编写一个 eval 案例，并在每次描述更改后使用 claude plugin eval 运行它。
<directory> 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。请参阅使用 evals 测试插件。
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后面。
--config 传递值，每个选项一个标志：
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 时它们才会停止。其他警告，如缺少描述，未列出。
在每次修复后再次运行命令，直到它不打印任何错误。
plugin.json 字段在清单参考上，市场级消息在市场验证错误下。
Plugin <name> 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 <name> custom directory
当插件加载时，~/.claude/debug/<session-id>.txt 处的 claude --debug 日志记录 Warning: No commands found in plugin <name> custom directory: <path>. Expected .md files or SKILL.md in subdirectories. 会话或 Errors 选项卡中不会出现任何内容。
清单中的 commands 路径存在但不包含 .md 文件，也不包含子目录中的 SKILL.md。添加 command 文件，或从清单中删除路径。
托管市场
您发布市场，用户报告错误，或您自己的验证失败。这些条目适用于市场所有者。相对路径的插件在基于 URL 的市场中失败
用户使用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 存储库：
市场验证错误
您从市场目录运行了claude plugin validate .，它在市场文件本身上报告了错误或警告。
claude plugin validate 也验证其 source 是本地路径的每个条目，并在条目的 version 与插件自己的清单不同时警告。
表格列出了市场级消息。条目级消息是 claude plugin validate 报告错误 下的插件消息，前缀为 plugins[N] plugin.json →。
在 v2.1.247 之前，包含控制或双向格式化字符的市场名称仅报告为
Marketplace name impersonates an official Anthropic/Claude marketplace。
被您的组织阻止
您的组织部署了限制插件的托管设置，命令被拒绝，显示策略消息。这些条目命名每个拒绝背后的设置，以便您知道要求管理员什么。对于管理员端，请参阅 为您的组织管理插件。Marketplace source '<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允许列表为空- 一个
Tip:说简写假设 github.com：允许列表允许 git 主机按主机名，您传递的owner/repo简写指向 github.com。如果存储库位于您的内部主机，使用其完整 URL 再次添加它，例如git@your-git-host.com:owner/repo.git
Marketplace "<name>" 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 "<name>" 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 '<name>' is seed-managed
您运行了 claude plugin marketplace update <name>，它失败，显示 Marketplace '<name>' is seed-managed (<dir>) 和要求您的管理员的提示。
操作员通过 CLAUDE_CODE_PLUGIN_SEED_DIR 预填充了此市场，Claude Code 将种子管理的市场视为只读。批量 marketplace update 跳过它并更新其他。
要更改市场的内容，要求维护种子镜像的人更新它。有关该过程，请参阅 种子容器和 CI。