Gemini CLI 的高级模型配置（modelConfigs）让你精细控制每次请求的 temperature、topP、thinkingBudget 等参数。通过 customAliases 创建可复用的配置预设，通过 overrides 按 Agent 场景动态注入参数，实现测试环境精确控制、生产环境创意输出的分离配置。

高级模型配置（generation-settings）

⚠️ 高级功能警告：配置值会直接传递给模型 API，仅做最小校验。错误的参数组合可能导致 API 运行时报错。建议在测试环境先验证。

系统概览

modelConfigs 配置系统（ModelConfigService）提供对模型生成行为的精细控制：

• 精确超参调优：直接控制 temperature、topP、thinkingBudget 等 SDK 级参数
• 环境特定行为：为测试和生产环境配置不同的参数
• Agent 级定制：只在特定 Agent 活跃时应用特定配置

系统基于两个核心概念：别名（Aliases） 和 覆盖规则（Overrides）。

配置位置

所有设置位于 settings.json 中的 modelConfigs 键下。

别名（customAliases）

别名是可命名、可复用的配置预设：

• 继承：别名可以用 extends 继承其他别名（包括系统默认别名如 chat-base），子别名覆盖父别名的配置
• 抽象别名：不指定具体 model 的别名可作为其他别名的基类

{
  "modelConfigs": {
    "customAliases": {
      "base": {
        "modelConfig": {
          "generateContentConfig": { "temperature": 0.0 }
        }
      },
      "chat-base": {
        "extends": "base",
        "modelConfig": {
          "generateContentConfig": { "temperature": 0.7 }
        }
      }
    }
  }
}

覆盖规则（overrides）

覆盖规则是基于运行时上下文动态注入配置的条件规则：

• 匹配条件：
  • model：匹配请求的模型名称或别名
  • overrideScope：匹配请求的 Agent 名称（如 codebaseInvestigator）

{
  "modelConfigs": {
    "overrides": [
      {
        "match": {
          "overrideScope": "codebaseInvestigator"
        },
        "modelConfig": {
          "generateContentConfig": { "temperature": 0.1 }
        }
      }
    ]
  }
}

主要参数说明

参数	类型	说明
model	string	模型 ID，如 gemini-2.5-pro
temperature	number	输出随机性。0.0 最确定，>0.7 最有创意
topP	number	核采样概率
maxOutputTokens	number	响应长度上限
thinkingConfig.thinkingBudget	number	思考推理 Token 预算（仅支持推理模型）
thinkingConfig.includeThoughts	boolean	是否在响应中包含推理过程

实用示例

确定性基线配置

创建零温度别名，适合需要高精度的任务：

{
  "modelConfigs": {
    "customAliases": {
      "precise-mode": {
        "extends": "chat-base",
        "modelConfig": {
          "generateContentConfig": {
            "temperature": 0.0,
            "topP": 1.0
          }
        }
      }
    }
  }
}

特定 Agent 注入思考预算

只为 codebaseInvestigator Agent 启用扩展思考，不影响全局默认值：

{
  "modelConfigs": {
    "overrides": [
      {
        "match": {
          "overrideScope": "codebaseInvestigator"
        },
        "modelConfig": {
          "generateContentConfig": {
            "thinkingConfig": { "thinkingBudget": 4096 }
          }
        }
      }
    ]
  }
}

A/B 测试：将特定别名路由到预览模型

{
  "modelConfigs": {
    "overrides": [
      {
        "match": {
          "model": "gemini-2.5-pro"
        },
        "modelConfig": {
          "model": "gemini-2.5-pro-experimental-001"
        }
      }
    ]
  }
}

常见问题

Q: temperature 设为多少合适？

A: 代码生成和需要精确答案的任务建议 0.0~0.2（确定性强）；创意写作和头脑风暴建议 0.7~1.0（创造力强）。日常对话用默认值 0.7 即可。

Q: overrides 中多个规则同时匹配怎么处理？

A: 按匹配条件的特异性排序（匹配的字段越多优先级越高）。特异性相同时，配置数组中靠后的规则优先（后者覆盖前者）。

Q: 这些配置影响子代理吗？

A: overrideScope 指定的就是 Agent 名称，可以精确控制特定子代理的行为。未指定 overrideScope 的全局覆盖规则会影响所有请求。