如何安装 Claude Code 插件

本指南讲解如何安装 Claude Code 插件，涵盖 Claude Code 支持的全部三种方式：在正在运行的会话里输入一行命令、在 shell 中执行两条命令，或者从本地文件夹临时加载。示例使用 ClaudeMods 插件市场（rotbit/claudemods-marketplace）和 cm-git-branch 插件；换成任何其他插件的名称同样适用。

插件（mod）本质上就是 Claude Code 的 plugin，所以用到的命令就是你可能已经熟悉的 plugin 命令。本站每个插件页面都有一个安装代码块，会自动帮你填好正确的名称。

安装插件之前需要准备什么？#

先检查你的版本：

claude --version

终端中需要 Claude Code 2.1.287 或更高版本。桌面应用从 2.1.286 起即可运行插件。如果你的版本较旧，请先更新 Claude Code 再继续；更早的版本无法运行插件。

如果你所在的公司统一管理 Claude Code，管理员可能把插件限制在一份审批通过的列表内。如果某个插件在工作环境中无法加载，请联系负责管理你设置的人。

方式一：在 Claude Code 内用一行命令安装#

在任意会话中输入：

/plugin install cm-git-branch --marketplace rotbit/claudemods-marketplace

只写插件名本身，不要带 @ 后缀。如果 Claude Code 还不认识这个插件市场，它会先请你确认，然后自动添加市场、安装插件，并把插件加载到当前会话中。这种写法需要 Claude Code 2.1.275 或更高版本，而任何能运行插件的版本都已满足这一要求。

注意，单独输入 /plugin install rotbit/claudemods-marketplace 是行不通的：不带 --marketplace 时，参数必须是 plugin@marketplace 的形式，否则会收到 "marketplace not found" 错误。

方式二：在 shell 中安装#

先添加一次插件市场，之后就可以从中安装任意数量的插件：

claude plugin marketplace add rotbit/claudemods-marketplace
claude plugin install cm-git-branch@claudemods

@ 后面的文字是插件市场在其 marketplace.json 中定义的名称（claudemods），而不是仓库名。marketplace add 执行成功后的提示信息会告诉你该用哪个名称。

这两条命令默认都写入你的用户设置，因此插件在所有项目中都可用。使用 --scope project 可以把插件共享给整个仓库，使用 --scope local 则只在某个项目中供你自己使用：

claude plugin install cm-git-branch@claudemods --scope project

已经打开的会话看不到新安装的插件，需要在其中运行：

/reload-plugins

如果你更喜欢点选操作，可以在会话中输入 /plugin install cm-git-branch@claudemods，它会在插件菜单中打开该插件的详情视图，你可以在那里选择安装范围。

方式三：不安装，直接试用插件#

想从本地文件夹试用插件（例如克隆下来的仓库，或你正在编写的插件），可以只为单个会话加载它：

claude --plugin-dir ./cm-git-branch

这样不会向你的设置写入任何内容。插件的 id 为 cm-git-branch@inline，退出后即消失。--plugin-dir 可以传入多次，而且保存对 hooks 模块的修改后会自动重新加载，无需重启。要确认加载了哪些内容，运行：

claude --plugin-dir ./cm-git-branch plugin list

输出中有一个 "Session-only plugins" 部分，显示插件的版本和已加载状态。这也是审查插件最安全的方式：先运行 claude plugin validate ./cm-git-branch，再仔细阅读输出中的 hooks: 和 calls: 两行。

如何确认插件正在运行？#

打开 /plugin。在标签页下方，会有一行暗色文字，例如 1 mod active · cm-git-branch，列出已加载的插件。在 shell 中，claude plugin list 会显示已安装的 plugin 以及每个是否已启用；在脚本中使用时可以加上 --json。

如果插件出现在列表中却什么也看不到，请检查你是在哪里运行的。插件只会在终端和桌面应用的 Code 标签页中绘制界面。在 VS Code 聊天面板中或使用 claude -p 时，hooks 依然会运行，但不会显示任何界面。

如何配置插件？#

大多数插件都声明了带默认值的选项。刚安装完时，Claude Code 可能会输出一行提示，说某些 userConfig 选项尚未设置。这是正常现象，默认值会生效。

要修改某个选项，可以在会话中打开 /config 找到该插件对应的行，或者使用 /plugin configure。插件会以新的值重新加载。在 shell 中，你可以在安装时直接设置选项：

claude plugin install cm-git-branch@claudemods --config hideWhenClean=true

也可以之后通过管道传入一个值均为字符串的 JSON 对象：

echo '{"intervalMs": "5000"}' | claude plugin configure cm-git-branch --values-stdin

没有写到的选项会保留当前值。不带该参数直接运行 claude plugin configure cm-git-branch，会列出所有选项以及哪些尚未设置。每个插件页面都会在“自定义”一节下用表格列出它的选项。

如何更新、停用或卸载插件？#

从插件市场更新到最新版本：

claude plugin update cm-git-branch@claudemods

新版本会在下一个会话中加载，或者在运行 /reload-plugins 后立即生效。

在不删除的前提下关闭插件，以及重新开启：

claude plugin disable cm-git-branch
claude plugin enable cm-git-branch

在会话中，/plugin disable cm-git-branch 的效果相同。如果插件不是安装在 user 范围，请加上 -s project（或 user、local）。

彻底删除插件：

claude plugin uninstall cm-git-branch

传入 --keep-data 可以保留插件的数据目录，传入 --prune 则会同时删除那些自动安装、且已不再需要的依赖。缓存副本会在稍后清理；运行 claude plugin prune 可以立即清理。

要在单个会话中关闭所有插件，可以用 claude --safe-mode 启动 Claude Code。要让它们一直保持关闭，请在设置中写入 "disableAllHooks": true。

插件无法加载时如何排查？#

请按以下顺序逐项检查：

• 版本。 claude --version 必须是 2.1.287 或更高版本。
• 重新加载。 从 shell 安装或更新后，运行 /reload-plugins 或开启新会话。
• 已启用。 插件必须在 /plugin 的 Installed 标签页中处于启用状态。被停用的插件虽已安装，但不会加载。
• 名称。 claude plugin install 需要 plugin@marketplace-name 形式的参数。运行 claude plugin marketplace list 查看你已添加的市场名称。
• 运行环境。 在 VS Code 聊天面板、claude -p 或 Agent SDK 中不显示界面，属于预期行为。
• 策略。 托管设置可能把插件限制在审批列表内，或禁止使用 --plugin-dir。
• 冲突。 两个插件写入同一位置（例如状态栏）时，可能会互相遮挡。逐个停用即可找出问题所在。

如果插件仍然表现异常，请查看它的页面上是否有已知问题，或者附上你的 Claude Code 版本以及对插件文件夹运行 claude plugin validate 的输出来反馈问题。完整的命令参考见 plugin CLI 文档。刚接触插件？先了解什么是 Claude Code 插件，再从插件目录中挑一个试试。