模型路由
Gemini CLI model routing 的用途：自动 fallback、提升稳定性、处理模型不可用或预览模型变化。
模型路由解决的是“当前模型不合适或不可用时怎么办”。它让 Gemini CLI 在不同模型之间做更稳定的选择或回退。
Fallback 是可用性机制，不是质量保证。模型切换后仍要看 diff、测试和最终使用模型。
官方文档里的关键点是：Gemini CLI 默认启用模型路由，并由 ModelAvailabilityService 监控模型可用性。当主模型因为配额、服务端错误或模型不可用失败时，CLI 会进入 fallback 流程。
工作机制
模型路由不是简单地“随机换模型”，而是按策略处理失败：
- 当前模型请求失败。
- Gemini CLI 根据模型策略判断是否需要 fallback。
- 默认情况下，CLI 会提示用户是否切换到 fallback model。
- 用户同意后，fallback model 会用于当前 turn 或本 session 后续请求，具体取决于策略。
部分内部工具调用也可能使用静默 fallback chain，例如 prompt completion 和 classification。这类 fallback 不会改变你显式配置的主模型，所以排查时要区分“内部工具 fallback”和“当前对话主模型切换”。
适合场景
- preview 模型不稳定。
- 当前模型达到限制。
- 某些任务需要更强推理。
- 自动化任务需要减少中断。
模型选择优先级
实际使用哪个模型，按这个顺序决定：
- 启动参数
--model。 - 环境变量
GEMINI_MODEL。 settings.json里的model.name。- 实验性的本地 Gemma model router。
- 默认模型
auto。
这意味着你排查“为什么它没用我想要的模型”时，先看启动命令，再看环境变量，最后才看项目配置。
使用边界
模型路由不是让你忽略成本。团队环境要明确默认模型、回退模型、预算和日志。
不要把 fallback 当成质量保证。复杂代码改动仍然依赖清晰上下文、可执行验证和人工 review。模型切换只能提高可用性，不能替代工程验收。
Auto routing 也不是黑盒魔法。官方 Gemini 3 文档把任务分成简单和复杂两类：简单任务可能走 Flash，复杂任务在 Gemini 3 可用时优先 Pro，否则回落到 2.5 Pro。教程里要把这个逻辑写成“可能路由”，不要承诺某条 prompt 一定走某个模型。
| 现象 | 优先检查 |
|---|---|
| 自动换到低成本模型 | 当前任务复杂度、Auto routing、配额 |
| 频繁 fallback | 账号限制、地区、服务状态、模型预览状态 |
| Usage report 出现其他模型 | subagent、内部工具、fallback chain |
| 自动化结果不稳定 | 最终模型是否记录、prompt 是否固定 |
| 手动指定无效 | 启动参数、环境变量、settings 覆盖顺序 |
排查清单
- 用
gemini --version确认 CLI 版本。 - 检查启动命令里是否传了
--model。 - 检查 shell 里是否设置了
GEMINI_MODEL。 - 检查
settings.json是否配置model.name。 - 如果 fallback 频繁发生，优先确认配额、地区、账号类型和当前模型状态。
- 自动化场景要记录最终使用模型，避免不同任务结果不可追溯。
如果你显式传了 --model，但看到实际输出仍有其他模型，优先检查 subagent 和内部工具，而不是马上判断配置失效。主会话模型、subagent 模型和内部 fallback 是三条不同线。
记录模板
生产自动化里建议把每次任务的模型信息写进日志：
cli_version:
auth_type:
requested_model:
actual_models:
fallback_happened:
fallback_reason:
task_result:
verification:这个模板能帮助你区分质量问题和可用性问题。如果失败发生在 fallback 之后，后续复现必须使用同样的实际模型，而不是只看启动命令。
接下来去哪
本地模型路由
继续看本地 Gemma / local routing 的适用边界。
模型选择
回看 /model、--model、alias 和 subagent 模型边界。
Token caching
模型路由之外，还要看 token caching 和成本优化。