在 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。
Cannot add marketplace "_internal": Claude Code cannot install plugins from a marketplace with this name. Each part of a plugin id (plugin@marketplace) may use only the letters a-z and A-Z, digits, ".", "_" and "-", and must start with a letter or digit. The name is set by "name" in the marketplace's marketplace.json; ask its maintainer to change it.
您运行了 /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 何时在安装前刷新市场 列出了刷新不运行的其他情况。
您的 shell 中的 claude plugin install 打印不同的消息。对于已在目标作用域安装的插件，它打印 Plugin "<name>@<marketplace>" is already installed (scope: user) 并以 0 退出。如果其缓存目录缺失，相同的命令重新下载它。
`"" was not installed: it would share its folder with ""`
您通过 claude plugin install、/plugin 或会话中的安装建议安装了插件，Claude Code 拒绝了它，显示此行或 would share its saved data with。
被拒绝的插件的 id 和已安装的插件的 id 映射到磁盘上的同一文件夹：一旦 . 和 @ 被写成 -，它们就是相同的。在 macOS 和 Windows 上，仅在大小写上不同的 id 也映射到同一文件夹。安装两者都会将一个插件的文件放在另一个的文件夹中，所以 Claude Code 拒绝并且已安装的插件保留其文件。
消息命名了出路：
其他插件已安装：消息说 Only one of the two can be installed. 并命名 claude plugin uninstall 命令，或 /plugin 中的卸载步骤，删除其他插件。运行它，然后再次安装。对于卸载删除和保留的内容，请参阅 卸载删除和保留的内容。
两个 id 在一次安装中到达，例如插件及其需要的依赖项：没有安装顺序有帮助。只有列出这两个插件的市场的维护者可以通过重命名其中一个来修复它。当两者来自不同的市场时，任一个的维护者都可以。
`This plugin uses a source type your Claude Code version does not support`
您安装了一个插件，其市场条目使用此版本 Claude Code 无法获取的源类型，Claude Code 停止并显示此消息和 Update Claude Code and try again.
您安装了作为 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.
"github:acme/formatter" was not installed: it is not an http or https link. An npm plugin source must name a registry package (name or name@version) or link to a tarball file. For a plugin in a git repository, use a "github", "url" or "git-subdir" source.
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 仓库再次添加市场
该市场在 ~/.claude/plugins/known_marketplaces.json 中有条目，但该条目未通过 Claude Code 每次读取该文件时运行的检查，因此该市场以及从它安装的插件停止加载。在您的 shell 中，claude plugin list 会为每个受影响的插件报告一行，指出原因和修复方法：
Marketplace team-tools is added but ignored. Its location is on a network drive, has "." or ".." in its path, or couldn't be checked. Re-add the marketplace (one added from a folder or file must be re-added from a copy on this computer), or, to trust a folder on a network drive, declare it under extraKnownMarketplaces in user or managed settings.
Its location is on a network drive, has "." or ".." in its path, or couldn't be checked，或关于 The folder or file it was added from 的相同句子：市场的目录或添加它时所用的本地路径位于网络位置、路径中包含 . 或 .. 段，或无法检查
Its git URL can't be used: <reason> 或 Its URL can't be read as an https:// or http:// address：条目记录的源 URL 是 Claude Code 拒绝从中克隆或获取的 URL
Its source doesn't match its extraKnownMarketplaces entry in user or managed settings：该条目与同名的 extraKnownMarketplaces 声明不匹配
当 (see the debug log) 代替原因出现在 is added but ignored 之后时，Claude Code 拒绝了该市场的名称，例如 保留名称的另一种拼写。调试日志 会指出该条目。
处理方法：
按照消息中的修复方法操作。在您的 shell 中，运行 claude plugin marketplace remove <name>，然后从受支持的源或本地路径再次添加该市场，并重新安装其插件（remove 命令会卸载这些插件）。remove 命令对被忽略的条目同样有效
在 v2.1.286 之前，无论原因是什么，claude plugin list 都将此类市场报告为 Marketplace <name> not found，而 /pluginErrors 选项卡将其报告为 Marketplace "<name>" is registered but was refused (see the debug log)。原因仅出现在调试日志中。在 v2.1.286 中，原因和修复句子使用了不同的措辞，例如 Its recorded location is network-shaped or unclassifiable (never probed)。
`Plugin has a corrupt manifest file` 或 `has an invalid manifest file`
Claude Code 获取了插件，然后无法读取其 .claude-plugin/plugin.json。在 shell 中，此行中的 <name> 可以是临时目录名称；Failed to install plugin "<name>@<marketplace>" 前缀携带插件的真实名称。措辞说明哪个检查失败：
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.
在 v2.1.287 之前，该消息为 Cannot add marketplace "<name>": its network source differs from the one declared for it in settings (kind, target, or a fetch-shaping field such as headers / ref / path / sparsePaths)。
`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 `
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 以激活插件，或启动新会话
were not installed, because ...：此插件无法运行安装，注释会说明原因，例如 Yarn、pnpm 或 bun.lockb lockfile，或者其包管理器未安装在此计算机上的 lockfile。只要该原因存在，更新插件就不会安装这些包。如果原因是 lockfile，插件作者必须替换它。如果是缺少包管理器，请安装它，然后更新插件
`Plugin "" not cached at `
Errors 选项卡显示此行，指导为 Run /plugin to refresh the plugin cache。Claude Code 有插件的安装记录，但记录指向的目录缺失，例如在您清除缓存后。
`installed_plugins.json holds a record under "" that this version of Claude Code cannot read`
消息以这些形式出现：
claude plugin list：将其打印为 Note:
claude plugin install、uninstall 和 update：拒绝并显示 Plugin "<name>" was not installed:、Plugin "<name>" was not uninstalled: 或 Plugin "<name>" was not updated:，后跟相同的文本
`install records under names that no version of Claude Code can use were removed from installed_plugins.json`
claude plugin list 打印此注释，带有副本的路径，名为 installed_plugins.set-aside.<date>.<hash>.json，只要该副本位于 installed_plugins.json 旁边。注释以 Nothing needs doing about these copies. 结尾。
installed_plugins.json 中的记录位于不是有效插件 id 的键下，因此没有版本的 Claude Code 可以使用它。文件的其余部分正常加载。
Claude Code 将不可用的记录复制到 .set-aside 文件中并将其从列表中删除。Claude Code 永远不会读回副本，副本在 cleanupPeriodDays 计划上老化。
`does not load (...), so Claude Code ignores the whole file`
修复警告中指明的错误。对于 Claude Code 不接受的值，修复损坏的设置文件 说明了修复方法。然后，如果命令所做的更改已不在文件中，请再次运行该命令。
该警告出现在您的 shell 中 claude plugin install、enable、disable 或 claude plugin marketplace add 的成功行之后：
⚠ /home/user/.claude/settings.json does not load (its "permissions" is not valid), so Claude Code ignores the whole file, including anything this command wrote there. Fix the file, then run this command again if its change is missing. If a newer Claude Code wrote the file, update Claude Code instead.
括号中的文本指明了错误：
its "<key>" is not valid：引号中的设置项包含 Claude Code 不接受的值。在 设置参考 中查找该设置项可接受的值。当多个值无效时，文本会指明第一个设置项并统计其他设置项的数量，例如 its "permissions" and 1 other value are not valid。
it is not a JSON object：文件的顶层不是 JSON 对象，例如顶层为数组的文件。
`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 上。
即使消息提示重新安装，也请先在 Claude Code 输入框中运行 /reload-plugins。当您的会话加载插件 hook 所用的目录已从磁盘上消失时，插件的 hook 会失败并显示 Failed to run: Plugin directory does not exist: <path> (<plugin> — run /plugin to reinstall)，且该 hook 不会运行。Plugin directory not found at path: <path> 是另一条消息，与市场条目有关。
要读取服务器在启动时打印的错误，请运行 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. 当任何未设置的选项为必需项时，not yet set 后面会跟上 (M required)。
如果您从 shell 安装，请使用 --config 传递值，每个选项一个标志：
claude plugin install my-plugin@my-marketplace--config api_url=https://example.com
如果您传递了清单未声明的 --config 键，插件仍会安装，命令会打印 ⚠ Installed, but --config not applied: --config key "<key>" isn't declared in this plugin's userConfig.，后跟插件已声明的键。
对于附带自身声明了 user_config 的MCPB 包文件的插件，消息会改为 isn't declared in this plugin's userConfig or by its bundled MCP servers.，已知的键包括该服务器的键，写作 <server>.<key>。清单通过 URL 引用的包在安装时不会被读取，因此其键不会被列出，消息会提示在 /plugin 中进行配置。设置 <server>.<key> 键需要 Claude Code v2.1.285 或更高版本。
`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 选项卡中不会显示任何内容。
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 中删除字符。
Claude Code cannot install plugins from marketplace "<name>". Each part of a plugin id (plugin@marketplace) may use only the letters a-z and A-Z, digits, ".", "_" and "-", and must start with a letter or digit. Change the marketplace's "name".
错误
将市场重命名以符合消息所述的规则。
Claude Code cannot install plugin "<name>". Each part of a plugin id (plugin@marketplace) may use only the letters a-z and A-Z, digits, ".", "_" and "-", and must start with a letter or digit. Change this entry's "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.ai 市场同步需要该形式。
Entry declares version "<a>" but <path>/plugin.json says "<b>"
警告
更新条目以匹配 plugin.json，这在安装时是权威的。
Marketplace name "<name>" is reserved in Claude Desktop
`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.
249Cannot add marketplace "_internal": Claude Code cannot install plugins from a marketplace with this name. Each part of a plugin id (plugin@marketplace) may use only the letters a-z and A-Z, digits, ".", "_" and "-", and must start with a letter or digit. The name is set by "name" in the marketplace's marketplace.json; ask its maintainer to change it.
819⚠ /home/user/.claude/settings.json does not load (its "permissions" is not valid), so Claude Code ignores the whole file, including anything this command wrote there. Fix the file, then run this command again if its change is missing. If a newer Claude Code wrote the file, update Claude Code instead.
820```
821
822括号中的文本指明了错误：
823
824* **`its "<key>" is not valid`**：引号中的设置项包含 Claude Code 不接受的值。在 [设置参考](/docs/zh-CN/settings-reference) 中查找该设置项可接受的值。当多个值无效时，文本会指明第一个设置项并统计其他设置项的数量，例如 `its "permissions" and 1 other value are not valid`。
825* **`it is not a JSON object`**：文件的顶层不是 JSON 对象，例如顶层为数组的文件。
934即使消息提示重新安装，也请先在 Claude Code 输入框中运行 `/reload-plugins`。当您的会话加载插件 hook 所用的目录已从磁盘上消失时，插件的 hook 会失败并显示 `Failed to run: Plugin directory does not exist: <path> (<plugin> — run /plugin to reinstall)`，且该 hook 不会运行。[`Plugin directory not found at path: <path>`](#plugin-directory-not-found-at-path) 是另一条消息，与市场条目有关。
