在 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。
您运行了 /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 在查找前没有刷新市场，例如当您离线时，所以您的目录副本可能已过时。使用市场的名称刷新，然后再次安装：
/plugin marketplace update <marketplace>
claude plugin marketplace update 打印 Successfully updated marketplace: <name>，/plugin marketplace update 显示 ✔ Updated 1 marketplace。如果重试的安装打印相同的消息，请按照 not found in marketplace 无提示 描述检查名称。Claude Code 何时在安装前刷新市场 列出了刷新不运行的其他情况。
您安装了作为 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.
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 存储库再次添加市场
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.
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 Code 会话、编辑器和终端（在 ~/.claude/plugins/cache 下），然后再次运行安装
使用 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 字段和带有每个 type 的 errorDetails 字段：前两行是 dependency-unsatisfied，第三行是 dependency-version-unsatisfied。
插件已安装但不工作
安装成功，但插件的技能、hooks 或服务器没有做任何事情。从 插件不出现或其技能不显示 开始，它告诉您 Claude Code 在哪里报告它加载的内容，然后匹配消息。
插件不出现或其技能不显示
您安装了插件并键入 / 期望其技能，或要求 Claude 使用它，但什么都没有发生。
在更改任何内容之前检查插件的状态：
1
确认插件已安装并启用
运行 /plugin 并打开 Installed。确认插件已列出并启用。您的 shell 中的 claude plugin list 打印相同的列表，每个插件的版本、作用域和 Status: ✔ enabled。
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 以激活插件，或启动新会话
`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。
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 上。
插件捆绑了 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 下有其自己的条目
服务器已配置但永远不连接
运行 /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，它将其报告为错误。
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。
在你的 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 退出。
`Warning: No commands found in plugin 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 选项卡中不会出现任何内容。
`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.
96有几种命令拼写在使用中，但 Claude Code 没有。下表将每一个映射到真实命令。[插件命令参考](/docs/zh-CN/plugins/cli-reference) 列出了每个子命令和标志。96有几种命令拼写在使用中，但 Claude Code 没有。下表将每一个映射到真实命令。[插件命令参考](/docs/zh-CN/plugins/cli-reference) 列出了每个子命令和标志。
9797
98| 您键入的 | Claude Code 说什么 | 改为使用 |98| 您键入的 | Claude Code 说什么 | 改为使用 |
970| `Duplicate plugin name "<name>" found in marketplace` | 错误 | 给每个插件一个唯一的 `name`。 |970| `Duplicate plugin name "<name>" found in marketplace` | 错误 | 给每个插件一个唯一的 `name`。 |
972| `Marketplace name cannot contain control or bidirectional-formatting characters` | 错误 | 从名称中删除字符，例如转义或换行符。 |972| `Marketplace name cannot contain control or bidirectional-formatting characters` | 错误 | 从名称中删除字符，例如转义或换行符。 |
