Claude Code Mods 是什么：10 月 1 日上线，插件能改界面和行为，附启用与验证步骤
Claude Code mods 是 2026 年 10 月 1 日随 2.1.287 版本推出的一类插件能力：官方更新日志的原话是“Added Claude Mods: plugins may now modify deeper behavior”，也就是插件可以改动比以前更深的行为，例如画界面、拦截提示词、在工具调用前后插手。同一版本还内置了第一个 mod，叫 “You should know”。以下内容截至 2026 年 10 月，以 Claude Code 官方更新日志为准。
Mod、hook、plugin 是什么关系？
三者是包含关系，不是并列关系。
| 名称 | 含义 |
|---|---|
| plugin（插件） | 分发和安装的单位，可以带命令、技能、hook 等内容 |
| hook（钩子） | 在固定时机运行的代码，例如 prompt.change、agent.spawn、turn.start |
| mod | 使用 mod API（日志中以 $. 开头，如 $.ui、$.model）的插件，能画界面、调用模型、改写提示词 |
更新日志里反复出现的说法是“a mod's hook”“a mod's Input”“a mod's Text”，可见 mod 本质上是一个会注册 hook、并能渲染界面元素的插件。这是根据日志措辞做的归纳，细节以官方文档为准。
内置的 “You should know” 做什么？
2.1.287 的日志说明：它是一个内置 mod，由一个旁路 agent 盯着会话，提示你或 Claude 可能漏掉的事。日志给出的启用命令是：
/plugin enable cc-plugin-you-should-know@builtin
日志同时注明适用于“first-party sessions with telemetry on”，即开启遥测的第一方会话。后续两次小改动：2.1.288（10 月 2 日）让提示根据决策者使用“we”“the main agent”或“you”；2.1.290（10 月 5 日）修复了它不按 language 设置输出语言的问题。
这两周 mod API 加了什么？
日志里与 mod 相关的条目，按版本整理如下（日期为日志所标）：
| 版本 | 日期 | 变化 |
|---|---|---|
| 2.1.288 | 10 月 2 日 | $.ui.selection()：返回全屏模式下最近选中的文字 |
| 2.1.292 | 10 月 6 日 | $.model.complete 支持提示缓存，文本块上设 cache: true；claude plugin install 新增 --marketplace <source> |
| 2.1.295 | 10 月 8 日 | $.ui.notify：通过你自己的通知设置发出原生通知 |
| 2.1.299 | 10 月 14 日 | $.prompt.media、$.session.identity()，二者面向由托管设置安装的 mod |
| 2.1.300 | 10 月 14 日 | prompt 装饰新增 virtualText；新增 prompt.change 钩子；agent.spawn 钩子可改写工作流 agent 的 prompt 和 model |
| 2.1.301 | 10 月 15 日 | Input 新增 rows，可做多行输入，Enter 提交，Shift+Enter 换行 |
其中提示缓存对成本有直接意义，原理见 Claude prompt caching 怎么用才省钱。
怎么装一个 mod 并确认它能用？
- 升级到 2.1.287 或更高。想用
--marketplace需要 2.1.292 以上。 - 一步装好并添加来源：
claude plugin install <插件名> --marketplace <source>。日志说明它会在需要时先添加 marketplace，并执行与claude plugin marketplace add相同的策略检查。 - 校验：
claude plugin validate。2.1.290 起，它会列出 mod 在“可拦截”位置注册的每个 hook，以及有没有.catch（加--json时字段为gatingHooks）。 - 需要自动化测试时可以用
claude plugin test，具体写法以官方文档为准。 - 在
/plugin里查看状态。组织用托管设置管理 Claude Code 时，可能影响 mod 的安装与运行，以官方文档为准。
校验的已知点：2.1.292 起，用重复声明或重新赋值的顶层 var 读取 $.state 的模块会被 validate 拒绝。
想自己写一个 mod，怎么起步？
最小思路：挑一个钩子，只做一件小事。例如在 prompt.change 里读取提示框文字，用 virtualText 在输入框里显示一句不会进入草稿的提示。具体的文件结构和 API 签名我没有在公开日志里核实到，请以官方文档为准。2.1.300 的日志提到内置的 plugin-authoring 技能负责 mod 的制作和分享，可以让 Claude 带着你搭骨架。
写完先跑 claude plugin validate，再装进一个临时项目试，不要一开始就装到日常工作的环境。
升级前要看什么？
mod API 在三周内改了很多次，有些是行为变化而不是新增。例如 2.1.301 把 $.env.set 改为设置成功后返回 {}，被拒绝时返回带原因的 { deny }。已经写了 mod 的人，升级前应逐条看日志。cdnping 的 官网动态 会逐行记录官方更新日志的增删，可以订阅 RSS。
和插件目录有什么关系？
Anthropic 的发布说明在 2026 年 9 月 25 日写明，现在可以通过新的开发者门户把插件提交到 Claude 目录，上线后可看到使用分析。这条说的是面向 Claude 的插件，是否同样适用于 Claude Code 的 mod，请以官方说明为准。
相关阅读
- 把 Claude Code 指向自定义接口：Claude Code 自定义 API 与 Codex、OpenCode 接口地址配置
- 升级后连不上：Claude Code 连接超时和报错怎么排查
- 响应变慢：Claude Code 慢怎么办
- 额度与限制：Claude Max 5x 和 20x 有什么区别
遇到服务异常，可以先看 Claude Code 是否在故障中 和 Anthropic API 状态。
