模型提供商

Qwen Code 允许你通过 settings.json 中的 modelProviders 设置来配置多个模型提供商。这使你能够使用 /model 命令在不同的 AI 模型和提供商之间进行切换。

概述

使用 modelProviders 按 provider id 声明 /model 选择器可切换的模型。每个键是一个 provider id，其值是一个模型定义数组（ModelConfig[]）。对于内置 provider，键必须是有效的 auth type（openai、anthropic、gemini、vertex-ai）；自定义 provider id（例如 idealab）也是允许的，只要你通过顶层的 [providerProtocol](#自定义 provider-idproviderprotocol) 设置将其映射到某个协议。每个模型条目需要一个 id；envKey 是可选但推荐的（如果省略，将回退到该 auth type 的默认环境变量键，例如 openai 对应 OPENAI_API_KEY），此外还有可选的 name、description、baseUrl 和 generationConfig。凭据永远不会持久化在设置中；运行时会从 process.env[envKey] 读取它们。Qwen OAuth 模型保持硬编码，无法被覆盖。

图像生成路由

当某个路由可供内置 image_gen 工具使用时，请设置 supportsImageGeneration: true。此能力独立于 capabilities.vision 或 generationConfig.modalities.image 等图像输入支持。

当路由专用于图像生成且不应出现在普通模型选择器中时，请设置 imageOnly: true。为保持向后兼容，imageOnly: true 也会隐式启用图像生成能力，因此现有设置无需迁移。

双用途路由既可选作主模型，也可通过 /model --image 选择：

{
  "modelProviders": {
    "openai": [
      {
        "id": "omni-model",
        "envKey": "MODEL_API_KEY",
        "baseUrl": "https://gateway.example.com/model-api",
        "supportsImageGeneration": true
      }
    ]
  }
}

专用图像路由需要同时设置这两个字段。只包含 imageOnly: true 的旧格式仍然有效：

{
  "id": "image-model",
  "envKey": "MODEL_API_KEY",
  "baseUrl": "https://images.example.com/api/v1",
  "supportsImageGeneration": true,
  "imageOnly": true
}

所选路由必须声明明确的 HTTPS baseUrl 和非空 envKey。图像生成使用该路由相同的端点和凭据；如果聊天与图像生成需要不同的端点或凭据，请配置两个路由。

各 Auth Type 的配置示例

以下是针对不同认证类型的全面配置示例，展示了可用的参数及其组合。

支持的 Auth Type

modelProviders 对象的键必须是有效的 authType 值。当前支持的 auth type 包括：

[!note] Vertex AI 条目可以使用 Application Default Credentials 进行认证。设置 GOOGLE_CLOUD_PROJECT（以及可选的 GOOGLE_CLOUD_LOCATION，默认为 global），并让 envKey 以及解析器读取的所有其他密钥来源保持未设置：GOOGLE_API_KEY、settings.security.auth.apiKey 和 CLI 密钥参数。任何传入 Vertex 条目的 API key 都会使 Google SDK 切换到 Vertex Express 模式，从而忽略项目、区域和 ADC 凭据。声明了 envKey 的条目绝不会转而使用 ADC，因此变量注入失败后会继续针对该变量报错，而不会静默改用其他主体进行认证。

[!warning] 既不是内置协议也未通过 providerProtocol 映射的 provider id（例如拼写错误如 "openai-custom"）无法被路由，因此其整个条目会被跳过并附带警告——其模型不会出现在 /model 选择器中。内置 provider 请使用上面列出的受支持 auth type 值之一，自定义 id 请添加 providerProtocol 映射。

自定义 provider id（providerProtocol）

内置 provider id（openai、gemini、anthropic、vertex-ai、qwen-oauth）会自动路由到其对应的 SDK 协议。要使用自定义 provider id——例如将多个兼容 OpenAI 的端点归组到一个更友好的名称下——请在 modelProviders 中声明它，并通过顶层的 providerProtocol 设置将其映射到内置协议：

{
  "modelProviders": {
    "idealab": [
      {
        "id": "my-model",
        "envKey": "IDEALAB_API_KEY",
        "baseUrl": "https://idealab.example.com/v1"
      }
    ]
  },
  "providerProtocol": {
    "idealab": "openai"
  }
}

如果没有匹配的 providerProtocol 条目，自定义 provider id 会被跳过（见上方警告）。

用于 API 请求的 SDK

Qwen Code 使用以下官方 SDK 向各个提供商发送请求：

这意味着你配置的 baseUrl 必须与相应 SDK 预期的 API 格式兼容。例如，使用 openai auth type 时，端点必须接受 OpenAI API 格式的请求。

兼容 OpenAI 的提供商 (openai)

此 auth type 不仅支持 OpenAI 的官方 API，还支持任何兼容 OpenAI 的端点，包括 OpenRouter 和 Requesty 等聚合模型提供商。

{
  "env": {
    "OPENAI_API_KEY": "sk-your-actual-openai-key-here",
    "OPENROUTER_API_KEY": "sk-or-your-actual-openrouter-key-here",
    "REQUESTY_API_KEY": "sk-your-actual-requesty-key-here"
  },
  "modelProviders": {
    "openai": [
      {
        "id": "gpt-4o",
        "name": "GPT-4o",
        "envKey": "OPENAI_API_KEY",
        "baseUrl": "https://api.openai.com/v1",
        "generationConfig": {
          "timeout": 60000,
          "maxRetries": 3,
          "retryInitialDelayMs": 3000,
          "retryMaxDelayMs": 30000,
          "enableCacheControl": true,
          "contextWindowSize": 128000,
          "modalities": {
            "image": true
          },
          "customHeaders": {
            "X-Client-Request-ID": "req-123"
          },
          "extra_body": {
            "enable_thinking": true,
            "service_tier": "priority"
          },
          "samplingParams": {
            "temperature": 0.2,
            "top_p": 0.8,
            "max_tokens": 4096,
            "presence_penalty": 0.1,
            "frequency_penalty": 0.1
          }
        }
      },
      {
        "id": "gpt-4o-mini",
        "name": "GPT-4o Mini",
        "envKey": "OPENAI_API_KEY",
        "baseUrl": "https://api.openai.com/v1",
        "generationConfig": {
          "timeout": 30000,
          "samplingParams": {
            "temperature": 0.5,
            "max_tokens": 2048
          }
        }
      },
      {
        "id": "openai/gpt-4o",
        "name": "GPT-4o (via OpenRouter)",
        "envKey": "OPENROUTER_API_KEY",
        "baseUrl": "https://openrouter.ai/api/v1",
        "generationConfig": {
          "timeout": 120000,
          "maxRetries": 3,
          "samplingParams": {
            "temperature": 0.7
          }
        }
      },
      {
        "id": "openai/gpt-4o-mini",
        "name": "GPT-4o Mini (via Requesty)",
        "envKey": "REQUESTY_API_KEY",
        "baseUrl": "https://router.requesty.ai/v1",
        "generationConfig": {
          "timeout": 120000,
          "maxRetries": 3,
          "samplingParams": {
            "temperature": 0.7
          }
        }
      }
    ]
  }
}

Anthropic (anthropic)

{
  "env": {
    "ANTHROPIC_API_KEY": "sk-ant-your-actual-anthropic-key-here"
  },
  "modelProviders": {
    "anthropic": [
      {
        "id": "claude-3-5-sonnet",
        "name": "Claude 3.5 Sonnet",
        "envKey": "ANTHROPIC_API_KEY",
        "baseUrl": "https://api.anthropic.com/v1",
        "generationConfig": {
          "timeout": 120000,
          "maxRetries": 3,
          "contextWindowSize": 200000,
          "samplingParams": {
            "temperature": 0.7,
            "max_tokens": 8192,
            "top_p": 0.9
          }
        }
      },
      {
        "id": "claude-3-opus",
        "name": "Claude 3 Opus",
        "envKey": "ANTHROPIC_API_KEY",
        "baseUrl": "https://api.anthropic.com/v1",
        "generationConfig": {
          "timeout": 180000,
          "samplingParams": {
            "temperature": 0.3,
            "max_tokens": 4096
          }
        }
      }
    ]
  }
}

Google Gemini (gemini)

{
  "env": {
    "GEMINI_API_KEY": "AIza-your-actual-gemini-key-here"
  },
  "modelProviders": {
    "gemini": [
      {
        "id": "gemini-2.0-flash",
        "name": "Gemini 2.0 Flash",
        "envKey": "GEMINI_API_KEY",
        "baseUrl": "https://generativelanguage.googleapis.com",
        "capabilities": {
          "vision": true
        },
        "generationConfig": {
          "timeout": 60000,
          "maxRetries": 2,
          "contextWindowSize": 1000000,
          "schemaCompliance": "auto",
          "samplingParams": {
            "temperature": 0.4,
            "top_p": 0.95,
            "max_tokens": 8192,
            "top_k": 40
          }
        }
      }
    ]
  }
}

对于也能遵循正常 Qwen Code agent 策略并使用工具的视觉模型，请同时启用两个 capabilities 以开启完整轮次的图像路由：

"capabilities": {
  "vision": true,
  "agent": true
}

当纯文本主模型将该模型配置为视觉回退时，完整的带图像轮次会在该 provider、模型和端点上保持完整，跨越工具调用和重试。下一个独立轮次会返回到主模型，每个模型请求只接收其目标支持的媒体模态。省略 agent（或设为 false）则保留更安全的 Vision Bridge 转录流程。

本地自托管模型（通过兼容 OpenAI 的 API）

大多数本地推理服务器（vLLM、Ollama、LM Studio 等）都提供兼容 OpenAI 的 API 端点。使用 openai auth type 和本地 baseUrl 进行配置：

{
  "env": {
    "OLLAMA_API_KEY": "ollama",
    "VLLM_API_KEY": "not-needed",
    "LMSTUDIO_API_KEY": "lm-studio"
  },
  "modelProviders": {
    "openai": [
      {
        "id": "qwen2.5-7b",
        "name": "Qwen2.5 7B (Ollama)",
        "envKey": "OLLAMA_API_KEY",
        "baseUrl": "http://localhost:11434/v1",
        "generationConfig": {
          "timeout": 300000,
          "streamIdleTimeoutMs": 600000,
          "maxRetries": 1,
          "contextWindowSize": 32768,
          "samplingParams": {
            "temperature": 0.7,
            "top_p": 0.9,
            "max_tokens": 4096
          }
        }
      },
      {
        "id": "llama-3.1-8b",
        "name": "Llama 3.1 8B (vLLM)",
        "envKey": "VLLM_API_KEY",
        "baseUrl": "http://localhost:8000/v1",
        "generationConfig": {
          "timeout": 120000,
          "maxRetries": 2,
          "contextWindowSize": 128000,
          "samplingParams": {
            "temperature": 0.6,
            "max_tokens": 8192
          }
        }
      },
      {
        "id": "local-model",
        "name": "Local Model (LM Studio)",
        "envKey": "LMSTUDIO_API_KEY",
        "baseUrl": "http://localhost:1234/v1",
        "generationConfig": {
          "timeout": 60000,
          "samplingParams": {
            "temperature": 0.5
          }
        }
      }
    ]
  }
}

对于有排队或响应较慢的本地 OpenAI 兼容服务器，streamIdleTimeoutMs 控制所选模型在流式数据块之间最多可保持静默多久。它会覆盖所选 provider 条目的全局 QWEN_STREAM_IDLE_TIMEOUT_MS 值；设为 0 可禁用空闲保护。除非提高或禁用 QWEN_STREAM_MAX_LIFETIME_MS，否则独立的 15 分钟流生命周期上限仍然生效。

对于不需要身份验证的本地服务器，你可以为 API key 使用任何占位符值：

# For Ollama (no auth required)
export OLLAMA_API_KEY="ollama"
 
# For vLLM (if no auth is configured)
export VLLM_API_KEY="not-needed"

阿里云 Coding Plan

阿里云 Coding Plan 提供了一组针对编码任务优化的预配置 Qwen 模型。此功能面向拥有阿里云 Coding Plan API 访问权限的用户开放，并提供简化的设置体验以及自动更新模型配置的功能。

概述

当你使用 /auth 命令通过阿里云 Coding Plan API key 进行身份验证时，Qwen Code 会自动配置以下模型：

设置

1. 获取阿里云 Coding Plan API key：
   • 中国：https://bailian.console.aliyun.com/?tab=model#/efm/coding_plan 
   • 国际：https://modelstudio.console.alibabacloud.com/?tab=dashboard#/efm/coding_plan 
2. 在 Qwen Code 中运行 /auth 命令
3. 选择 Alibaba ModelStudio，然后从子菜单中选择 Coding Plan
4. 选择你的区域
5. 根据提示输入你的 API key

这些模型将被自动配置并添加到你的 /model 选择器中。

区域

阿里云 Coding Plan 支持两个区域：

区域在身份验证期间进行选择，并存储在 settings.json 的 modelProviders 配置下。要切换区域，请重新运行 /auth 命令并选择不同的区域。

API Key 存储

当你通过 /auth 命令配置 Coding Plan 时，API key 会使用保留的环境变量名 BAILIAN_CODING_PLAN_API_KEY 进行存储。默认情况下，它存储在你的 settings.json 文件的 env 字段中。

# ~/.qwen/.env
BAILIAN_CODING_PLAN_API_KEY=your-api-key-here

自动更新

Coding Plan 模型配置具有版本控制。当 Qwen Code 检测到模型模板有新版本时，会提示你进行更新。接受更新将会：

• 将现有的 Coding Plan 模型配置替换为最新版本
• 保留你手动添加的任何自定义模型配置
• 保持你选中的模型不变；如果它不再存在于更新后的配置中，请使用 /model 选择新模型

更新过程会刷新模型配置和功能，而不会改变你选中的模型。

手动配置（高级）

如果你倾向于手动配置 Coding Plan 模型，可以像配置任何 OpenAI 兼容的 provider 一样将它们添加到 settings.json 中：

{
  "modelProviders": {
    "openai": [
      {
        "id": "qwen3-coder-plus",
        "name": "qwen3-coder-plus",
        "description": "Qwen3-Coder via Alibaba Cloud Coding Plan",
        "envKey": "YOUR_CUSTOM_ENV_KEY",
        "baseUrl": "https://coding.dashscope.aliyuncs.com/v1"
      }
    ]
  }
}

解析层与原子性

有效的 auth/model/credential 值按字段使用以下优先级进行选择（优先采用首个存在的值）。你可以将 --auth-type 与 --model 结合使用，直接指向 provider 条目；这些 CLI flags 会在其他层之前运行。

*当存在时，CLI auth flags 会覆盖设置。否则，由 security.auth.selectedType 或隐式默认值决定 auth type。Qwen OAuth 和 OpenAI 是唯一无需额外配置即可使用的 auth types。

Generation Config 分层：不可穿透的 Provider 层

配置解析遵循严格的分层模型，其中有一条关键规则：modelProvider 层是不可穿透的。

工作原理

1. 当选择了 modelProvider 模型时（例如，通过 /model 命令选择 provider 配置的模型）：

   • 来自 provider 的整个 generationConfig 将被原子地应用
   • Provider 层完全不可穿透——较低层（CLI、env、settings）根本不参与 generationConfig 解析
   • modelProviders[].generationConfig 中定义的所有字段均使用 provider 的值
   • Provider 未定义的所有字段均设置为 undefined（不从 settings 继承）
   • 这确保了 provider 配置作为一个完整、自包含的“密封包”运行

   如果模型列在 modelProviders 中，请将该模型的所有特定于模型的 generation 设置放在匹配的 provider 条目中。对于 provider 模型，顶层的 model.generationConfig 值（包括 contextWindowSize、modalities、customHeaders 和 extra_body）将被忽略。请在 modelProviders[authType][].generationConfig 下配置这些字段以使其生效。

2. 当未选择 modelProvider 模型时（例如，将 --model 与原始模型 ID 一起使用，或直接使用 CLI/env/settings）：

   • 解析会穿透到较低层
   • 字段按 CLI → env → settings → defaults 的顺序填充
   • 这将创建一个 Runtime Model（见下一节）

generationConfig 的逐字段优先级

customHeaders 中的动态值

customHeaders 的值可以包含占位符 ${session_id}，它会在每次请求时扩展为当前 Qwen Code 会话 ID。可用于要求每个对话具有稳定标识符的网关——例如 OpenCode Go 会拒绝缺少 x-opencode-session 的请求：

{
  "generationConfig": {
    "customHeaders": {
      "x-opencode-session": "${session_id}"
    }
  }
}

由于该值是在每次请求时解析的，而非烘焙到 SDK 客户端中，/new 和 /resume 可以在不重启的情况下轮换它。

⚠️ 需要两个步骤。 上面的 provider 条目只是一半——占位符本身是惰性的，你还需要开启 outboundCorrelation.allowDynamicHeaderValues：

{
  "outboundCorrelation": {
    "allowDynamicHeaderValues": true
  }
}

在此之前，包含占位符的值会被丢弃而不会发送，Qwen Code 会在启动时打印一条警告，指明该 header 和此设置名。该 header 绝不会带着字面量 ${session_id} 被发出。

该开关是全局的，因为它是一个同意决策，独立于值被发送到_哪里_：扩展后的值会将实时会话状态带给接收方，而该开关仅控制 ${session_id} 是否可以被扩展。它不会标识是哪个设置源提供了该 header。

隐私说明： 会话 ID 在对话生命周期内是一个稳定的标识符，因此你发送到的任何 host 都可以将该对话的每个请求归组。具体是哪些 host 由哪些 provider 条目携带该 header 决定——没有单独的 host 列表需要与你的 baseUrl 保持同步。

原子字段处理

以下字段被视为原子对象——provider 的值将完全替换整个对象，不会发生合并：

• samplingParams - Temperature、top_p、max_tokens 等。
• customHeaders - 自定义 HTTP headers（可能包含 ${session_id}；参见动态值）
• extra_body - 额外的请求体参数

示例

// 用户设置 (~/.qwen/settings.json)
{
  "model": {
    "generationConfig": {
      "timeout": 30000,
      "samplingParams": { "temperature": 0.5, "max_tokens": 1000 }
    }
  }
}
 
// modelProviders 配置
{
  "modelProviders": {
    "openai": [{
      "id": "gpt-4o",
      "envKey": "OPENAI_API_KEY",
      "generationConfig": {
        "timeout": 60000,
        "samplingParams": { "temperature": 0.2 }
      }
    }]
  }
}

当从 modelProviders 中选择 gpt-4o 时：

• timeout = 60000（来自 provider，覆盖 settings）
• samplingParams.temperature = 0.2（来自 provider，完全替换 settings 对象）
• samplingParams.max_tokens = undefined（未在 provider 中定义，且 provider 层不会从 settings 继承——如果未提供，字段会被显式设置为 undefined）

当通过 --model gpt-4 使用原始模型时（不来自 modelProviders，会创建一个 Runtime Model）：

• timeout = 30000（来自 settings）
• samplingParams.temperature = 0.5（来自 settings）
• samplingParams.max_tokens = 1000（来自 settings）

modelProviders 本身的合并策略是 REPLACE（替换）：项目设置中的整个 modelProviders 将覆盖用户设置中的相应部分，而不是将两者合并。

Reasoning / thinking 配置

generationConfig 下的可选 reasoning 字段控制模型在响应前进行推理的积极程度。Anthropic 和 Gemini 转换器始终遵循该字段。OpenAI 兼容管道也会遵循，除非设置了 generationConfig.samplingParams —— 请参阅下面的“与 samplingParams 的交互”注意事项。

{
  "modelProviders": {
    "openai": [
      {
        "id": "deepseek-v4-pro",
        "name": "DeepSeek V4 Pro",
        "baseUrl": "https://api.deepseek.com/v1",
        "envKey": "DEEPSEEK_API_KEY",
        "generationConfig": {
          // 四级强度：
          //   'low'    | 'medium' — 在 DeepSeek 服务端会映射为 'high'
          //   'high'   — 默认推理强度
          //   'max'    — DeepSeek 特有的超强级别
          // 或者设置为 `false` 以完全禁用推理。
          "reasoning": { "effort": "max" },
        },
      },
    ],
  },
}

各 provider 的行为

reasoning: false

设置 reasoning: false（字面量布尔值）会在所有 provider 上显式禁用思考功能——这对于不需要推理的低成本辅助查询非常有用。在请求级别，也可以通过 request.config.thinkingConfig.includeThoughts: false 来遵循此设置，用于一次性调用（例如建议生成）。

在 api.deepseek.com baseURL 下，OpenAI 管道会发出 DeepSeek V4+ 所需的显式 thinking: { type: 'disabled' } 字段 —— 服务端默认值为 'enabled'，因此仅仅省略 reasoning_effort 仍然会产生思考的延迟/成本。自托管的 DeepSeek 后端（sglang/vllm）和其他 OpenAI 兼容服务器不会接收此字段；如果你需要在这些后端上禁用思考，请通过 samplingParams/extra_body 注入 thinking: { type: 'disabled' }（或你的推理框架暴露的任何控制参数）。

在 openrouter.ai baseURL 下，禁用推理时，OpenAI 管道会发送 OpenRouter 的 provider 级 reasoning: { enabled: false } 字段。其他 OpenAI 兼容服务器不会收到这一 OpenRouter 专用字段；请通过 samplingParams/extra_body 使用它们各自的原生禁用参数。

与 samplingParams 的交互（仅限 OpenAI 兼容）

budget_tokens

你可以通过在 effort 旁边包含 budget_tokens 来固定精确的思考 token 预算：

"reasoning": { "effort": "high", "budget_tokens": 50000 }

对于 Anthropic，这会转换为 thinking.budget_tokens。对于 OpenAI/DeepSeek，该字段会被保留但目前被服务端忽略 —— reasoning_effort 才是起实际作用的控制参数。

Provider Models 与 Runtime Models

Qwen Code 区分两种类型的模型配置：

Provider Model

• 在 modelProviders 配置中定义
• 拥有完整、原子的配置包
• 被选中时，其配置会作为一个不可穿透的层应用
• 出现在 /model 命令列表中，并带有完整的元数据（名称、描述、能力）
• 推荐用于多模型工作流和保持团队一致性

Runtime Model

• 当通过 CLI (--model)、环境变量或设置使用原始模型 ID 时动态创建
• 未在 modelProviders 中定义
• 配置是通过“投影”解析层（CLI → env → settings → defaults）构建的
• 当检测到完整配置时，会自动捕获为 RuntimeModelSnapshot
• 允许重复使用而无需重新输入凭据

RuntimeModelSnapshot 生命周期

当你不使用 modelProviders 配置模型时，Qwen Code 会自动创建一个 RuntimeModelSnapshot 来保留你的配置：

# 这会创建一个 ID 为 $runtime|openai|my-custom-model 的 RuntimeModelSnapshot
qwen --auth-type openai --model my-custom-model --openai-api-key $KEY --openai-base-url https://api.example.com/v1

该快照：

• 捕获模型 ID、API key、base URL 和 generation config
• 跨会话持久化（在运行期间存储在内存中）
• 作为运行时选项出现在 /model 命令列表中
• 可以使用 /model $runtime|openai|my-custom-model 切换至该模型

主要区别

何时使用哪种

• 使用 Provider Models：当你有团队共享的标准模型、需要一致的配置，或者想要防止意外覆盖时。
• 使用 Runtime Models：当你快速测试新模型、使用临时凭据，或处理临时端点时。

选择持久化与建议

• /model 和 /auth 会将 model.name（如适用）和 security.auth.selectedType 持久化到已定义 modelProviders 的最近可写作用域；否则它们会回退到用户作用域。这使工作区/用户文件与活动的 provider 目录保持同步。
• 如果没有 modelProviders，解析器会混合 CLI/env/settings 层，从而创建 Runtime Models。这对于单 provider 设置来说没问题，但在频繁切换时会很繁琐。当多模型工作流很常见时，请定义 provider 目录，以便切换保持原子性、来源可追溯且可调试。