Gemini CLI 内置模型路由机制：当主模型因配额或服务错误失败时，CLI 会询问是否切换到备用模型。模型选择优先级从高到低：--model 命令行标志 → GEMINI_MODEL 环境变量 → settings.json 的 model.name → 本地 Gemma 路由（实验性）→ 默认 auto。实用工具调用（如提示补全）有静默降级链，不影响主对话模型。

模型路由与故障转移

Gemini CLI 内置模型路由功能，在主模型不可用时自动处理降级，确保会话连续性。

自动故障转移

当前模型失败时（如配额耗尽或服务错误），CLI 会启动切换流程：

1. 检测失败：ModelAvailabilityService 监测到当前模型异常
2. 用户确认：（根据失败类型和模型策略）弹出对话框询问是否切换到备用模型
3. 切换模型：批准后，使用备用模型处理当前轮次或剩余会话

静默降级链：某些内部工具调用（如提示补全、分类判断）使用静默降级，不弹对话框、不修改配置模型：

gemini-2.5-flash-lite → gemini-2.5-flash → gemini-2.5-pro

模型选择优先级

当 Gemini CLI 决定使用哪个模型时，按以下优先级（从高到低）：

优先级	来源	示例
1	--model 命令行标志	gemini --model gemini-2.5-pro
2	GEMINI_MODEL 环境变量	export GEMINI_MODEL=gemini-2.5-flash
3	settings.json 的 model.name	{ "model": { "name": "gemini-2.5-pro" } }
4	本地 Gemma 路由（实验性，需配置）	见下文
5	默认模型	auto（自动选择 Pro 或 Flash）

实验性：本地 Gemma 模型路由

可以用本地运行的 Gemma 模型来做路由决策（替代托管模型），减少云端 API 调用成本。

前置条件：本地 Gemma 模型必须通过 Gemini API 兼容接口提供服务，可通过 HTTP 访问。

配置示例（在 settings.json 中）：

{
  "experimental": {
    "localModelRouter": {
      "enabled": true,
      "endpoint": "http://localhost:8080"
    }
  }
}

详见上游文档：Local Model Routing

临时切换模型

在运行中的会话里，用 /model 命令切换：

/model set gemini-2.5-pro          # 只对本次会话有效
/model set gemini-2.5-flash --persist  # 保存到 settings.json

常见问题

Q: 自动切换了备用模型后，下次启动还是用备用模型吗？

A: 取决于切换时的范围。如果只是"当前轮次"的切换，下一轮还是用原模型；如果是"剩余会话"的切换，本次会话内都用备用模型，但不会修改 settings.json，下次启动恢复配置的模型。

Q: auto 模式会自动选择最好的模型吗？

A: auto 让 Gemini CLI 根据任务类型和当前配额情况自动在 Flash 和 Pro 之间路由，兼顾速度和质量。对于大多数用户这是最省心的选择。

Q: 如何固定用某个模型，不被自动切换？

A: 用 --model 标志启动 CLI，如 gemini --model gemini-2.5-pro，这是最高优先级，不会被自动路由覆盖。