服务对象与地域限制
PuppyIP 仅面向海外合规企业及其授权人员提供服务，不面向中国大陆地区开放或提供代理服务。本服务仅限用于中国大陆境外的合法业务活动，严禁在中国大陆境内使用本服务。
代理 IP 或服务器位于境外，不改变上述限制。不得通过中转、转接、共享或转售向中国大陆境内的最终使用者提供本服务。使用前请阅读用户服务协议。
本文要点
- Mods 在 Claude Code 内处理事件，可加入面板、命令或修改工具调用；它与传统 settings hooks 的运行方式不同。
- v2.1.287 于 10 月 1 日发布，v2.1.288 于 10 月 2 日继续修复相关问题，本文按 UTC 区分版本日期。
- 终端和 Desktop Code 可显示 Mod 界面；VS Code 聊天面板中没有界面，不一定代表 Mod 未运行。
- 安装、禁用与排错先查看插件状态和组织策略；模型调用仍使用原有套餐或 API Key 的额度。
先看版本：这次改变了什么
官方 v2.1.287 发布于 2026 年 10 月 1 日 18:00 UTC，加入 Claude Mods。它面向希望定制开发工作流的人，例如显示上下文状态、增加自己的命令，或在工具执行前加入交互。仅需要一组固定写作或编码指令时，原有 Skill 仍可能更合适，不必为了新功能重做配置。
10 月 2 日 20:19 UTC 发布的 v2.1.288 增加 $.ui.selection()，并修复 Mod 的 tool.call 影响 worktree 子代理路径、重载或禁用插件时后台会话退出等问题。遇到这些症状时，先确认安装版本是否包含修复，再修改 Mod 代码；不能把后续修复误认为另一种独立产品。本文于北京时间 10 月 4 日核验文档，未在读者环境中实际安装运行。
Mods、插件和 hooks 应该怎么选
插件是分发和安装的容器。Mod 是其中使用 JavaScript 或 TypeScript 事件处理函数的部分，函数在 Claude Code 内执行，能够观察、改变或接管特定事件。一个插件也可以同时带 Skill、MCP 服务和其他组件，所以看到插件已安装，还不能直接推断 Mod 正在运行。
可以从要交付的结果倒推选择：重复说明一套工作方法，用 Skill；让现有脚本在指定事件后运行，先看 settings hooks；接入外部工具，考虑 MCP；需要在会话界面增加可交互面板，或组合更细的事件处理，再评估 Mod。这样也更容易为失败定位负责的组件。
安装前确认三件事
第一，在终端执行 claude --version，确认至少为 v2.1.287；若正在处理上述已修复问题，还要核对 v2.1.288 或后续版本。第二，确认插件作者与 marketplace 的实际名称和来源。第三，确认使用的是允许加载该 Mod 的个人或组织环境，不能把软件版本满足条件当成组织已经放行。
Mods 按当前用户权限运行。官方说明它们可接触文件、环境变量和会话内容，也可发起进程、网络请求及模型调用；Claude Code 的 Bash sandbox 不会把 Mod 本身隔离起来。查看作者代码和插件说明的目的，是判断这些能力是否符合你的实际工作范围，而不是只凭一个安装成功提示判断可信。
从安装到确认加载
已有可信 marketplace 时，在 Claude Code 会话输入 /plugin install 插件名@市场名，或在外部终端使用 claude plugin install 插件名@市场名。这里的中文是占位说明，必须替换为该作者文档给出的真实名称；没有登记 marketplace 时，先按插件安装文档添加来源。个人使用先明确安装 scope，不要误把项目级配置提交给所有协作者。
若从外部终端安装或更新，而原会话还开着，在原会话运行 /reload-plugins；否则下次启动加载。随后打开 /plugin 的 Installed 页，检查目标插件和终端的 mods active 名单。再执行一个与 Mod 用途直接对应的小操作，例如观察约定面板或调用它提供的命令，分别确认“已加载”和“按预期工作”。
没有面板，先排除客户端差异
当前官方支持表把事件执行与界面绘制分开。交互终端以及 Desktop 应用的 Code 页能够显示 Mod 面板等界面，但部分元素仅限终端。VS Code 扩展的聊天面板可以运行已加载的 Mod hooks，却不显示它绘制的界面；claude -p、Agent SDK 等无界面使用方式也不能拿面板作为验收标准。
Desktop 的 WSL 会话目前不支持插件，不能套用普通 Desktop Code 会话的结论。若只在某个客户端看不到内容，先在支持该界面的终端确认加载状态和行为，再向作者报告客户端差异。不要一开始就清空全部配置或重新安装所有依赖。
自己做第一个 Mod，如何留下可验证结果
官方提供两条创建路径：在交互会话描述需求，让内置 plugin-authoring 技能协助编写；或者照 Create a mod 文档写一个最小插件。建议从单一结果开始，例如只显示当前 Git 分支，避免首次尝试就同时接管工具、改变模型和绘制多个窗口。文档说明 Claude Code 可直接加载相应 JS/TS 文件，不要求先加入 Node.js 打包步骤。
让 Claude 编写时，文件位于该会话的 dev-mods 目录，受文件审批与热重载确认约束。完成后仍要到 /plugin 检查，再触发所需行为；生成文件不等于已经加载。需要跨会话保留时，按文档把插件目录保存到自己的稳定位置，再用 --plugin-dir 加载或通过 marketplace 分发。不要把会话临时目录当作长期部署位置。
不生效时按加载、事件、策略顺序查
能取得插件文件时，先执行 claude plugin validate ./some-mod，把路径换成实际目录。这一步检查清单与静态分析结果，不运行 Mod；查看 hooks 和 calls 列表，确认要处理的事件确实被识别。再检查 /plugin 是否列出目标 Mod，必要时用 claude --debug 启动会话查加载错误。
若插件的 Skill 正常但 Mod 不运行，继续核对启动参数、disableAllHooks 以及组织限制。官方还提供一个诊断：在不含 Mod 的目录运行 claude plugin test；no hooks module to load 表明该检查下模块加载未被整体关闭，turned off here 表示个人设置或组织策略阻止，turned off in this process 表示 Anthropic 远程关闭，本地设置无法恢复。但这个检查不能排除 allowManagedModsOnly，不能据此保证任意第三方 Mod 都会加载。
提交问题时记录 Claude Code 版本、客户端、插件版本、最小触发步骤和错误文字。日志先去除提示词、文件内容、密钥等非必要信息。若组织策略明确禁止该来源，应由管理员确认允许的安装范围，不以关闭策略作为通用排错步骤。
如何关闭：旧环境变量已经不管用
v2.1.287 及以后忽略 CLAUDE_CODE_ENABLE_FUNCTION_HOOKS，设为 0 也不能停用。只想停止自己安装的一个 Mod，在 /plugin 的 Installed 页禁用或卸载对应插件；终端也可使用 claude plugin disable 插件名@市场名。禁用整个插件会影响它提供的其他组件，操作前先看该插件还包含什么。
临时排除用户安装的 Mod，可以启动一个 --safe-mode 会话，但它也会关闭其他自定义功能。用户设置中的 disableAllHooks 会停止自己的 Mods、settings hooks 和自定义状态行，受管内容仍运行；若由管理员在 managed settings 设置，范围包括受管 Mods 和 settings hooks。内置 Mods 不受此开关影响。精确停用、临时诊断和组织统一策略应分别选择，不能把一个宽范围开关当成万能修复。
资料来源
常见问题
Claude Mods 需要单独打开预览开关吗？
v2.1.287 起默认开启相应能力，旧 CLAUDE_CODE_ENABLE_FUNCTION_HOOKS 已被忽略。是否能加载具体 Mod，还受插件状态、客户端和组织策略影响。
插件已经安装，为什么没有 mods active？
插件可能只含 Skill 或 MCP，也可能尚未重载，或 Mod 被设置阻止。先确认该插件确实包含 Mod，再检查 /plugin、静态校验和加载日志。内置 Mods 不计入这条活动名单。
VS Code 里看不到 Mod 面板就是失败吗？
不一定。当前 VS Code 聊天面板可执行已加载的 Mod hooks，但不绘制它的界面。应根据该客户端支持的输出方式确认行为。
关闭 sandbox 能解决 Mod 不工作吗？
不应把关闭 sandbox 当成此类通用排错。Mod 本身并不受该 Bash sandbox 隔离，应查版本、模块校验、加载状态与组织策略。
Mods 会让 Claude 额度变多吗？
不会因安装 Mod 自动增加套餐或 API 额度。Mod 调用模型时可以消耗现有用量，是否额外发起请求应查看其说明与代码。
官方示例可以直接用于生产团队吗？
官方将 playground 示例按现状提供，不承诺支持。团队应先确认其行为、权限和维护方式，再决定是否在自己的 marketplace 或受管环境分发。