Claude Code 2.1.228：那个把自定义请求头送进错误 tier 的 settings 合并 bug

2.1.228 里影响最大的修复，不是大多数人先看到的那一条。

Vertex AI 凭据快速失败的改动确实显眼，因为它把一段几分钟的重试等待缩短到了几秒。但 settings 合并 bug 的影响范围更隐蔽，而且完全无声。在任何把同一个 marketplace 条目定义在多个 settings tier 里的部署中，低优先级 tier 的 custom-headers 字段可能会悄悄合并进高优先级 tier 的那份定义，全程没有任何警告。

发生了什么

Claude Code 2.1.228 于 2026 年 8 月 11 日发布，集中修复了三个运营层面的问题。

Settings tier 隔离（安全）。 当同一个 marketplace 条目在多个 settings tier 都有定义时，比如 workspace 级别定义了一次、用户级别又覆盖了一次，高优先级 tier 的条目理应只使用它自己层级里声明的 custom-headers。旧逻辑按字段逐一合并，导致低优先级层级的请求头可能流入高优先级条目。修复后，marketplace 条目整体合并，不再拆字段继承。

Vertex AI 凭据失败提速。 使用 CLAUDE_CODE_USE_VERTEX=1 时，如果 Google Cloud 凭据过期或缺失，旧版本会不断重试，通常要等好几分钟才报错。新版本在识别到 ADC 状态异常时直接短路，几秒内就能返回错误。改动在于 SDK 握手层，不是重试次数。

从 claude.ai 同步的 skill 加固。 从云端同步下来的 skill 不再能覆盖同名的本地命令或 MCP prompt。它们的描述经过清理和标记，本地机器上同步下来的 skill body 也不能执行 ! shell 命令，也不能展开 @ 文件引用。这堵上了一条供应链路径。之前一个上传到 claude.ai 的 skill，有可能在另一台机器上用展开机制读取文件内容。

Write tool 行为变化。 更新的模型版本现在可以覆盖写入一个本次 session 里没有读过的文件，和 Edit tool 的规则对齐。旧版本模型仍然要求先读后写。这是能力扩展，工具权限模型本身没变。

为什么 AI 工程团队需要关注

请求头泄漏 bug 的危险在于它完全沉默。没有警告，日志里看不到异常。如果团队在 workspace 层级为某个 marketplace 集成配置了认证 header，然后在用户层级重新定义了同一个条目，用户层级的条目可能带着 workspace 层级的 auth header 发出请求，正好和最小权限原则相反。

触发条件有一定局限性。同一个 marketplace 条目 ID 必须同时出现在两个或更多 settings tier，且低优先级 tier 里有 custom-headers 字段。只用单 tier settings、或 marketplace 条目只在一处定义的部署不受影响。但这类 bug 属于悄悄改变安全姿态的那种，任何可观测性管道都看不到它。

Vertex AI 的修复意义不同。如果你的 Claude Code 部署把 Vertex AI 作为其中一条 provider 路径，过去凭据失效会让 session 卡住好几分钟才触发 fallback，上游调用者很容易先超时，制造出类似故障的假象。秒级失败让路由层能在正常请求预算内做出 fallback 决策。

Router/operator 视角

现在就审计 marketplace settings tier。 用 claude settings list 在每个 settings tier 里列出配置，找出在多个 tier 都有定义的 marketplace 条目，对比其中的 custom-headers 值。如果高优先级 tier 里的值不是你预期的，说明在 2.1.228 之前这个 bug 已经影响到了你的部署。修复改变的是后续行为，不会追溯之前的 session。

Vertex AI 快速失败改变了你的错误分类预算。 如果你同时跑 Vertex AI 和其他 provider，并在 Vertex 失败时配置了 fallback，2.1.228 之前 Vertex 凭据问题会占用几分钟重试时间才触发 fallback。修复后凭据错误能在单次请求超时窗口内暴露，路由层可以及时切换。如果你之前专门给 Vertex provider 设置了宽松超时来吸收重试延迟，现在可以收紧这个值，和其他 provider 对齐，不会错杀正常请求。

Skill 同步加固是一条供应链边界。 旧行为下，从 claude.ai 同步的 skill 可以覆盖同名 MCP prompt，也可以在 skill body 里通过 ! 命令执行任意 shell 指令。在多团队共用企业账号的场景下，一个团队上传的 skill 有可能干扰另一个团队本地的 MCP 配置。修复后，同步的 skill 有独立沙箱，不能覆盖，不能执行 shell，描述经过清理。如果你有自动化流程依赖从 claude.ai 同步的 skill body 执行 ! 命令，2.1.228 之后这些 body 不会再运行，需要改成显式工具调用。

Write tool 变化需要注意模型版本。 用旧版本模型、且流程里依赖「先读后写」作为正确性校验的流程不受影响。用更新模型、且依赖「读前写不能执行」作为隐式安全门的流程，这道门对 Write tool 已经取消了。显式的预写断言，或者在 orchestration 层加读取校验步骤，仍然是正确的做法。

TheRouter 用户可以做什么

检查你的 Claude Code 部署是否有 marketplace 条目在多个 settings tier 里都有定义并带了 custom-headers。团队级 workspace 配置加上开发者个人 settings 的组合最容易触发这个场景。2.1.228 修复了后续行为，但不会自动修复历史 session 的状态，需要手动审计。

对于跑 Vertex AI 的路由路径，升级到 2.1.228 后可以用故意失效的凭据测一次 p99 错误延迟，确认新行为确实把失败时间压到了 15 秒以内。有了这个数据，才有依据调整 Vertex provider 的超时配置。

更多 Claude Code operator 部署的背景，参见 TheRouter 新闻 中此前的相关报道。