凭据、协议与配置优先级

配置 modelProviders、认证类型和默认模型，理解环境变量及 .env 加载规则。

This page has not been translated into English yet. The original Chinese version is shown below.

自定义模型需要把模型 ID、API 协议、端点与凭据来源配对。官方建议在用户级 ~/.qwen/settings.json 定义 modelProviders，减少项目与用户配置的合并冲突。

基础配置

以下示例使用标准 DashScope 的 OpenAI 兼容端点，通过环境读取 Key：

{
  "modelProviders": {
    "openai": [
      {
        "id": "qwen3-coder-plus",
        "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",
        "envKey": "DASHSCOPE_API_KEY"
      }
    ]
  },
  "security": {
    "auth": { "selectedType": "openai" }
  },
  "model": { "name": "qwen3-coder-plus" }
}

模型名是官方文档示例，使用前确认账号可用。运行环境提供 DASHSCOPE_API_KEY；与之不同，Coding Plan 和 Token Plan 必须使用自己的专用地址。

模型条目

字段	要求与含义
`id`	必填，发送给 API 的模型 ID
`name`	选择器显示名称，默认与 id 相同
`envKey`	Key 所在环境变量名；省略时使用协议的默认 Key 变量
`baseUrl`	API 地址覆盖，用于代理、自定义服务等
`wireApi`	OpenAI 兼容请求格式，`chat-completions` 或 `responses`；省略时继承提供商协议
`generationConfig`	超时、重试、采样等高级生成设置，具体字段见生成配置

security.auth.selectedType 决定启动认证协议，model.name 应匹配模型条目 id。只添加 modelProviders 而不配置启动选择或凭据，不能保证非交互任务直接可用。

凭据来源优先级

优先级	来源
1	CLI 显式参数，例如 `--openai-api-key`
2	进程环境，例如 shell export 或启动时内联变量
3	自动找到的 `.env`
4	`settings.json` 的 `env` 对象

上表是 Authentication 页的凭据概括；选中 modelProviders 条目后的字段解析还受 provider 层影响，不能直接推断任意 CLI Key 都覆盖已选条目，见模型解析。环境变量加载中，启动时低优先级来源补充未设置或空字符串变量，不覆盖进程中已有非空值。官方支持在 settings 的 env 写 Key，但它以明文保存；避免提交包含凭据的文件。

.env 查找

当前实现从工作目录向上找到第一份允许的项目文件，每级优先 .qwen/.env，其次 .env，随后仍追加用户文件。顺序是全局 Qwen 目录的 .env、QWEN_HOME 重定向时的旧 ~/.qwen/.env、最后 ~/.env；重复路径去重。

Authentication 页“只读首个文件”的旧描述不再完整。当前源码会按上述顺序补齐未设置或空字符串值，不累积多个祖先项目文件。普通项目 .env 默认排除 DEBUG、DEBUG_MODE，而所有层还受强制变量限制，见环境加载。

官方推荐 .qwen/.env 隔离 Qwen Code 的变量，并将其排除在 Git 之外。若改文件后仍读取旧 Key，先检查更高优先级的 shell 环境及实际找到的文件，不要盲目复制更多配置。

切换与诊断

/model 按协议展示配置模型，选择会保存到后续会话；启动参数 qwen --model "模型ID" 可用于不同终端选择模型。/doctor 检查当前配置，输出含敏感信息时不应直接公开。

旧 qwen auth 子命令已经移除，配置迁移见认证入口。