Claude Code Mods 实操：用 TypeScript 事件钩子改写 CLI 行为与界面

Mods 与 hooks 的区别

Anthropic 在 10 月 1 日的官方博客中把 Mods 描述为几行 TypeScript 就能改变 Claude Code 的行为与外观。它和此前的 hooks 不是替代关系：hooks 是配置在 settings 文件里的外部命令、HTTP 请求或提示词，在固定的生命周期点触发，一次调用一个进程；而 Mods 是跑在 Claude Code 进程内部的函数，可以保持状态、可以画界面、可以改写甚至接管事件。

机制上是事件驱动。Claude Code 每做一件事就发出一个事件，比如调用工具、请求权限、绘制界面的一部分。一个 Mod 就是一个挂钩到某个事件的函数，它可以在事件之前运行、之后运行，也可以取而代之，或者把事件包起来前后都插逻辑。

五步跑通第一个 Mod

第一步，确认版本：Mods 需要 Claude Code v2.1.287 或更高，且默认开启，无需额外开关。第二步，准备插件目录：Mods 随插件分发，目录里放一个 manifest 与你的 TypeScript 入口文件；Anthropic 已在 Claude Code 仓库的 mods 目录公开了 diff、agents-md、sec-default、telemetry 四个内置 Mod 的源码，这是最好的参考代码。

第三步，写下第一个钩子。官方给出的能力清单是：在提示词抵达模型前改写它、拦截或重试工具调用、批准还是拒绝权限请求、在 Claude 读到工具输出前把密钥抹掉。多个 Mod 挂钩同一事件时按加载顺序执行，先加载的先看到事件。第四步，安装：在 CLI 里运行 /plugin 从插件目录或本地路径安装，也可以直接让 Claude 帮你写、装并在会话里热重载。第五步，先验证再放行：对任何来源不明或自己不确定的 Mod，先跑 claude plugin validate，它会列出该 Mod 挂钩的事件与调用的 API，而不执行其代码。

必须知道的三个边界

第一，Mods 不被沙箱隔离，运行权限与 Claude Code 本身相同，也就是能读文件、跑命令、动你的机器。早期访问期社区检查过当时公开的 31 个 Mod，其中 14 个具备执行本机进程的能力，接近一半。第二，企业侧有内置的 sec-default Mod，在 Team 与 Enterprise 计划或推送了托管设置的机器上会最先加载，阻止用户自装的 Mod 覆盖权限拒绝规则；管理员也可以改用自己的 Mod，但要记得把 sec-default 加回列表。第三，内置功能正在陆续迁成 Mod，/diff 已经是一个 Mod，可以在 /plugin 里关掉或用自己的版本替换。

能力与风险总是一起到来：社区目录里 72 个 Mod 中，46 个能写文件、跑程序、驱动 Claude 或访问网络。

实践建议是从只观察、只绘制的 Mod 起步，比如显示上下文用量的 token-ledger，或让界面更安静的那一类，确认无误之后再引入会改写工具调用的 Mod。对已经批准 Claude Code 上线的团队来说，安全策略需要补上一条：哪些 Mod 允许装、谁有权装、信任哪些插件市场。