自定义模型 - Qoder

除了 Qoder CLI 内置提供的标准模型外，你还可以通过 BYOK（Bring Your Own Key，自带密钥）接入自己的第三方模型：用你自己的 API 密钥调用某个提供商的模型，并在 Qoder CLI 中像使用标准模型一样使用它。本页介绍标准模型、如何配置 BYOK 自定义模型、如何按任务选择模型，以及相关的模型别名机制。基础的模型切换见选择模型与推理强度。

标准模型

Qoder CLI 内置一组标准模型，通过统一的标识名选择，无需配置密钥：

标识	说明
`auto`	智能选择最优模型，在性能与成本间平衡。
`ultimate`	专家级深度推理与思考，输出质量最高。
`performance`	高级推理，输出质量高。
`efficient`	标准推理，成本较低。
`lite`	基础推理，可在免费额度下使用（高峰期可能较慢），不支持图片输入。

在交互界面中运行 /model 即可切换标准模型；也可以在启动时用 -m/--model 指定。

配置自定义模型（BYOK）

BYOK 让你用自己的密钥接入第三方模型。自定义模型在配置文件的 modelConfigs.customModels 数组中声明，每个条目描述一个模型。

配置示例

在 settings.json 中添加：

{
  "modelConfigs": {
    "customModels": [
      {
        "provider": "openai",
        "apiKey": "sk-...",
        "model": "gpt-4o",
        "baseURL": "https://api.openai.com/v1",
        "key": "my-gpt4o",
        "displayName": "My GPT-4o",
        "format": "openai",
        "isReasoning": false,
        "isVl": false,
        "maxInputTokens": 128000
      }
    ]
  }
}

修改 customModels 后需要重启 Qoder CLI 才能生效。

字段说明

字段	必填	默认值	说明
`provider`	是	—	提供商标识，例如 `openai`、`deepseek`。
`apiKey`	是	—	该提供商的 API 密钥。
`model`	是	—	提供商侧的裸模型 ID，例如 `gpt-4o`。
`type`	否	—	提供商的模型类型键，匹配提供商配置中的类型。
`baseURL`	否	—	提供商的推理请求基础 URL，例如 `https://api.openai.com/v1`。
`key`	否	`<provider>/<model>`	用于 `-m` 选择该模型的标识符。
`displayName`	否	同 `key`	人类可读的显示名称。
`format`	否	`openai`	API 格式/风格，允许值：`openai` 或 `anthropic`。
`isReasoning`	否	`false`	是否为推理模型。
`isVl`	否	`false`	是否接受图片输入（视觉语言模型）。
`maxInputTokens`	否	`128000`	最大输入 token 数。

选择自定义模型

配置并重启后，自定义模型会被并入模型目录，可以通过 key 选择：

qodercli -m my-gpt4o

也可以在交互界面中用 /model 选择。

密钥安全

apiKey 会以明文形式保存在配置文件中，请注意存放位置：

不要把含密钥的配置写进项目级 settings.json（<项目>/.qoder/settings.json），因为它会随版本库提交，导致密钥泄露。
优先把 BYOK 配置放在用户级 ~/.qoder/settings.json，或项目内不提交版本库的本地级 settings.local.json。
如需在团队间共享结构而不泄露密钥，可结合环境变量引用，把真实密钥放到环境变量中。

如果启用了环境变量脱敏（security.environmentVariableRedaction.enabled），可进一步降低密钥在工具执行时被暴露的风险，见配置文件与生效顺序。

模型别名与作用范围

Qoder CLI 内部通过“模型别名”把不同任务映射到不同的模型档位。别名是一组命名的模型配置预设，可以通过 extends 继承其他别名，也可以在 modelConfigs.aliases / modelConfigs.customAliases 中扩展或覆盖。这套机制让不同用途的内部任务（例如标题生成、上下文压缩、快速补全等）使用更轻量或更合适的模型档位，从而在保证质量的同时控制成本。大多数用户无需改动别名；如需精细控制，可参考以下要点：

modelConfigs.aliases：内置的命名预设，可在需要模型名的位置使用，并支持 extends 继承。
modelConfigs.customAliases：自定义预设，与内置别名合并并覆盖同名项。
modelConfigs.overrides / customOverrides：基于匹配条件（主键为模型或别名）应用配置覆盖，最具体的匹配优先生效。

模型参数

别名的模型配置中可以调整生成参数，常见的有：

temperature、topP：采样相关参数。
maxOutputTokens：单次输出的最大 token 数。
thinkingConfig.thinkingBudget：推理预算。

下一步

基础模型切换：选择模型与推理强度。
配置文件与生效顺序：配置文件与生效顺序。
完整配置项与环境变量：配置项、环境变量与文件路径。

​标准模型

​配置自定义模型（BYOK）

​配置示例

​字段说明

​选择自定义模型

​密钥安全

​模型别名与作用范围

​模型参数

​下一步