什么是 Mod

Mod 是改变 Claude Code 外观和行为的插件。它用 JavaScript 或 TypeScript 函数（钩子）编写，Claude Code 每遇到一个事件就会调用这个函数。事件包括工具调用、提交提示词、绘制界面、回合的开始和结束、会话的开始和结束。

钩子如何处理事件

钩子接收事件后，会做三件事之一。

1. **观察：**看一眼，原样放行。例如统计工具调用次数。
2. **改写：**修改内容后再传下去。例如在加载动画旁边加一个数字。
3. **代答：**自己处理，并阻止原本的行为。例如拒绝危险命令。

钩子触及外部世界的途径只有 mods API（$）一条。读取文件、运行进程、访问网络、调用模型，全都要经过 $。所以安装之前，可以用 claude plugin validate 列出这个 Mod 会做什么。

最小的 Mod

只需要三个文件。

first-mod/
├── .claude-plugin/plugin.json   ← 清单
└── hooks/
    ├── hooks.json               ← 钩子模块位置
    └── register.js              ← 钩子代码（.ts、.tsx 也行）

hooks/register.js

let calls = 0

export function register(on) {
  // 每次 Claude 即将使用工具时
  on('tool.call', async ($, e, next) => {
    calls += 1
    $.ui.invalidate('ui.render')
    return next(e)
  })
  // 每次绘制加载动画时：在原来的加载动画上只加一个数字
  on('ui.render', { component: 'Spinner' }, async ($, e, next) => {
    return next({ ...e, props: { ...e.props, suffix: ` · tool calls: ${calls}…` } })
  })
}

与其他扩展有什么不同

关键区别在于运行位置。设置钩子、技能、MCP、状态栏在 Claude Code 外部响应，而 Mod 在内部介入。

	Mod	设置钩子	技能	MCP 服务器
本质	Claude Code 进程内的函数	事件发生时执行的 shell 命令、HTTP、提示词	Claude 读取的 SKILL.md 指令	提供工具的外部进程或服务
能改变什么	工具调用、提示词、命令、回合、界面	是否放行、工具参数和结果、附加上下文	Claude 所知道的内容和做事方式	Claude 能使用的工具
绘制界面	可以	不可以	不可以	不可以
编写语言	JavaScript/TypeScript	脚本 + settings.json	Markdown	任意语言
何时选用	需要窗口、横条、专用命令，或要修改事件时	用现成脚本只做拦截、放行、记录时	总在重复粘贴同样的指示时	Claude 需要接触外部系统时

一个插件里可以同时包含这四种。如果设置钩子或技能就够用，最好不要用 Mod，因为它的权限最大。

在哪里运行

Mod 在终端 2.1.287 及以上、桌面应用 2.1.286 及以上默认开启。

运行位置	钩子执行	界面显示
终端 claude（编辑器内置终端，含 JetBrains）	是	是
桌面应用 Code 标签页	是	是（终端专用元素除外）
桌面应用 WSL 会话	否	否
VS Code 扩展聊天面板	是	否
claude -p、Agent SDK	是	否
Remote Control（claude.ai、手机）	是（在你自己电脑的会话中）	仅在你电脑的终端里
云端会话	仅当插件随之同步时	否

Mod 不在沙箱里运行

Mod 以你的账号权限运行。它能读写文件、运行程序、发起网络请求，还能看到所有提示词和工具调用。安装前一定要先做安全检查。

内置的 Mod

Claude Code 的部分功能本身就是 Mod。在 /plugin 的 Installed 标签页里，Built-in 下面可以看到。

• cc-plugin-diff：/diff 窗口
• cc-plugin-agents-md：把 AGENTS.md 作为项目指令加载
• cc-plugin-sec-default：保护组织管理的设置不被用户 Mod 改动的守卫
• cc-plugin-telemetry：发送分析记录
• cc-plugin-plugin-authoring：制作 Mod 的技能（无代码）

其中一部分的源码公开在 anthropics/claude-code 的 mods 文件夹，是制作 Mod 时很好的范本。