SpyBara
Go Premium

plugins/mods/overview.md 2026-11-12 23:02 UTC to 2026-11-13 00:00 UTC

No changes for this document in this history range.

2026
Tue 10 21:57 Thu 12 23:02

Mods 概览

使用 mod 向 Claude Code 添加窗格、命令和工具调用规则。了解 mod 可以做什么、如何创建或安装 mod，以及 mod 在哪里运行。

Mod 是一个插件，它改变 Claude Code 的外观和行为。它由 JavaScript 或 TypeScript 事件处理程序组成：Claude Code 在事件发生时调用一个处理程序，例如工具调用、提交的提示或界面的一部分被绘制，处理程序可以观察事件、更改事件或接管事件。使用 mod 向 Claude Code 添加自己的功能，例如一个窗格，在每个请求后显示上下文有多满。有关 mod 中的文件和完整示例，请参阅Mod 如何工作。

[!NOTE]

Claude Code 现有的 hooks 也在事件上运行，作为 shell 命令、HTTP 请求或在设置文件中配置的提示。Mod 的处理程序是在 Claude Code 内部运行的函数。Claude Code 调用两种类型的 hooks：在这些页面上，"hook" 指的是 mod 的处理程序，而设置文件类型是"设置 hook"。

Mod 可以做什么

设置 hooks、skills、状态行和 MCP 服务器从 Claude Code 外部工作：每一个都运行一个脚本，或给 Claude 文本或工具。Mod 在 Claude Code 内部运行，所以它可以做他们做不了的事情：

  • 绘制可以使用的界面：在文本记录旁边的窗格或提示上方的带状区域，带有选项卡、按钮和文本字段。请参阅在界面中绘制。
  • 重新绘制 Claude Code 自己的界面：替换或重新设置 Claude Code 自己绘制的部分，例如工具调用的行、微调器或 Claude 提出问题的对话框。请参阅更改 Claude Code 已经绘制的内容。
  • 进入工具调用或请求：例如，在向用户提出问题时保持工具调用，在不运行工具的情况下回答问题，或将一个请求发送到不同的模型。请参阅保护或更改工具调用和跟随一个转折。
  • 在命令上运行自己的代码：一个 /command，立即运行你的函数，没有 Claude 转折，即使 Claude 正在工作。请参阅添加命令或工具。
  • 在 hooks 之间共享数据：mod 的 hooks 共享其文件中的变量，所以一个 hook 记录的内容，另一个可以显示。例如，一个 hook 可以计算工具调用，而另一个在微调器旁边显示计数，或者一个可以读取每个请求的令牌使用情况，而另一个在窗格中绘制它。请参阅对事件做出反应。

mod 可在 Claude Code CLI、Claude Desktop 应用的 Code 选项卡以及 VS Code 扩展中工作。请参阅mod 在哪里运行以了解它们在其他地方的行为，例如在 claude -p 和云端会话中。如果设置 hook、skill 或 MCP 服务器已经能满足您的需要，请在编写 mod 之前先比较它们。要为组织管理 mod，请参阅为您的组织管理 mod。

获取 mod

要开始使用 mod：

安装或更新 mod

[!WARNING]

mod 是使用您的权限运行的代码。它可以读写您的文件、启动进程和发出网络请求。仅从您信任的作者和市场安装 mod。请参阅决定是否信任 mod。

mod 作为插件从市场安装。给出插件的名称、一个 @ 和市场的名称。这些示例从名为 your-org 的市场安装名为 token-chart 的插件：

  • 在 Claude Code 会话中，运行 /plugin install token-chart@your-org。
  • 在您的 shell 中，运行 claude plugin install token-chart@your-org。

安装插件涵盖市场、作用域、VS Code 扩展和桌面应用，以及保持插件更新，所有这些都适用于包含 mod 的插件，无需更改。

如果在会话打开时从 shell 安装或更新 mod，请在该会话中运行 /reload-plugins 以加载它。否则，它将在下次启动 Claude Code 时加载。

试用示例 mod

Anthropic 在 claude-code-playground 仓库的 claude-code/mods 目录中分享示例 mod。每个示例都是一个完整的插件，其 README 说明了它的构建方式。该仓库按原样分享这些示例，不提供支持。

  • token-weather：在输入框上方绘制上下文窗口的预测图
  • blast-radius：拦截有风险的 shell 命令（例如 rm -rf 或强制推送），显示它将更改的内容，并提供继续或取消的按钮
  • replay-theater：添加一个 /replay 命令，用于逐步浏览 Claude 在上一轮次中所做的文件编辑

示例 mod 使用您的权限运行。要在加载之前查看它的作用，请列出其 hook 和调用。

要试用某个示例，请克隆该仓库，并使用 --plugin-dir 为单个会话加载该 mod 的目录。要确认 mod 已加载，请检查会话加载了哪些 mod。

要保留某个示例，请将克隆中的 claude-code/mods 目录添加为市场，然后从 claude-code-playground-mods 安装该 mod。该市场指向您的克隆，因此如果您移动或删除该克隆，mod 将停止加载。

决定是否信任 mod

Mod 是使用您的权限在 Claude Code 内部运行的代码。仅从您信任的作者和市场安装 mod。

Mod 可以访问什么

Mod 使用您的权限运行，所以在安装之前，请了解它可以访问什么。一旦加载，mod 可以：

  • 在您的机器上以您的身份行动：读写您的用户账户可以访问的任何位置的文件、启动程序以及发出网络请求
  • 读取您的机密信息：环境变量和设置文件，包括您保存在其中任何一处的 API 密钥
  • 查看您的会话：您发送的每个提示词和 Claude 进行的每个工具调用
  • 更改您的会话：重写提示词或工具调用、像您亲自输入一样提交提示词，或向您的另一个会话发送消息
  • 在不询问您的情况下行动：在询问您之前批准工具调用
  • 消耗您的使用量：使用您的计划或 API 密钥调用模型

Mod 不在沙箱中运行。如果您启用沙箱隔离，沙箱会隔离 Claude 运行的 Bash 命令，而 mod 启动的进程在沙箱之外运行。

Mod 可以批准许多工具调用，而这些调用原本会被您的 deny 或 ask 规则或您的 PreToolUse hook 拦截，除非内置守卫阻止这样做。加载守卫后，默认情况下用户的 mod 无法这样做。在本地终端会话中，如果 /plugin 的 Installed 选项卡上显示 cc-plugin-sec-default，则表示守卫已加载。

Mod 可以重新设置 Claude Code 界面的大部分样式，但不能重新设置权限提示。它无法改变权限提示向您显示的内容。

在安装 mod 之前列出它做什么

在安装 mod 之前，您可以在不运行它的情况下列出它处理哪些事件以及它要求 Claude Code 做什么，例如读取文件或发出网络请求。首先获取插件的文件，例如通过克隆其仓库。然后，在您的 shell 中，对插件的目录运行 claude plugin validate：

claude plugin validate ./some-mod

输出中的 hooks: 和 calls: 行列出了 mod 处理的事件以及它要求 Claude Code 做什么。查看 mod 可以做什么展示了输出内容以及需要留意的调用。

打开或关闭 mods

mod 默认处于打开状态。在终端中，请使用 Claude Code v2.1.287 或更高版本。Desktop 应用包含其自带的 Claude Code 副本，mod 从 v2.1.286 起即可在其中使用。请在您使用 mod 的地方检查版本：

  • 终端：在您的 shell 中运行 claude --version。如果您的版本较旧，请更新 Claude Code。
  • Desktop 应用：在 Code 选项卡的本地会话中输入 /status，查看 Claude Code 一行，其中会显示 2.1.286 之类的版本号。如果您的版本较旧，请更新 Desktop 应用。

要关闭 mods，选择要停止多少个，以及停止多长时间。要重新打开它们，撤销相同的更改：

  • 一个 mod：从/plugin 中的已安装选项卡禁用或卸载其插件
  • 每个已安装的 mod，对于一个会话：使用 --safe-mode 启动 Claude Code，这也会禁用您的其他自定义
  • 您安装的每个 mod，在每个会话中：在 ~/.claude/settings.json 中设置 "disableAllHooks": true。您的设置 hook 和自定义状态栏也会停止。您的组织管理的内容继续运行。

如果您通过组织使用 Claude Code，管理员也可以限制哪些 mods 加载。管理员从停止用户安装的 mods 加载开始。

disableAllHooks 和您组织的 allowManagedModsOnly 会停止 mod，但保留其插件的其余部分：插件保持安装状态，其 skill、命令、Agent 和 MCP 服务器照常加载。其他设置和标志的影响范围更广。disableAllHooks 和allowManagedHooksOnly 下运行的内容列出了每一项对插件及其设置 hook 的影响。

要了解 mods 是否可以为您加载，请参阅检查 mods 是否可以加载。

[!NOTE]

如果您在早期访问期间设置了 CLAUDE_CODE_ENABLE_FUNCTION_HOOKS，请删除它。Claude Code v2.1.287 及更高版本忽略它，所以将其设置为 0 不会保持 mods 关闭。

查看会话加载了哪些 mods

要查看终端会话加载了哪些 mods，在 Claude Code 提示符处运行 /plugin。选项卡下的暗色行给出计数和名称，例如 1 mod active · first-mod。如果您安装的 mod 没有在那里列出，请参阅找出为什么 mod 什么都不做。

Mod 如何工作

Mod 是一个插件，其代码注册事件处理程序，称为 hook。Claude Code 在相应事件发生时运行 hook，例如当 Claude 调用工具或绘制微调器时。一个小 mod 有三个文件：

first-mod/
├── .claude-plugin/
│   └── plugin.json
└── hooks/
    ├── hooks.json
    └── register.js

这是一个完整的 register.js。它统计 Claude 进行的工具调用次数，并在 Claude 工作时在微调器旁边显示计数，如 Thinking · tool calls: 3…。

// The count, shared by the two hooks below
let calls = 0

// Claude Code calls this once when the mod loads
export function register(on) {
  // Runs each time Claude is about to use a tool
  on('tool.call', async ($, e, next) => {
    calls += 1
    // Ask Claude Code to draw the interface again, so the new count shows
    $.ui.invalidate('ui.render')
    // Let the tool run as usual
    return next(e)
  })

  // Runs each time Claude Code draws the spinner
  on('ui.render', { component: 'Spinner' }, async ($, e, next) => {
    // Keep Claude Code's spinner, with the count added after its word
    return next({ ...e, props: { ...e.props, suffix: ' · tool calls: ' + calls + '…' } })
  })
}

该文件注册了两个 hook，两者都使用顶部的 calls 变量：

  • tool.call hook 在 Claude 每次即将使用工具时运行。它将 calls 加一，要求 Claude Code 再次绘制界面，并让工具照常运行。
  • ui.render hook 在 Claude Code 每次绘制微调器时运行。它保留 Claude Code 自己的微调器，并在其文字后添加计数。

这段录屏展示了 mod 的工作过程。请观察输入框上方的微调器行：当 Claude 列出目录并读取两个文件时，它显示 Thinking · tool calls: 1…，然后是 2…，然后是 3…。