我用 Claude Code 用了大半年一直觉得它哪都好就是官方行为太硬。想让它干活前先列个计划、执行命令前多问一句都得靠改系统提示词或者塞一堆 command hooks 去绕。直到 2.1.287 这个版本把 Mods 插件机制扶正我才感觉到这工具终于把行为本身做成了可插拔的单元第三方插件能真正改写 Claude Code 的工作方式了。这篇东西不打算写成 changelog我想从一个实际使用者的角度聊聊Mods 到底改变了什么玩法、怎么把环境先跑稳、如何装现成插件、怎么写一个最简的 Mods以及大家都关心的第三件事——怎么把 Claude Code 接到 DeepSeek、Qwen、GLM 这类模型上。文末还会把我踩过的几个坑一并交代都是能直接复用的经验。1. Mods 到底带来什么变化从补丁式配置到行为单元1.1 升级后看到的第一个变化事情是这样的某天我照常执行claude update发现版本跳到了 2.1.287启动后新增了claude mods命令族。当时没太在意直到我敲了下claude mods --help才发现它支持 install、list、validate 这些子命令原来官方把改行为这件事做成了一套正式机制而不是靠用户在配置里东拼西凑。再说直白一点以前你想让 Claude Code 在每次动手写代码前先输出一个影响范围分析能做到但很别扭——要么写进 CLAUDE.md 全局提示词要么挂一个 SessionStart hook 往上下文里注入一大段话。现在不一样了Mods 可以声明我监听什么场景、触发后注入哪些行为约束、也可以拦截工具调用并且能按项目、按目录、按文件类型去匹配。这就等于给 Claude Code 装上了行为触发器而不是单纯加提示词。1.2 Mods 与 command hooks 的分工我见过有人问Mods 和 hooks 是不是一回事我的理解是hooks 是某个事件发生后的回调它的执行逻辑是写在外部脚本里的Claude Code 本身只负责在对应时机调你的脚本而 Mods 更像一套自带匹配规则和行为定义的常驻插件包。用个粗浅的类比吧hooks 像你把钥匙交给门卫门卫按你的清单在特定时刻做特定动作Mods 则像你直接改了大楼的门禁系统——定义了什么人、什么时间、进哪扇门、需要遵守什么规则。所以 Mods 能做的不仅是执行一串命令它还能改变 Claude Code 在某个场景下的输出格式、工具选择偏好、甚至拦截某些高风险操作。hook 是战术级别的补丁Mods 是行为层面的框架。1.3 三个立等可取的真实玩法光说概念没意思我列几个 2.1.287 之后社区里高频出现的 Mods 方向你感受下这类插件的边界终端命令安全网。写一个 Mods 匹配 Bash 工具调用遇到git push --force、rm -rf这类命令时不直接放行而是先输出风险提示并要求确认。这个如果放在以前得靠 PostToolUse 之后去做日志审计根本拦不住执行前的动作。输出格式规范化。比如检测到代码块里有数学公式时自动用更友好的 Markdown 数学语法重排说明这就和社区里常见的 Markdown 数学公式插件思路一致只是现在它可以作为一个独立的 Mods 分发给别人。项目上下文自动补充。进入一个新目录后自动扫描 README、目录结构把项目概况塞进上下文省去每轮手动ls的功夫。这三个方向有一个共同点它们都在改变 Claude Code 的“默认决策”而不是简单拼一段提示词。这正是 Mods 机制值得关注的原因。2. 把环境先跑顺安装、升级与目录结构观察2.1 全平台安装与升级路径先补基础。Claude Code 目前最常见的安装方式还是 npmnpm install -g anthropic-ai/claude-code装完之后验证版本claude --version如果你在 VSCode 或 Cursor 里用官方也提供了桌面版和编辑器扩展本质都是同一套 CLI 引擎只是调用入口不同。有人问我 Cursor 里能不能用我的做法是直接在终端里装 CLI再在 Cursor 的终端面板里跑claude这样所有配置都共享不用为每个编辑器单独配环境。升级的话官方支持在线升级claude update升级前建议看一眼当前版本和目录里已有的 Mods 兼容性。2.1.287 这个版本后我明显感觉到 Mods 相关的配置变动变勤了大版本升级前最好先claude mods list看下有没有行为冲突的提示。2.2 ~/.claude 目录里到底有什么想玩 Mods第一件事是把家目录下的~/.claude结构摸清楚。我实际使用中的目录大概长这样~/.claude/ ├── settings.json ├── CLAUDE.md ├── plugins/ ├── mods/ ├── projects/ ├── statsig/ └── shell-snapshots/其中settings.json是全局配置入口mods/是我自己安装和放置 Mods 的地方projects/下面按项目路径记录历史。安装 Mods 之前我建议先看一眼settings.json里有没有被旧版插件写入过什么奇怪字段免得装完插件后互相覆盖。如果mods/目录还不存在不用慌执行一次claude mods install或者手动创建即可。目录没建好的时候claude mods list会输出一个空列表但不报错。2.3 那个note: claude code might not be available in your country提示我猜很多国内用户卡在这一步。启动 Claude Code 时终端偶尔会蹦出类似note: claude code might not be available in your country. check supported countries...的提示。这段提示我见得不算少但它并不一定代表你的账号有问题。从我排查的经验看这个提示和账号注册区域、当前网络链路都有关系。Claude Code 启动时会做一次可服务区域的检查如果检查不通过交互可能被降级甚至直接退出。常规处理思路是先确认账号注册区域是否在官方支持清单内再检查当前网络链路和账号区域是否一致。很多人的做法是把官方入口从链路里摘出去——也就是下面第四节讲的用第三方兼容端点接自己的模型 Key让 Claude Code 变成纯壳层执行器这样它访问的是你自己的模型服务商自然不依赖官方可用性。这个方法既干净又合规我后面会详细展开。2.4 登录与不登录的差别也有不少人纠结到底要不要注册账号。我的实测结论是如果你只用第三方模型不登录完全能跑通claude会进入本地执行模式但如果你想用官方模型、云同步会话记录以及跨设备恢复上下文那就必须登录。注册账号与否不影响 Mods 的加载逻辑——Mods 是在壳层执行的模型是谁并不关键。使用方式官方模型Mods机制第三方模型接入云同步登录账号可用完整可配可用不登录受限完整可配不可用我自己是不登录第三方 API为主力工作流登录账号只用来偶尔跑官方模型对比效果。3. 从安装到编写第一款能改变行为的 Mods 插件3.1 先装一个现成的命令确认增强 Mods空对空聊模板没有意义我先说一个我实际装过的 Mods给终端命令增加执行前确认。这个需求很典型因为 Claude Code 默认对 bash 工具的执行比较果断有时候让它查个目录它都能给你递归列半天更别提让它 push 代码。安装命令大致是claude mods install 某个命令安全类插件装的时候它会问你作用域——user还是project。我建议先选project因为全局作用域一旦装多了后面排查冲突非常痛苦。装完用claude mods list确认它在列表里。然后随便让它跑一条rm或git push你会看到输出里多了一层风险提示不再像以前那样闷头执行。这就是 Mods 通过行为匹配改变工具调用的直观感受。3.2 自己写一个最简 Mods先理解行为配置文件结构装现成的不算本事我们来写一个。假设我要做一个代码审查强制模式的 Mods当 Claude Code 准备运行命令或生成补丁时强制先输出一段审查清单。第一步在项目目录下建.claude/mods/目录或者直接在~/.claude/mods/下建一个独立子目录。以项目级为例my-project/.claude/mods/ └── review-mode/ ├── mod.toml └── behavior.mdmod.toml是声明文件里面写行为命名、匹配范围、启用的钩子。一个极简例子长这样name review-mode version 0.1.0 description 在生成补丁或执行敏感操作前强制输出审查清单 [hooks.SessionStart] enabled true [hooks.PreToolUse] tool Bash enabled true [behavior] match [patch, commit, push, review] action strict_check严格说不同版本的字段命名会有出入但核心结构就是一个身份声明、一个钩子绑定、一组匹配规则、一个行为指向。behavior.md里写触发后的具体行为描述Claude Code 会把这部分内容注入到你声明的场景上下文里让模型照着执行。3.3 钩子ID与匹配规则Mods 的触发开关Mods 的行为触发高度依赖 hooksID这是我花了不少时间才理顺的点。所谓 hooksID就是官方定义的那些可挂钩事件点常见的有钩子ID触发时机典型用途SessionStart新会话开始时注入项目背景、加载Mods规则PreToolUse工具调用之前拦截/校验/改参数PostToolUse工具调用之后结果分析、格式化ResponseCreated响应生成时调整输出格式UserPromptSubmit用户提问提交时改写用户问题匹配规则match则是判断当前场景是否命中的条件可以按文件名、目录前缀、工具名、关键词等维度写。比如我只想让审查模式在涉及git commit或协作场景下生效就写match [commit, push]。匹配规则写宽了后果就是什么场景都触发反而拖慢正常任务。3.4 运行验证与调试配置写好后用claude mods validate先验证有没有语法问题然后进入项目目录跑一次claude用一条命令看它能不能按 behavior 输出。我调试 Mods 时的固定套路是开一个--debug会话配合claude mods list --verbose看每个 Mods 的命中状态。如果触发没生效最可能的原因是 hooksID 拼写不对或者匹配规则没覆盖到你测试的场景。这时不要猜直接在 behavior.md 里加一句请输出你当前加载的行为规则名称作为探针让模型把它看到的东西打印出来。这招比翻日志快得多。4. 把 Claude Code 接到 DeepSeek、Qwen、GLM第三方模型接入技巧4.1 先说清楚Claude Code 是一个壳层很多人以为 Claude Code 只能配 Claude其实是误解。它的本质是一个 agent 壳层——负责交互界面、工具调用、上下文管理和 hooks 触发真正的大脑是模型后端。官方默认只接 Anthropic 家的模型但底层支持通过环境变量替换 API 端点。这就解释了为什么社区里流传一句话有了 Claude Code你相当于免费拿了一套 agent 工作台模型随便接。前提是你熟悉第三方 API 的使用技巧知道协议怎么转换。4.2 最小配置方案环境变量加兼容端点Claude Code 原生的 API 协议是 Anthropic 格式而 DeepSeek、Qwen、GLM 都只提供 OpenAI 兼容接口。所以要做的中间步骤是加一层协议转换层。网上常见的方案有两种一是用一套本地代理把 OpenAI 兼容接口转成 Anthropic 格式二是直接找支持 Anthropic 转发的 Gateway 类服务。配置核心就三个环境变量export ANTHROPIC_BASE_URLhttp://你的转换层地址 export ANTHROPIC_AUTH_TOKENsk-你的模型Key export ANTHROPIC_MODELdeepseek-chat # 或 qwen3-235b / glm-4.6设置好之后在项目目录直接跑claude它会走你指定的端点去请求第三方模型。这类接入方式对 Mods 完全透明——因为 hooks 和 Mods 逻辑都跑在壳层跟模型是谁没关系。4.3 CC Switch 这类工具省在哪配置环境变量本身不难难的是频繁切换模型。今天用 DeepSeek 做批量整理明天用 Qwen 跑推理来回改环境变量太痛苦。热词里提到的 CC Switch 就是干这个的社区工具。我实际用下来CC Switch 的核心价值是把不同供应商的 Base URL、Key、模型名、附带参数存成一套配置然后用命令快速切换。比如cc-switch use deepseek-v4 cc-switch use qwen3每次切换会更新 Claude Code 进程读取的环境变量然后就开一个新会话继续干。省去手改.bashrc的功夫。如果你不想装第三方工具自己维护几个 shell 脚本切换ANTHROPIC_BASE_URL和ANTHROPIC_MODEL也完全可以区别只是手感。4.4 换模型后的行为差异和踩坑接第三方模型之后有四个坑几乎人人会踩第一工具调用格式差异。部分模型官方的 function calling 收敛度不够Claude Code 发出去的 tool call 它可能接不住表现出来的症状就是模型一直说废话不调用工具。解决办法是尽量选对工具调用优化过的版本或者把 Anthropic 转换层上的max_tokens调大避免输出没写完就被截断。第二指令遵循能力的差别。DeepSeek 系在长文本和中文指令上挺稳但对极简的 system prompt 更敏感Qwen 系有混合推理模式某些版本会默认先输出一段思考过程再给答案这会导致工具调用延迟。如果不想看思考过程记得在其 API 参数里关掉推理开关。第三上下文窗口不一致。Claude 模型默认给 200k 上下文其他各家模型窗口不一窗口小的模型在超长会话里表现会明显变差。我的处理方式是按需开新会话别指望 10 万 token 的会话让每个模型都扛住。第四Mods 行为文案别写太重。第三方模型的指令遵循能力不如 Claude 强一个 Mods 里塞 500 字行为约束它可能只执行一半。我的经验是把行为拆成小步每步一个明确动作再配上输出样例比长篇大论管用得多。5. 实踩的坑行为叠加、失效判定与团队共享5.1 同一个工具被多个 Mods 拦截怎么办装了三个 Mods 之后我遇到的第一个问题同一任务命中多个行为规则而它们互相打架。比如一个 Mods 要求执行命令前确认另一个 Mods 要求所有命令静默执行并自动纠错两个都挂在PreToolUse上Claude Code 会按加载顺序叠加处理结果就是会话变得很分裂——有时候确认、有时候不问。解决办法是在mod.toml里把匹配范围收窄加上项目名或工具名限定。另一个思路是明确优先级官方加载规则一般有先后顺序你可以先claude mods list看顺序再把冲突的那个作用域改成project让项目级规则覆盖全局规则。5.2 Mods 失效的两种假象行为过期和匹配写宽失效问题有个隐蔽的细节。第一种假象是行为过期——官方提示词结构升级后Mods 里写的上下文约定可能不再匹配新版行为框架导致行为注入后模型看到了但不遵守。这时claude mods validate往往还是通过的真正的判断标准是你测试用例的输出有没有变化。我处理的方式是在 behavior.md 里写明目标行为的具体输出样例一旦模型输出偏离样例基本就是过期了。第二种是匹配规则写得太宽看起来像失效实际是每条请求都命中了反而让模型行为被稀释。比如我的一个插件把match写成[*]结果它在任何场景都注入一段长长的审查约束把正常任务拖得又慢又啰嗦体感上就像没装。排查方法很简单临时把匹配范围改成非常窄的一个关键词如果行为恢复正常就是规则太宽的问题。5.3 团队共享把 Mods 变成项目资产Mods 另一个让我真香的点是它可以进 git。把.claude/mods/放在项目仓库里之后团队每个成员 clone 下来只要装了同样版本的 Claude Code就能共享同一套行为规则。这个太适合规范统一了——代码审查规则、命令安全策略、输出格式标准全都可以作为 Mods 沉淀进仓库而不是靠口头传。注意一点settings.json里如果写了user级 Mods 的绝对路径换机器后大概率失效。所以团队共享时统一用项目级.claude/mods/别把路径写死。5.4 最后再分享一个判断 Mods 是否生效的土办法我调试 Mods 时很少纯看状态输出更常用的做法是故意制造一次触发器然后观察模型的行为变化。比如写了一个检测 README 并总结项目的 Mods那就先在项目里放一份特殊的 README 文件看它是否在会话开始阶段主动提到 README 里的关键信息。如果提到了说明行为注入链路是通的如果没提先查 hooksID再查匹配规则基本两步就能定位。这个方法看起来土但比任何状态命令都可靠。因为 Mods 的最终效果是模型行为的改变而不是某个脚本有没有执行。你把观察目标定在行为输出上就不会被中间层的信息迷惑。我对 2.1.287 最大的感受是Claude Code 从一个好用的专用工具变成了一个可以按需改装的通用工作台。Mods 机制把行为拆成了可声明、可匹配、可共享的单元配合第三方模型接入你完全可以拼出一套适合自己或团队的工作流。如果你还在观望我的建议是从一个最痛的需求开始——命令安全确认、输出格式化、项目上下文注入挑一个写个最简版本跑起来。先跑通再谈完善Mods 的回报率确实比我预期的高。
