什么是 Claude Code 插件？

什么是 Claude Code 插件？它们是在 Claude Code 内部运行你自己的 JavaScript 或 TypeScript 代码的 plugin，因此可以改变 Claude Code 的外观和行为：在输入框上方显示一行文字、在状态栏里放上数字、拒绝执行危险的 shell 命令，或者添加一个斜杠命令。插件（mod）功能随 Claude Code 2.1.287 推出，并且默认开启。

本指南会讲清楚插件由什么组成、它能碰什么不能碰什么、插件与设置中的 hooks、MCP 服务器和 skills 有何不同，以及如何判断一个插件是否可以放心安装。最后还会带你用两分钟做出一个能实际运行的插件。

Claude Code 插件到底是什么？#

插件就是一个普通的 Claude Code plugin，只是多了一个文件：hooks 模块。这个模块导出一个 register(on, options) 函数。Claude Code 加载该 plugin 时会调用 register，插件则用 on(...) 订阅各种事件，例如“某个工具即将运行”“一轮对话已结束”或“正在绘制加载动画（spinner）”。

每个处理函数都会收到三个参数：

• $，即插件 API。插件产生的每一个效果都要经过它：$.ui.status、$.ui.toast、$.process.run、$.fs.read、$.command.register 等等。
• e，即事件本身，例如即将运行的 Bash 命令。
• next，用于把事件交还给 Claude Code 自身的默认行为。

处理函数可以观察（调用 next(e) 并查看结果）、改写（用修改后的事件调用 next），或者直接应答（返回自己的结果，完全不调用 next，防护类插件就是这样拒绝工具调用的）。

让一个 plugin 成为插件（mod）的，只是一个键。只要 hooks/hooks.json 中包含 modules，这个 plugin 就是插件：

{
  "modules": ["./register.js"]
}

插件在 Claude Code 的进程中以你的用户权限运行，并没有沙箱隔离。与之相对的好处是：所有效果都必须经过 $，因此 Claude Code 可以在你运行之前读取插件源码，准确列出它处理哪些事件、调用哪些 API。

插件能改变哪些东西？#

事件列表很长，但大多数插件只会用到其中几类：

插件还可以打开面板、注册供 Claude 调用的工具、运行子代理、读写文件、发起 HTTP 请求，并把数据保存在一个小型键值存储中。这些能力都是 $ 调用，都会出现在验证结果里。

插件界面会在终端（包括 JetBrains 插件）和桌面应用的 Code 标签页中绘制。在 VS Code 扩展的聊天面板、claude -p 和 Agent SDK 中，hooks 依然会运行，但不会绘制任何内容。因此，防护类插件在无界面运行时照样保护你，而状态栏插件只是没有地方显示文字而已。

插件、hooks、MCP 服务器与 skills 有什么区别？#

这四种扩展方式只是名字相近，实际上各不相同：

• 设置中的 hooks 会在固定时机（工具运行前、工具运行后、停止时）执行一条 shell 命令。它们是独立进程，通过 stdin 和 stdout 上的 JSON 与 Claude Code 通信，无法绘制界面，也无法保存实时状态。
• 插件（mods） 在进程内运行，并提供带类型的 API。它们能做 hooks 能做的一切，还能在渲染位置上绘制内容、注册命令和工具，并响应 hooks 根本接收不到的事件，例如加载动画的绘制或上下文压缩的开始。
• MCP 服务器 通过一套协议为 Claude 提供新的工具和数据源，由 Claude 决定何时调用。它们不会改变 Claude Code 的界面，也不会拦截其内置工具。
• Skills 是 Claude 在任务匹配时加载的说明和文件。它们改变的是 Claude 知道什么，而不是 Claude Code 做什么。

一个粗略的判断标准：如果你希望 Claude 知道某些新东西或能够做某些新事情，就用 skill 或 MCP 服务器；如果你希望 Claude Code 本身看起来或表现得不一样，就写一个插件。

Claude Code 插件安全吗？#

插件能做你在终端里能做的任何事，所以安装插件时要像安装任何开发者工具一样谨慎。以下三个习惯可以把风险降到很低：

1. 阅读验证输出。 claude plugin validate <dir> 会为模块输出一行 hooks: 和一行 calls:。如果一个状态栏插件列出了 $.http.fetch 或 $.fs.write，就值得仔细看一看。
2. 查看权限标签。 ClaudeMods 上每个插件页面都会把这些调用转换成易懂的标签，例如“执行命令”或“拦截工具调用”，并用一句话说明插件为什么需要这项权限。
3. 知道如何关闭。 /plugin disable <name> 可以关闭单个插件。claude --safe-mode 会启动一个停用所有插件的会话。在设置中写入 "disableAllHooks": true 则会让插件保持关闭。

组织还可以采取更严格的措施。管理员可以只允许托管插件、禁止通过 --plugin-dir 侧载，并让一个经过审批的防护插件排在用户安装的所有插件之前运行。详情请参阅 插件管理员文档。

需要哪个版本的 Claude Code？#

运行 claude --version。终端需要 2.1.287 或更高版本。桌面应用自带一份 Claude Code，从 2.1.286 起即可使用插件。本站每个插件都标注了最近一次测试所用的版本；撰写本文时，这个版本是 2.1.291。

动手做一个小插件，看看它如何运行#

三个文件就够了。创建如下目录结构：

hello-status/
├── .claude-plugin/
│   └── plugin.json
└── hooks/
    ├── hooks.json
    └── register.js

.claude-plugin/plugin.json：

{
  "name": "hello-status",
  "version": "0.1.0",
  "description": "Writes a fixed message to the Claude Code status line",
  "author": { "name": "Your Name" }
}

hooks/hooks.json 中写入前面展示过的 modules 键，指向 ./register.js。然后是 hooks/register.js：

export function register(on) {
  on('session.start', async ($, e, next) => {
    const started = await next(e)
    $.ui.status('hello from my first mod')
    return started
  })
}

运行之前先检查一下：

claude plugin validate ./hello-status

在 Claude Code 2.1.291 上，它会输出：

  ❯ ./register.js hooks: session.start
  ❯ ./register.js calls: $.ui.status

✔ Validation passed

现在启动一个只在本次运行中加载该插件的会话：

claude --plugin-dir ./hello-status

状态栏会显示你的消息。编辑 register.js 并保存，Claude Code 会自动重新加载模块，无需重启。该插件以 hello-status@inline 的身份加载，退出后即消失。插件教程 介绍了测试与发布的方法。

去哪里找插件？#

插件通过 plugin 市场分发，市场就是包含 marketplace.json 的 Git 仓库或 URL。ClaudeMods 维护着一个这样的市场，插件目录中的每个插件都有专属页面，包含演示录屏、安装命令、可配置选项、实现功能的代码以及它所使用的权限。每个插件在页面上线前，都会在真实的 Claude Code 版本上经过验证、测试和录制。

准备好添加一个了吗？如何安装 Claude Code 插件介绍了所有安装方式，以及更新和删除的方法。