Claude Code 的 v2.1.261 更新我最先注意到的是 changelog 里那行新增 /skill-doctor。说实话这名字差点让我以为团队给 Claude 写了个全科医生插件。用过一段时间 Claude Code 的人应该都有体会自定义 skills 一多排查为什么这个技能不触发比写代码本身还折腾。v2.1.261 除了新增这个诊断命令还补上了输出上限配置同时清理了一批历史 bug。这篇文章我就从自己几天的实际使用出发把这版更新拆开讲新功能怎么用、参数怎么调、升级后会碰到哪些坑以及和 Codex、VS Code 插件、本地模型搭配这些热门话题里的实操经验。1. 这次发布解决了什么从 changelog 背后看改进方向v2.1.261 的 changelog 不算长信息量却很大。团队像是集中还债——之前长期被人诟病的问题这次一口气修了一批。我翻完更新说明又去社区看了几圈反馈能明显感觉到这次更新的目标不是堆新功能而是把日常用着别扭的地方一个个填平。1.1 /skill-doctor 与输出上限配置两个新功能的价值先说 /skill-doctor。Agent Skills 是 Claude Code 里很受关注的一块能力简单说就是你可以把一组指令、模板、脚本打包成一个技能放在项目的.claude/skills目录下让 Claude 在合适的时候自动调用。比如写 PPT 的时候读一份大纲模板查数据库的时候执行一段 MCP 配置做代码审查的时候套用团队规范。但技能一多问题就来了为什么我明明放好了 skill 目录但让它执行时它就像没看到一样description 写得不精确、frontmatter 字段拼错、路径多了一层、名称和触发词对不上每个原因都能让你排查半小时。/skill-doctor 就是干这个的。我在对话里敲这个命令后它会扫描当前项目可识别的技能列表校验 skill.md 的格式检查文件路径和命名是否符合规范然后把异常项列出来相当于给 skills 做了一次全面体检。对我这种喜欢堆技能的人来说这个命令就是官方版的故障排查工具。max_output_tokens 输出上限配置则是另一个维度。Claude Code 默认对单次输出有 token 上限当回答太长时会被截断。以前用户想放大上限得绕路去改环境变量或者换模型配置不够优雅。v2.1.261 把这个参数放到了官方设置层面支持在 /config 里直接修改也可以在 settings.json 里写死。对跑长任务的人来说这是一个几乎每天都会用到的基础能力。1.2 修复清单里的高频痛点这次修复的问题翻一下社区反馈能看出几个方向中文乱码Windows 系统下终端字体和代码页设置不对时输出经常出现乱码这次针对输出编码做了修复。PowerShell 环境兼容用 Windows 自带 PowerShell 安装时经常报错问题多出在执行策略和脚本签名校验新版本调整了安装脚本的兼容逻辑。模型识别报错部分自定义模型名不被当前版本识别报错提示比以前更明确。对话历史保存之前不少人反映对话记录没有自动持久化或切换会话后上下文丢失这次修了一部分。MCP 工具稳定性接数据库等外部工具的 MCP 场景连接中断和超时问题有改善。这五个方向几乎全是真实使用中最高频的抱怨点。可以看出团队在用户反馈收集上还是很到位的。我的建议是如果你之前在 Windows 上遇到过乱码升级后顺手清一下终端配置文件很大概率能解决老问题。1.3 升级节奏与建议Claude Code 的更新频率一直很快v2.1.x 系列几乎每周都有小版本。这里有个实用的建议不要太勤地追每个小版本也不要长期停在旧版。我个人的节奏是如果当前项目正在稳定跑一个长任务我会等它跑完再升级平时开发间隙则随时升级因为新版本通常带着 bug 修复早升早受益。升级方式如果是 npm 全局安装的直接npm update -g anthropic-ai/claude-code就好如果是桌面版客户端会自动提示更新。升级完第一件事我会跑一遍 /status 确认版本号检查环境参数没有被重置再继续干活。尤其是 settings.json 里的自定义配置某些版本升级后有被覆盖的案例备份一份总没坏处。2. /skill-doctorSkills 故障的体检工具别再手动翻目录了2.1 Skills 到底是啥为什么值得折腾在讲 /skill-doctor 之前得先把 skills 这件事说清楚。Agent Skills 的规范是每个技能是一个目录目录下有一个 skill.md 文件文件顶部用 frontmatter 块写明 name 和 description正文写具体的指令、示例、操作步骤。Claude Code 会在用户对话时根据 description 自动判断是否调用这些技能。技能目录可以放在两个层级项目级.claude/skills下和用户级~/.claude/skills下。项目级的跟随仓库走适合团队共享用户级的全局生效适合装你自己的常用技能。有些技能还支持子模块比如一个数据库查询技能下可以挂多个 SQL 模板文件一个PPT 生成技能下可以放大纲模板和版式规范。技能多了之后命名冲突、目录结构错误、描述不清晰这些问题会越来越多这正是 /skill-doctor 要解决的。2.2 用 /skill-doctor 排查技能故障的完整流程我在 v2.1.261 升级完后第一件事就是跑了一遍 /skill-doctor。整个排查路径大致是这样的第一步敲/skill-doctor它会列出当前环境识别到的所有技能包括项目级和用户级的并显示每个技能的状态。第二步状态为警告或错误的技能它会给出具体原因比如 frontmatter 里缺少 name 字段、description 太短、目录路径不对、或同名技能冲突。第三步部分问题它可以给出修复建议比如提示你应该把目录放在哪个路径下。有个很典型的案例。我写过一个叫 weekly-report 的小技能用来生成周报草稿description 写的是 generate a weekly report。但实际跑的时候它怎么都不触发。我用 /skill-doctor 一查原因有两个一是目录名是 weekly-report和 frontmatter 里的 name 不一致二是 description 太泛模型无法区分它和另一个 generate report 技能。改完这两个点重新触发就正常了。这种问题以前要手动比对目录结构和描述文本才能发现现在一条命令就查出来了。2.3 实测中的注意事项用 /skill-doctor 有一个细节要注意它扫描的是当前进程能感知到的技能集合。有些技能是插件提供的路径不在.claude/skills下如果没扫描出来大概率是插件加载层的配置问题而不是技能本身写错了。这时候要回头查插件安装状态别在 skill 目录上死磕。另外技能触发与否description 的质量是关键。我的经验是description 里最好包含触发场景和排除项。比如当用户提到写周报、汇总工作进度、整理周总结时使用仅用于周维度的汇报不用于每日站会记录。描述越具体模型越不容易误调或漏调。/skill-doctor 不会帮你推荐更好的描述文案但能帮你发现描述过短、格式错误这类硬伤。还有一个常见误解/skill-doctor 不是用来执行技能的它只诊断不运行。想测试技能是否真的好用还是在正常对话里触发它看实际执行效果。两者配合才能构成完整的技能维护闭环。3. 输出上限配置max_output_tokens 怎么用、怎么调3.1 输出上限到底是什么为什么默认值既够用又不够用max_output_tokens 控制的是 Claude Code 单次响应的最大输出 token 数。token 是模型处理文本的最小单位一个中文词大概占一到两个 token。默认值在多数版本里是 32000 左右——这是一个够用但不是全能的值。日常写代码、改文件、修 bug32000 token 完全够用但如果你让它一口气重构一个大型模块、生成一份完整的技术方案文档、或者一次性输出超长内容时就容易撞到上限回答被截断。被截断的表现很典型代码块突然结束在中途、最后几行建议凭空消失、或者继续对话时说我还没讲完。以前我遇到这种情况通常只能让模型继续从 xxx 处写既费 token 又费时间。v2.1.261 把输出上限做成正式设置项后跑超长任务前我会主动调高平时则调回一个合适的值来控制成本。3.2 三种配置方式哪种适合你第一种最常用的是在对话里敲/config。新版里输出上限会出现在配置列表里按提示修改即可。这种方式的优点是即时生效不需要重启。第二种写 settings.json。在用户目录的.claude/settings.json里加上输出上限相关字段具体字段名以你本地 /config 里看到的为准适用于需要固定配置、跨项目保持一致的情况。第三种环境变量方式适合在 CI/CD 或者脚本化调用 Claude Code 时使用把值注入到运行环境里。我的习惯是项目上有特殊需要就在项目级配置里改个人默认值保持相对较小的数值。比如平时用 32000只有预感到要跑大任务时才临时改到 64000 或更高。这样可以避免日常对话因为输出上限过高而产生不必要的 token 消耗——毕竟大模型输出是有成本的。3.3 调多少合适我的经验值这里直接分享几个实测过的场景和建议值场景建议值理由日常改代码、修 bug12000-16000响应快成本低普通任务不会触发截断代码生成、文件重构20000-32000给较长的输出留出空间长文档、全量方案32000-64000 甚至更高减少截断但要注意等待时间实测中有一个问题调高输出上限后如果中间有某一步卡住等待时间会明显变长。有一次我为了生成一份完整架构设计文档把上限调到了 64000结果中间步骤处理得慢整体响应接近一分钟。所以别一味追求越大越好平衡很重要。另外输出上限设置的是单次请求的上限不是整个对话的上限。对话本身还会累积上下文两者要分开理解。4. 升级后最容易踩的坑从热搜词看真实用户场景4.1 模型识别不匹配升级后常见的一个报错是类似 glm-5.2 is not a model this version of claude code recognizes。这通常发生在自定义配置了第三方模型名、或通过兼容端点接入其他模型时。Claude Code 的部分版本对模型名校验很严格识别不了就直接报错。解决办法有几个改用官方模型名检查配置里有没有二次映射或者升级到能识别该模型名的版本。注意如果模型名写的是你自己起的别名版本不认识也别慌先检查拼写和配置层再考虑是否要换模型名。4.2 Windows PowerShell 安装报错另一座高频大山是 PowerShell 报错。安装脚本执行时报禁止运行脚本或签名校验失败本质是执行策略限制。解决办法有两条路一是用管理员身份打开 PowerShell运行Set-ExecutionPolicy -Scope CurrentUser RemoteSigned二是改用 cmd 或非 PowerShell 环境执行安装。另外有些报错跟 Node.js 版本也有关建议 Node 保持在 18 以上太老的版本会遇到依赖安装失败的问题。4.3 乱码问题与对话历史保存升级前中文乱码是最常被吐槽的问题之一。Windows 上出现乱码根源通常在于终端代码页和 UTF-8 编码不匹配。新版本修复了不少但如果你升级后还有乱码可以检查终端的编码设置把代码页切成 UTF-865001。至于怎么保存对话历史这个问题搜索量一直很高其实 Claude Code 的会话历史默认是存在本地的/resume 可以恢复之前的对话。如果发现历史没保存多半是启动目录不对或者版本太老优先升级并确认启动位置问题就能解决。4.4 接第三方模型和本地模型时的注意点很多人在做通过兼容 API 接入第三方大模型比如 DeepSeek或本地模型比如 Ollama也有人用配置切换工具在不同服务商之间来回切。这类做法可行但要注意几个点一是第三方服务的上下文长度和输出上限不一定和 Claude Code 默认值匹配需要你自己显式配置二是工具调用的格式要做适配不然模型能聊但没法实际操作文件三是 MCP 连接本地模型接 MCP 数据库工具时稳定性取决于模型本身遵循工具格式的能力跟客户端关系不大。v2.1.261 修复了部分 MCP 连接问题但接得好不好最终还是看模型能力。为了便于对照我把升级后常见问题整理成一张速查表问题典型表现常见原因处置模型不识别报错 X is not a model模型名拼写错误或版本不支持检查模型名、升级版本PowerShell 安装失败提示禁止运行脚本执行策略限制Set-ExecutionPolicy 调整中文乱码输出乱码终端代码页非 UTF-8切换 65001 编码对话历史丢失/resume 无记录工作目录不对或版本太老升级、确认启动目录MCP 连接不稳定工具调用超时模型或网络层问题更新模型版本、重连测试5. v2.1.261 实测体验与后续建议5.1 高强度使用后的感受我升级后跑了几天包括重构一个 Python 服务、写两份技术评审文档、调试一个数据库查询的 MCP。整体感觉是响应稳定性比上一个版本好之前偶尔出现的上下文丢失问题在这几天里没再遇到。/skill-doctor 让我把积压的多个技能全部检查了一遍找出两个描述不规范的问题。修复之后技能触发率明显提高。输出上限配置是真正省心的改进长任务前提前调高不用再看着回答被截断干着急。5.2 省 token 的几个实用技巧热搜里有一堆人搜claude code 如何省 token我实测下来比较有效的做法一是善用 CLAUDE.md 项目说明文件把指令固化减少重复强调二是用 /compact 压缩上下文长对话后能清掉大量历史噪声三是控制输出上限按下节说的场景区分设置四是利用技能把常用操作包装成模板省去每次重新描述的成本。另外出现过类似 your limits are temporarily boosted 的配额提示后就别再开太多长任务并行跑了优先级放给最核心的那个任务。5.3 Codex 还是 Claude Code我的选择这个话题最近很热。Codex 和 Claude Code 都是终端型 AI 编程助手核心差异在模型、工具链和生态。Claude Code 在长上下文理解、复杂多文件修改上表现稳定Agent Skills 和 MCP 生态也比早期丰富很多Codex 的优势在于 OpenAI 生态和部分场景的执行效率。我的建议是别纠结哪个更强而是看你的主力模型和既有代码库在哪。喜欢 Anthropic 模型的直接选 Claude Code依赖 OpenAI 生态、经常用 ChatGPT 的可以试试 Codex。有条件的话两个都装不同任务用不同助手这很正常。5.4 对后续版本的一个小期待再说一个私心期待。v2.1.261 把技能诊断和输出上限都补上了下一步希望官方能强化技能共享能力——现在技能还是以本地目录和插件为主如果能直接拉取社区技能包、并在安装时自动调用 /skill-doctor 做检查团队协作的效率会高很多。目前来看Claude Code 在持续补齐开发者体验的短板每一个小版本都有看得见的进步这种迭代节奏对用户来说确实是好事。我升级 v2.1.261 后做的第一件事就是把 /skill-doctor 跑了一遍把一直没排查好的 weekly-report 技能修好了。那种原来问题出在这里的舒爽感大概是每个用过 skills 的人都能共鸣的。建议你也升级后先跑一下这个命令顺便把输出上限按自己的任务习惯调好——这两个小改动能让你接下来用 Claude Code 的体验舒服不少。