SpyBara
Go Premium

plugins/mods/overview.md 2026-09-30 23:00 UTC to 2026-10-01 21:02 UTC

This page contains 269 additions and 0 deletions.

2026
Thu 1 21:02

Mods 概览

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

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

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 可以计算工具调用，而另一个在微调器旁边显示计数，或者一个可以读取每个请求的令牌使用情况，而另一个在窗格中绘制它。请参阅对事件做出反应。

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

获取 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

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

Mod 可以访问什么

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

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

批准工具调用的 mod 可以批准 ask 规则会提示的工具调用，或你自己的 PreToolUse hooks 阻止的工具调用。使用 hooks 扩展权限列出了这样的 mod 可以批准的内容，包括它何时可以批准 deny 规则拒绝的调用。

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

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

在安装 mod 之前，你可以列出它 hooks 的事件以及它要求 Claude Code 做什么，例如读取文件或发出网络请求，而无需运行它。首先获取插件的文件，例如通过克隆其存储库。然后，在你的 shell 中，在插件的目录上运行 claude plugin validate：

claude plugin validate ./some-mod

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

打开或关闭 mods

Mods 需要 Claude Code v2.1.287 或更高版本，默认情况下它们是打开的。在你的 shell 中，运行 claude --version 以检查，如果你的版本较旧，请更新 Claude Code。

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

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

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

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

查看会话加载了哪些 mods

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

Mod 如何工作

Mod 是一个插件，其代码注册事件处理程序，称为 hooks。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 + '…' } })
  })
}

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

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

这个录制显示了 mod 的工作。观看提示框上方的微调器行：当 Claude 列出目录并读取两个文件时，它读取 Thinking · tool calls: 1…，然后 2…，然后 3…。