Claude Code fallback model：如何避免 API 路由里的双重故障转移

今日 Claude Code 版本中，真正值得运维团队关注的不是那些 CLI 易用性改进，而是三处将 coding agent 可靠性与企业管控能力向 API 基础设施层下沉的变化：--fallback-model 自动切换、pluginSuggestionMarketplaces 企业治理，以及 skill frontmatter 中的 disallowed-tools。加上新增的 OpenTelemetry app.entrypoint 属性，这一版本让 Claude Code 在部署层面变得更可观测、更可管控。

发生了什么

官方 anthropics/claude-code GitHub 仓库发布于北京时间 5 月 27 日 09:30，包含以下对 operator 有实质影响的更新：

--fallback-model 在 model-not-found 错误时自动激活。 此前，若会话主模型返回找不到模型的错误，该会话在剩余时间内的每次请求都会失败。此版本起，只要主模型不可用，Claude Code 会立即将 --fallback-model 切换为本次会话的执行模型，无需手动干预，也不需要重启会话。切换是会话级别持久的：一旦触发，本次会话保持使用 fallback 模型。

pluginSuggestionMarketplaces 企业管理设置。 新增 managed policy，允许管理员将特定组织插件市场加入白名单，只有白名单内的市场插件才会通过上下文感知提示出现在开发者面前。没有此设置时，Claude Code 可能将任意可用市场的插件推荐给开发者；有了它，IT 与安全团队能在插件建议层面实现准入管控，而不仅是安装层面。

Skill 和 slash-command frontmatter 中的 disallowed-tools。 Skill（Claude Code 的按需知识模块）现在可以在 frontmatter 中声明一组工具黑名单，模型在该 skill 激活期间不得使用这些工具。这是工具级别的隔离机制：一个仅用于只读文档检索的 skill 可以阻止 Claude 执行 shell 命令或写入文件，无论会话的主权限策略如何配置。

OTEL app.entrypoint 指标属性。 通过 OTEL_METRICS_INCLUDE_ENTRYPOINT=true 选项开启，将 session 的入口方式（CLI、SDK、remote 等）作为 OpenTelemetry 指标属性输出。将 OTEL 数据导出至 Datadog、Grafana 等后端的团队，现在可以按调用方式切分模型使用量和 token 花费——例如区分终端交互会话与 CI 流水线调用，或远程 agent 下发任务。

本次版本其他值得记录的更新：

• SessionStart hook 现可在启动和恢复时设置会话标题，并可触发 skill 目录重扫，无需重启。
• MessageDisplay hook：hook 现可在输出层面对模型回复进行变换或隐藏——支持输出过滤、脱敏或标注。
• /code-review --fix 可将审查结果直接写入工作区；/simplify 现调用它。
• Auto mode 不再需要手动 opt-in。
• 修复：cache_creation_input_tokens 在 transcript 和 result usage 中错误报为 0 的问题，现已从 API 的嵌套 cache 明细中正确读取。

对 AI 工程团队意味着什么

--fallback-model 改变了会话失败的契约。 此前，模型可用性问题意味着会话基本报废，开发者必须察觉、停止、重启，可能丢失已累积的上下文。新行为使 Claude Code 能在无感知的情况下切换到 fallback 模型恢复会话，无需中断工作流。这个模式此前是 API routing gateway 在基础设施层提供的能力，现在已内置到客户端本身。

这里有一个重要的部署层面含义：依赖 routing gateway 做自动故障切换的团队需要意识到，Claude Code 现在具备了自己的第一跳 fallback 逻辑。在 gateway 层触发的失败会走 gateway 的 fallback 策略；在到达 gateway 之前就已失败的请求（如模型 ID 错误、客户端配置层的 quota 超限），现在可能会触发 Claude Code 自己的 fallback。清楚 fallback 在哪个层触发，对可靠性归因和避免双重 fallback 场景至关重要。

pluginSuggestionMarketplaces 填补了真实的企业治理空白。 随着 Claude Code 在组织内规模化落地，未经审批的第三方插件在开发者会话中被推荐的风险也随之上升。开发者在活跃的编码会话中收到安装未审核市场插件的建议，是一个影子 IT 风险。新的 managed setting 让安全团队和平台团队在插件建议层面拥有白名单管控，而不是等到开发者已经安装之后再追溯。

disallowed-tools 实现了 skill 级别的最小权限设计。 一个没有写入权限的 skill 不会破坏文件；一个不能执行 shell 命令的 skill 不会触发非预期的副作用。这对构建内部 skill 库的团队是显著升级——skill 作者现在可以将每个 skill 的预期操作范围编码为安全属性，而不是依赖文档说明。

OTEL app.entrypoint 弥补了多入口部署的可见性缺口。 在多种模式下运行 Claude Code 的团队——桌面终端、CI 流水线、云端远程下发、SDK 托管——此前没有办法在 OTEL 指标中按调用方式分类。这个属性使"CI 流水线 vs 交互式会话各占 token 花费的多少"这类问题变得可以回答，对成本分配和容量规划都有直接价值。

Router/Operator 视角

客户端 fallback 与 gateway 层 fallback 现在共存，需要明确边界。 Claude Code 的 --fallback-model 在客户端生效：若配置的模型找不到，会话在本地切换。API gateway 的 fallback 在基础设施层生效：若 provider 返回特定错误码或超过延迟阈值，gateway 将请求路由到备用 provider 或模型。

二者可以共存，但需要配置为互补关系，而非重复触发同一故障点。实践建议：客户端 fallback 处理 model-not-found 类错误（模型 ID 错误、访问被拒）；gateway 层 fallback 处理 provider 错误（5xx、rate limit、超时）。将这个边界明确写入内部运维文档，避免同一次故障事件在两层都触发、导致可靠性数据难以归因。

Session 可观测性新增了 entrypoint 维度。 如果你的团队将 Claude Code 的 OTEL 数据导出到中央可观测性后端，app.entrypoint 属性支持按调用来源分类：CI 流水线花费 vs. 开发者交互花费 vs. 远程 agent 花费。对于管理跨多个 Claude Code 使用场景的共享 API 预算的团队，建议尽早开启 OTEL_METRICS_INCLUDE_ENTRYPOINT=true，并将 entrypoint 加入花费仪表板的分组维度。

disallowed-tools 作为 skill 层的策略原语。 构建大规模 Claude Code 内部 skill 目录的团队，现在可以将 disallowed-tools 作为一等策略机制使用。只读文档检索 skill 可以在 frontmatter 中声明 disallowed-tools: [Bash, Edit, Write]，无论会话的主权限策略如何，该 skill 激活期间模型都无法执行命令或写入文件。这与现有 managed-settings.json 策略可叠加——skill 层限制是附加的，不替代会话级别的管控。

MessageDisplay hook 支持输出层治理。 需要从 Claude Code 输出中脱敏敏感信息（IP 地址、凭证、PII 模式）的团队，现在可以通过 MessageDisplay hook 在展示层完成，而无需修改模型的响应。对于在敏感代码库上使用 Claude Code 且 IT 要求某些模式不出现在开发者可见输出或会话记录中的企业，这个 hook 提供了一个干净的实施层。

TheRouter 用户需要关注或尝试的事项

• 检查 fallback 模型配置，避免双重 fallback 场景。 如果你在使用 Claude Code 的 --fallback-model 设置，同时 routing 层也有覆盖相同模型的 fallback 策略，请梳理每一层处理的具体失败模式。目标是互补覆盖，而不是让两层对同一次失败都触发。

• 如果在多种模式下运行 Claude Code，立即开启 OTEL_METRICS_INCLUDE_ENTRYPOINT=true。 这个属性不产生额外开销，但事后很难补充。在将 Claude Code 扩展至 CI 流水线或远程 agent 下发之前就加上，当按调用模式分摊成本的需求出现时，数据已经就位。

• 审查内部 skill 库，找出可以添加 disallowed-tools 的候选。 任何设计为只读任务的 skill——文档检索、设计审查、代码解释——都适合添加显式的 disallowed-tools 声明。将预期操作范围编码为安全属性，比依赖文档说明更能减少 skill 在非预期上下文中被调用时的影响范围。

• 企业部署前先测试 pluginSuggestionMarketplaces。 该功能控制哪些市场的插件可以出现在开发者的建议中。如果你的组织有内部插件市场，将其加入白名单并验证建议行为，然后再向会主动安装插件的团队大规模推出。

TheRouter 路由 OpenAI-compatible 请求并记录每个会话的 token 用量。针对 Claude Code 工作流，--fallback-model 变更使客户端自身的 fallback 逻辑更加可见——使用 TheRouter 配合 Claude Code 的团队应确认 gateway 层 fallback 策略与 Claude Code 的 --fallback-model 设置覆盖的是不同的故障面，而不是同一个。通过 OTEL 导出 session ID 和 entrypoint 维度的指标，是跨全栈获取完整 session 级花费可见性最可靠的方法。