Gemini CLI 模型选择机制详解：`/model` 命令、`--model` 参数与 Auto 智能路由原理

本文围绕 gemini-cli 的模型选择体系展开：从交互式的 /model 命令和启动时的 --model 参数入手，结合仓库源码深入解析 Auto 模式下“分类器路由”是如何为每个任务自动挑选 Pro 或 Flash 模型的。读完后你可以：熟练地在会话中切换模型并理解各选项的实际含义、在启动时通过别名或具体模型名锁定行为、并弄清 Auto 模式背后的复杂度分类与策略链实现，从而在“速度”与“推理质量”之间做出有依据的取舍。

/model 命令的使用方式

在 gemini-cli 交互界面中输入以下命令即可打开模型选择对话框：

/model

该命令会弹出一个对话框，提供以下选项（对应文档 docs/cli/model.md 中的选项表）：

选项	说明	对应模型
Auto (Gemini 3)	让系统为你的任务自动选择最佳的 Gemini 3 模型	gemini-3-pro-preview、gemini-3-flash-preview
Auto (Gemini 2.5)	让系统为你的任务自动选择最佳的 Gemini 2.5 模型	gemini-2.5-pro、gemini-2.5-flash
Manual	手动选择一个具体模型	任意可用模型

官方推荐使用 Auto 选项；如果你确实需要锁定某个具体模型，可以选择 Manual 从可用模型中挑选。

从源码结构看，这个对话框由 ModelDialog 组件 实现，其行为有几个值得注意的细节：

• 对话框打开时会读取 config.getModel() 作为当前“偏好模型”（默认回退到 auto 别名），并用 ModelQuotaDisplay 展示配额信息；
• 对话框内按 Tab 键可切换“持久化”模式（persistMode），决定本次选择是写入配置还是仅对当前会话生效；按 Escape 从 Manual 视图退回主视图或关闭对话框；
• 如果账号没有 Pro 模型的访问权限（getProModelNoAccess），对话框会自动直接定位到 Manual 视图，并隐藏不可用的预览模型（shouldShowPreviewModels 由 getHasAccessToPreviewModel() 决定）。

需要特别说明的一个边界情况（文档中也有 NOTE 提示）：/model 命令（以及 --model 参数）不会覆盖子代理（sub-agent）使用的模型。因此在模型用量报告中，你可能看到与主会话不同的模型被使用——这是预期行为，因为子代理有自己的模型配置。

--model 启动参数与模型别名

除了交互式切换，你还可以在启动 gemini-cli 时通过 --model（简写 -m）参数指定模型，默认值为 auto。根据 CLI 参考文档 的参数表：

Option	Alias	Type	Default	Description
--model	-m	string	auto	指定使用的模型，可用别名或具体模型名

模型支持“别名”机制，即用户友好的快捷名称会解析为具体模型。别名的定义与解析逻辑位于 models.ts：

// Model aliases for user convenience.
export const GEMINI_MODEL_ALIAS_AUTO = 'auto';
export const GEMINI_MODEL_ALIAS_PRO = 'pro';
export const GEMINI_MODEL_ALIAS_FLASH = 'flash';
export const GEMINI_MODEL_ALIAS_FLASH_LITE = 'flash-lite';

CLI 参考文档中给出的别名映射表如下：

别名	解析结果	说明
auto	gemini-2.5-pro 或 gemini-3-pro-preview	默认值；若启用 preview 特性则解析为预览模型
pro	gemini-2.5-pro 或 gemini-3-pro-preview	面向复杂推理任务
flash	gemini-2.5-flash	快速、均衡
flash-lite	gemini-2.5-flash-lite	最快速的简单任务模型

从源码看，resolveModel() 函数实现了这套别名到具体模型 ID 的映射，并处理两类降级场景：

• 无 preview 权限时降级：如果用户没有预览模型的访问权限，auto/pro 会解析到 gemini-2.5-pro，flash 解析到 gemini-2.5-flash，而不是 -preview 后缀的模型；
• 实验性动态模型配置：当 getExperimentalDynamicModelConfiguration() 为 true 时，解析会委托给 ModelConfigService.resolveModelId()，由服务端的模型定义（含 tier、family、features 等字段）驱动，为后续新模型上线预留了扩展点。

仓库中实际维护的合法模型集合 VALID_GEMINI_MODELS 除了 Gemini 系列外，还包含 Gemma 本地模型（如 gemma-4-31b-it、gemma-4-26b-a4b-it），这些主要用于本地路由实验场景。

无论通过对话框还是启动参数修改，这些设置都会应用于后续与 gemini-cli 的所有交互。

Auto 模式的底层实现：分类器路由策略链

Auto 选项之所以能“自动选择最佳模型”，背后是一条模型路由（Model Routing）策略链。核心服务是 ModelRouterService，它在构造时按固定顺序组装出一组策略：

// Order matters here. Fallback and override are checked first.
strategies.push(new FallbackStrategy());
strategies.push(new OverrideStrategy());

// Approval mode is next.
strategies.push(new ApprovalModeStrategy());

// Then, if enabled, the Gemma classifier is used.
if (this.config.getGemmaModelRouterSettings()?.enabled) {
  strategies.push(new GemmaClassifierStrategy());
}

// The generic classifier is next.
strategies.push(new ClassifierStrategy());
strategies.push(new NumericalClassifierStrategy());

// The default strategy is the terminal strategy.
const terminalStrategy = new DefaultStrategy();

也就是说，每一个请求到达路由器时，会依次经过：FallbackStrategy（回退保护）→ OverrideStrategy（用户强制指定）→ ApprovalModeStrategy（审批模式适配）→ 可选的 GemmaClassifierStrategy（本地 Gemma 分类器）→ ClassifierStrategy（云端 LLM 分类器）→ NumericalClassifierStrategy → 最终的 DefaultStrategy（终端策略，保证一定给出决策）。所有策略通过 CompositeStrategy 组合，任一中间策略返回 null 就交由下一个策略处理。

ClassifierStrategy：复杂度分类的判定标准

云端分类器 ClassifierStrategy 是 Auto 模式的核心。它会用一次额外的轻量 LLM 调用（模型配置键为 classifier）来分析用户请求，并按内置的“复杂度评分标准”输出 JSON 决策，只允许在 flash（SIMPLE）和 pro（COMPLEX）之间二选一。其系统提示词中的判定标准（complexity rubric）摘要如下：

• 判为 COMPLEX（选 pro） 的情形（满足其一即可）：
  1. 高操作复杂度（预估 4 步以上/4 次以上工具调用），需要依赖动作、规划或多个协调修改；
  2. 需要战略规划与概念设计——用户在问“怎么做”或“为什么”，需要建议、架构或高层策略；
  3. 高模糊度或大范围请求，需要大量调查；
  4. 深度调试与根因分析——从症状诊断未知或复杂问题。
• 判为 SIMPLE（选 flash） 的情形：任务高度具体、边界清晰、操作复杂度低（预估 1-3 次工具调用），且“操作上的简单性优先于策略性措辞”。

提示词中还给了 6 个判定示例，例如“列出当前目录文件”→ flash（单步工具调用）；“为 User schema 新增 email 字段、迁移数据库并更新注册接口”→ pro（跨文件多步协调）；“重命名变量 data 为 userData 的最佳方式是什么”→ flash（虽然用了“最佳方式”的策略性措辞，但本质是局部编辑）。

几个实现细节值得注意：

• 历史上下文裁剪：分类器只会取最近 20 轮历史中过滤掉 function call/response 后的最后 4 轮（HISTORY_TURNS_FOR_CONTEXT = 4），把上下文成本控制在很低水平；
• 函数响应直接绕过：如果本次请求本身是一个 FunctionResponse（工具执行结果回传），分类器会被跳过，避免构造出不合法的分类请求；
• 可用性校验：分类器选出的模型会再经过 ModelAvailabilityService.snapshot() 检查，若该模型当前不可用则放弃本次路由决策（返回 null），由后续策略接管；
• 失败即让位：分类器遇到任何异常（API 错误、JSON 解析失败等）都会记录日志并返回 null，不会阻塞主流程；
• 决策留痕：ModelRouterService.route() 在每次路由后都会发出 ModelRoutingEvent 遥测事件，包含选中模型、策略来源、延迟、判定理由（reasoning）、审批模式、数值路由开关与分类阈值等信息——这也是你在用量报告中看到“其他模型”的数据来源。

分类结果如何落成具体模型

分类器输出的 flash/pro 只是抽象档位，最终落到哪个模型 ID 由 resolveClassifierModel() 决定。它会把档位与当前请求的模型族结合：例如请求处于 Gemini 3 Auto 档位时选 flash，就会解析为 gemini-3-flash-preview（有 3.5 Flash GA 权限时则为对应的 GA 模型）；请求处于 Gemini 2.5 Auto 档位时选 flash，则解析为 gemini-2.5-flash。这解释了文档选项中为什么每个 Auto 档位都对应“一个 Pro 模型 + 一个 Flash 模型”的组合：路由器只在同一代际内做 Pro/Flash 的取舍，不会跨代切换。

模型选择最佳实践

原文档给出的三条建议（docs/cli/model.md），结合上面的机制可以更完整地理解其适用场景：

• 默认使用 Auto。 对大多数用户，Auto 在速度与效果之间取得平衡：它会按任务复杂度自动选择正确模型。例如开发一个 Web 应用，可能混合了复杂任务（搭建架构、脚手架）和简单任务（生成 CSS），Auto 会在 Pro 与 Flash 之间动态切换。
• 结果不理想时切换到 Pro。 如果你希望模型“更聪明”，可手动选择 Pro。它提供最高水平的推理与创造力。典型场景：复杂的、多阶段的调试任务——这类任务正是分类器 rubric 中“深度调试与根因分析”判为 COMPLEX 的类别。
• 需要快速响应时切换到 Flash 或 Flash-Lite。 如果只需要快速得到一个简单回答，Flash/Flash-Lite 是最佳选择。典型场景：把一个 JSON 对象转成 YAML 字符串——这类边界清晰的转换任务在 rubric 中属于“1-3 次工具调用”的 SIMPLE 范畴。

小结与进一步阅读

gemini-cli 的模型选择体系可以概括为三层：

1. 交互层：/model 对话框提供 Auto (Gemini 3)、Auto (Gemini 2.5)、Manual 三种选择，支持持久化或临时生效；
2. 参数层：启动时 --model/-m 参数接受别名（auto/pro/flash/flash-lite）或具体模型名，默认 auto；
3. 路由层：Auto 模式下由 ModelRouterService 驱动的策略链执行，其中 ClassifierStrategy 按复杂度评分标准调用分类模型，在 Pro/Flash 之间做出逐请求的动态决策，并通过遥测事件记录全过程。

如需继续深入，可参考以下仓库路径：

• 模型别名与解析实现：packages/core/src/config/models.ts
• 路由服务与策略组装：packages/core/src/routing/modelRouterService.ts
• 策略接口定义（RoutingDecision/RoutingContext）：packages/core/src/routing/routingStrategy.ts
• 云端分类器策略：packages/core/src/routing/strategies/classifierStrategy.ts
• 模型对话框 UI：packages/cli/src/ui/components/ModelDialog.tsx
• 全部 CLI 参数与别名映射：docs/cli/cli-reference.md
• 完整配置项说明：docs/reference/configuration.md

注意：文中涉及的模型名称、预览权限与实验性开关（如 Gemini 3.1、3.5 Flash GA 灰度）以当前仓库版本的实际代码为准，不同发布版本中 --model 可解析的具体模型集合可能随模型迭代而变化。