服务对象与地域限制
PuppyIP 仅面向海外合规企业及其授权人员提供服务,不面向中国大陆地区开放或提供代理服务。本服务仅限用于中国大陆境外的合法业务活动,严禁在中国大陆境内使用本服务。
代理 IP 或服务器位于境外,不改变上述限制。不得通过中转、转接、共享或转售向中国大陆境内的最终使用者提供本服务。使用前请阅读用户服务协议。
本文要点
- Mods 在 Claude Code 内处理事件,可加入面板、命令或修改工具调用;它与传统 settings hooks 的运行方式不同。
- v2.1.289 于 10 月 3 日 23:07 UTC 发布,修复升级后首个会话不加载已安装 Mods 等问题;对应北京时间 10 月 4 日。
- 终端和 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 日核验文档,未在读者环境中实际安装运行。
10 月 3 日 23:07 UTC 正式发布的 v2.1.289 又修复了升级后首个会话不加载已安装 Mods,以及本地文件夹 marketplace 的插件列表、评估和更新仍显示旧副本的问题。刚升级却没有 Mod 时,先核对实际运行版本,避免立即删除配置。
该版还修复受管机器上,复合 shell 命令内部的 deny 或 ask 规则被用户安装 Mod 的批准覆盖,以及 IDE 通过符号链接引用文件时 Read deny 未生效的问题。VS Code 的频繁登出则可能与 v2.1.288 的 claude auth status 变更有关,289 已回退该变更。修复有明确场景,不代表所有权限或登录问题都已解决。
升级到包含修复的版本,再重新确认
原生安装可运行 claude update;npm 安装可执行 npm install -g @anthropic-ai/claude-code@latest。完成后重新启动 Claude Code,再执行 claude --version。不要把旧会话仍在运行理解成已经使用新版本;claude doctor 可查看安装状态与最近更新尝试。
Homebrew 用户按原安装项执行 brew upgrade claude-code 或 brew upgrade claude-code@latest;WinGet 用户执行 winget upgrade Anthropic.ClaudeCode。软件包渠道可能晚于公告提供版本,命令成功仍需检查版本号。若结果未达到 2.1.289,先查看更新渠道和组织版本限制。
stable 通常晚于 latest,不保证新修复刚发布就能取得。原生安装可在 /config 查看 Auto-update channel;Homebrew 由 cask 名称决定渠道。团队用户先按管理员安排升级,不通过关闭限制强行切换。升级后重做一次插件加载和最小功能检查,确认原症状是否消失。
Mods、插件和 hooks 应该怎么选
插件是分发和安装的容器。Mod 是其中使用 JavaScript 或 TypeScript 事件处理函数的部分,函数在 Claude Code 内执行,能够观察、改变或接管特定事件。一个插件也可以同时带 Skill、MCP 服务和其他组件,所以看到插件已安装,还不能直接推断 Mod 正在运行。
可以从要交付的结果倒推选择:重复说明一套工作方法,用 Skill;让现有脚本在指定事件后运行,先看 settings hooks;接入外部工具,考虑 MCP;需要在会话界面增加可交互面板,或组合更细的事件处理,再评估 Mod。这样也更容易为失败定位负责的组件。
安装前确认三件事
第一,在终端执行 claude --version,确认至少为 v2.1.287;若处理升级后首个会话加载失败或上述权限问题,还要确认版本已包含 v2.1.289 修复。第二,确认插件作者与 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 会话的结论。若只在某个客户端看不到内容,先在支持该界面的终端确认加载状态和行为,再向作者报告客户端差异。不要一开始就清空全部配置或重新安装所有依赖。
处理 VS Code 登录或 IDE 文件引用问题时,还要在 Extensions 中检查 Claude Code 扩展版本:面板使用扩展自带的 Claude Code,终端 CLI 升级不等于扩展已更新。更新扩展并重新加载窗口后再检查;仍显示未登录时使用面板 Sign in,登录界面未出现可执行 Developer: Reload Window。无需先删除凭据或清空配置。
自己做第一个 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 不计入这条活动名单。
刚更新完 Claude Code,Mods 却没有加载怎么办?
先重新启动并执行 claude --version。v2.1.289 修复了升级后首个会话未加载已安装 Mods 的问题;若仍运行较早版本,检查安装渠道和组织版本限制。已包含修复仍失败时,继续检查插件状态与加载日志,不要直接清空配置。
VS Code 里看不到 Mod 面板就是失败吗?
不一定。当前 VS Code 聊天面板可执行已加载的 Mod hooks,但不绘制它的界面。应根据该客户端支持的输出方式确认行为。
关闭 sandbox 能解决 Mod 不工作吗?
不应把关闭 sandbox 当成此类通用排错。Mod 本身并不受该 Bash sandbox 隔离,应查版本、模块校验、加载状态与组织策略。
Mods 会让 Claude 额度变多吗?
不会因安装 Mod 自动增加套餐或 API 额度。Mod 调用模型时可以消耗现有用量,是否额外发起请求应查看其说明与代码。
官方示例可以直接用于生产团队吗?
官方将 playground 示例按现状提供,不承诺支持。团队应先确认其行为、权限和维护方式,再决定是否在自己的 marketplace 或受管环境分发。