SpyBara
Go Premium

plugins/mods/overview.md 2026-10-22 22:58 UTC to 2026-10-23 22:59 UTC

This page contains 56 additions and 56 deletions.

2026
Thu 1 23:59 Fri 2 22:59 Tue 6 23:59 Thu 8 22:58 Wed 14 22:58 Thu 15 23:58 Mon 19 23:58 Tue 20 23:00 Thu 22 22:58 Fri 23 22:59

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 启动的进程在沙箱之外运行。

当存在托管设置，或以 Team 或 Enterprise /login 作为会话凭据时，默认情况下 mod 的批准无法让调用绕过您的 ask 规则或 PreToolUse hook。如果两者都不存在，mod 可以批准 ask 规则会提示确认的调用，或您的 PreToolUse hook 已阻止的调用。要了解 mod 何时还可以批准 deny 规则拒绝的调用，请参阅使用 hook 扩展权限。

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…。