它到底是什么

--fallback-model 是 CLI 启动 flag。官方文档的定义是：当主模型过载（overloaded）或不可用（例如模型已退役）时，自动回退到指定的模型。

• 接受的值：逗号分隔的模型列表，按顺序依次尝试。每一项可以是模型名或别名，"default" 会展开为默认模型。
• 默认值：官方文档没有写默认值。文档也说明 Claude Code 启动时不会确认回退链，/status 也不显示它。

触发条件：

用法

# 单个回退模型(官方示例)
claude -p --fallback-model sonnet "query"

# 多级回退链,按顺序尝试
claude --fallback-model sonnet,haiku

# 与 --model 组合
claude --model opus --fallback-model sonnet,haiku

官方文档说明，持久化配置请使用 fallbackModel setting,--fallback-model 会覆盖该 setting。

与其他 flag 的组合 / 互斥

• --model:--model 指定主模型，--fallback-model 指定备用模型。官方文档没有说明二者互斥。
• -p / --print：官方示例用于 -p。当前 CLI 文档没有把它列为 print mode only，而 --max-turns、--max-budget-usd 等 flag 则明确标注了"print mode only"。
• --safe-mode：官方文档提到，--safe-mode 可用来检查是不是某项自定义配置触发了自动模型回退。该章节我没有读到，具体机制不展开。

在 settings.json / env 的等价配置

{
  "fallbackModel": ["claude-sonnet-5", "claude-haiku-4-5"]
}

运行约束 / 限制

经典使用场景

• headless / CI：官方示例 claude -p --fallback-model sonnet "query"，主模型过载时脚本仍能完成请求。
• 主模型被退役：文档明确把"模型不可用（例如已退役的模型）"列为触发条件。
• 长期固定配置：用 fallbackModel setting 写入配置文件，临时需要不同链时再用 flag 覆盖。

常见坑

• 配额类错误不会回退：rate-limit、billing、authentication 错误不会触发切换。想靠它绕过限流是行不通的。
• 回退是 per-turn 的：切换只持续当前 turn，下一条消息会重新先试主模型，不会一直停留在备用模型上。
• 没有启动时确认：/status 不显示回退链，首次看到切换提示时才能确认它已生效。
• 超过 3 个的条目会被静默忽略。
• availableModels 限制会过滤回退链：不在 allowlist 里的条目会被丢弃，链可能比你写的更短。

来源

• CLI reference - Claude Code Docs（docs.claude.com/en/docs/claude-code/cli-reference 经 301 跳转至此）
• Model configuration - Claude Code Docs