Gemini CLI 模型配置别名：为不同场景预设模型参数

在使用 Gemini CLI 时，不同的任务场景往往需要不同的模型配置组合：

创意写作希望更高的随机性，适合设置较高的 temperature
代码生成需要精确性，适合较低的 temperature 和确定性配置
需要深度思考的任务可以启用 thinking 模式并分配足够的 token 预算

Gemini CLI 的模型配置别名（Model Config Aliases）功能正是为了这个需求而设计的。

什么是模型配置别名

模型配置别名允许在配置文件中预定义多个模型配置方案，每个方案包含模型选择和完整的生成参数。通过为每个配置方案设置一个简短的别名，使用时只需指定别名即可快速切换到对应的配置。

Gemini CLI 提供了两类别名：

内置别名（Built-in Aliases）: 系统预定义的配置方案，如 base、chat-base、gemini-2.5-pro 等
自定义别名（Custom Aliases）: 用户在配置文件中自己定义的方案，可以继承内置别名或从头定义

自定义别名会与内置别名合并，当同名时会覆盖内置配置。

配置位置

自定义别名配置位于 settings.json 文件中，使用 modelConfigs.customAliases 字段：

全局配置：~/.gemini/settings.json
项目配置：<项目目录>/.gemini/settings.json

项目配置会覆盖全局配置。

配置语法

基础结构

{
  "modelConfigs": {
    "customAliases": {
      "别名名称": {
        "modelConfig": {
          "model": "gemini-2.5-pro",
          "generateContentConfig": {
            "temperature": 0.7,
            "topP": 0.95
          }
        }
      }
    }
  }
}

modelConfig 对象

必需字段：

model: 模型 ID，如 "gemini-2.5-pro"、"gemini-2.5-flash"、"gemini-3-pro-preview" 等

可选字段：

generateContentConfig: 生成配置对象
tools: 工具定义数组（如 googleSearch、urlContext）

generateContentConfig 支持的参数

根据官方 schema，以下是完整的支持参数列表：

参数	类型	说明	示例值
`temperature`	number	控制输出随机性，范围 0-2	0, 0.3, 1, 1.5
`topP`	number	核采样参数，范围 0-1	0.95, 1
`topK`	number	每步采样的候选词数量	64
`maxOutputTokens`	number	最大输出 token 数量	1024, 2000, 16000
`thinkingConfig`	object	思考模式配置对象	见下文
`tools`	array	工具定义	-

注意

schema 中没有定义 stopSequences、presencePenalty、frequencyPenalty 等参数，这些参数在 Gemini CLI 中不可用。

当前版本的settings.json

thinkingConfig 配置

思考模式的详细配置：

{
  "thinkingConfig": {
    "includeThoughts": true,
    "thinkingBudget": 8192,
    "thinkingLevel": "HIGH"
  }
}

参数说明：

includeThoughts (boolean): 是否启用思考模式
thinkingBudget (number): 分配给思考的 token 预算，如 512, 8192
thinkingLevel (string): 思考等级，如 "HIGH" 表示扩展思考

配置继承机制

使用 extends 字段可以从其他别名继承配置，这是一个强大的功能，可以避免重复定义：

{
  "modelConfigs": {
    "customAliases": {
      "my-creative": {
        "extends": "chat-base",
        "modelConfig": {
          "generateContentConfig": {
            "temperature": 1.5
          }
        }
      }
    }
  }
}

继承规则

子配置会与父配置合并
子配置中的字段会覆盖父配置的同名字段
可以继承内置别名或其他自定义别名
继承链可以多级延伸

在上面的例子中，my-creative 继承了内置别名 chat-base 的所有配置，只覆盖了 temperature 参数。

内置别名

Gemini CLI 提供了一些常用的内置别名，根据 schema 定义，主要包括：

基础配置：

base: 最小化配置，temperature 0，topP 1（完全确定性）
chat-base: 启用思考模式，temperature 1，topP 0.95，topK 64

扩展配置：

chat-base-2.5: 继承 chat-base，添加 8192 token 思考预算
chat-base-3: 继承 chat-base，设置思考等级为 HIGH

模型特定配置：

gemini-2.5-pro: 继承 chat-base-2.5 (启用思考模式)
gemini-2.5-flash: 继承 chat-base-2.5 (启用思考模式)
gemini-2.5-flash-lite: 继承 chat-base-2.5 (启用思考模式)
gemini-2.5-flash-base: 继承 base (无思考模式，纯文本生成)
gemini-3-pro-preview: 继承 chat-base-3 (高等级思考模式)

专用场景：

classifier: 分类任务配置，继承 base，maxOutputTokens 1024
prompt-completion: 提示补全配置，继承 base，maxOutputTokens 16000
summarizer-shell: Shell 命令摘要，继承 base
web-search: Web 搜索配置，启用 Google Search 工具

这些内置别名构成了一个继承链：

- base
  - chat-base
    - chat-base-2.5
      - gemini-2.5-pro
      - gemini-2.5-flash
      - gemini-2.5-flash-lite
    - chat-base-3
      - gemini-3-pro-preview
  - gemini-2.5-flash-base
    - web-search
    - web-fetch
    - web-fetch-fallback
    - loop-detection
    - llm-edit-fixer
    - next-speaker-checker
  - classifier
  - prompt-completion
  - edit-corrector
  - summarizer-default
  - summarizer-shell
- loop-detection-double-check (extends base)
- chat-compression-3-pro (不继承任何别名)
- chat-compression-2.5-pro (不继承任何别名)
- chat-compression-2.5-flash (不继承任何别名)
- chat-compression-2.5-flash-lite (不继承任何别名)
- chat-compression-default (不继承任何别名)

配置验证

配置文件遵循 JSON Schema 规范，可以参考官方 schema 验证配置的正确性：

Schema 位置：https://github.com/google-gemini/gemini-cli/blob/main/schemas/settings.schema.json

使用的参数都在 schema 定义范围内
参数类型和值范围正确
继承的别名存在（内置或已定义的自定义别名）

总结

模型配置别名是 Gemini CLI 提供的强大配置管理功能，可以预定义多个场景化的配置方案。

什么是模型配置别名

配置位置

配置语法

基础结构

modelConfig 对象

generateContentConfig 支持的参数

thinkingConfig 配置

配置继承机制

继承规则

内置别名

配置验证

总结

参考资料