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 可以计算工具调用,而另一个在微调器旁边显示计数,或者一个可以读取每个请求的令牌使用情况,而另一个在窗格中绘制它。请参阅对事件做出反应。
claude -p 和云端会话中。如果设置 hook、skill 或 MCP 服务器已经能满足您的需要,请在编写 mod 之前先比较它们。要为组织管理 mod,请参阅为您的组织管理 mod。
获取 mod
要开始使用 mod:- 使用您已经拥有的:Claude Code 自身的一些功能就是 mod,例如
/diff。请参阅内置于 Claude Code 的 mod。 - 创建一个:在 Claude Code 会话中描述您想要的内容,Claude 会编写 mod。请参阅向 Claude 请求 mod。要了解 mod 代码如何工作,自己编写一个。
- 安装一个:请参阅安装或更新 mod,或试用示例 mod
安装或更新 mod
mod 作为插件从市场安装。给出插件的名称、一个@ 和市场的名称。这些示例从名为 your-org 的市场安装名为 token-chart 的插件:
- 在 Claude Code 会话中,运行
/plugin install token-chart@your-org。 - 在您的 shell 中,运行
claude plugin install token-chart@your-org。
/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 在上一轮次中所做的文件编辑
--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 密钥调用模型
deny 或 ask 规则或您的 PreToolUse hook 拦截,除非内置守卫阻止这样做。加载守卫后,默认情况下用户的 mod 无法这样做。在本地终端会话中,如果 /plugin 的 Installed 选项卡上显示 cc-plugin-sec-default,则表示守卫已加载。
Mod 可以重新设置 Claude Code 界面的大部分样式,但不能重新设置权限提示。它无法改变权限提示向您显示的内容。
在安装 mod 之前列出它做什么
在安装 mod 之前,您可以在不运行它的情况下列出它处理哪些事件以及它要求 Claude Code 做什么,例如读取文件或发出网络请求。首先获取插件的文件,例如通过克隆其仓库。然后,在您的 shell 中,对插件的目录运行claude plugin validate:
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 应用。
- 一个 mod:从
/plugin中的已安装选项卡禁用或卸载其插件 - 每个已安装的 mod,对于一个会话:使用
--safe-mode启动 Claude Code,这也会禁用您的其他自定义 - 您安装的每个 mod,在每个会话中:在
~/.claude/settings.json中设置"disableAllHooks": true。您的设置 hook 和自定义状态栏也会停止。您的组织管理的内容继续运行。
disableAllHooks 和您组织的 allowManagedModsOnly 会停止 mod,但保留其插件的其余部分:插件保持安装状态,其 skill、命令、Agent 和 MCP 服务器照常加载。其他设置和标志的影响范围更广。disableAllHooks 和allowManagedHooksOnly 下运行的内容列出了每一项对插件及其设置 hook 的影响。
要了解 mods 是否可以为您加载,请参阅检查 mods 是否可以加载。
如果您在早期访问期间设置了
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 有三个文件:register.js。它统计 Claude 进行的工具调用次数,并在 Claude 工作时在微调器旁边显示计数,如 Thinking · tool calls: 3…。
hooks/register.js
calls 变量:
tool.callhook 在 Claude 每次即将使用工具时运行。它将calls加一,要求 Claude Code 再次绘制界面,并让工具照常运行。ui.renderhook 在 Claude Code 每次绘制微调器时运行。它保留 Claude Code 自己的微调器,并在其文字后添加计数。
Thinking · tool calls: 1…,然后是 2…,然后是 3…。
Hook 可以对事件做什么
Claude Code 在对事件采取行动之前运行您的 hook,因此由 hook 决定接下来会发生什么。它可以:- 观察:记录正在发生的事情并让其不变地继续,就像示例中的
tool.callhook 一样 - 重写:在事件继续之前更改事件,就像
ui.renderhook 在向微调器添加计数时所做的那样 - 回答:自己处理事件,使通常的行为不会运行,例如拒绝某个命令
Mods 在哪里运行
mod 的 hook 在加载该插件的每种会话中运行,无论由哪个提供商提供模型,包括 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry。绘制的范围更窄:mod 绘制的内容会出现在终端、桌面应用和 VS Code 扩展中。此表列出了您可能运行 Claude Code 的每个地方:
会绘制内容的 mod 可以检查自己运行在哪个应用中,并在无法绘制的地方回退为会话记录中的一行或命令的文本回复。
为你的组织控制 mods
管理员通过托管设置决定 mods 是否运行以及哪些运行。为你的组织管理 mods涵盖默认情况下发生的事情、如何查看 mod 以及如何使用你自己的 mod 强制执行策略。比较 mod、设置 hook、skill 和 MCP 服务器
Mod、设置 hook、skill 和 MCP 服务器的功能有所重叠。此表说明每一种是什么以及何时选择它。
其他每一种都有自己的页面:Hooks、Skills 和 MCP。一个插件可以容纳所有这些,因此 mod 可以与 skill 和 MCP 服务器放在同一个插件中发布。
内置于 Claude Code 的 Mods
Claude Code 自身的一些功能就是 mod。要查看您的会话拥有哪些,请在 Claude Code 输入框中运行/plugin 并转到已安装选项卡,它在内置下列出这些 mod。您不能更新或卸载内置 mod。mods active 行不包含内置 mod。
此表按 /plugin 显示的名称列出部分内置条目:
对于不在表中的内置插件,请在
/plugin 中打开其详细信息,以了解它的作用或将其禁用。
停止已安装 mods 的设置和标志,例如 disableAllHooks、--bare 和 --safe-mode,不会停止内置 mods。
阅读内置 mods 的源代码
其中一些 mods 的源代码在 Claude Code 仓库的mods 目录中是公开的。每一个都是一个完整的插件,带有其 hooks 模块和测试:
diff:/diff窗格,带有绑定到键盘操作的按钮和 mod 自己处理的滚动agents-md:将AGENTS.md加载为项目指令,带有userConfig选项sec-default:了解默认情况下发生的事情中描述的保护,一个强制执行策略的 mod 的模型telemetry:添加其他 mods 可以调用的方法,并提供其类型
后续步骤
- 创建 mod:构建一个计算工具调用、在微调器旁边显示计数并添加命令的 mod,并学习编辑和重新加载循环
- 在界面中绘制:窗格、输入框上方的带状区域、按钮、文本字段和状态
- 对事件做出反应:工具调用、提示词、轮次和 mods 运行的顺序
- 使用 mods API:命令、工具、模型调用、计时器和文件
- 测试 mod:在没有会话的情况下运行的自动化测试
- 对 mod 进行故障排除:mod 什么都不做的原因和调试日志
- 为您的组织管理 mods:默认值、托管设置、查看 mod 和策略 mods
- Mods 参考:事件、方法、元素和限制