Skip to content

Add modelProviders configuration guide to Qwen Code user guide (+177 lines) #12

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
wenshao merged 4 commits into from
Mar 29, 2026
Merged

Add modelProviders configuration guide to Qwen Code user guide (+177 lines) #12

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
ade536a
Add modelProviders configuration guide to Qwen Code user guide (+177 …
wenshao Mar 28, 2026
5481579
Fix 5 issues from Qwen-Code + GLM-5.1 source code review
wenshao Mar 28, 2026
7398d7e
Fix 5 issues from Qwen-Code + GLM-5.1 R2
wenshao Mar 29, 2026
4c3a83e
Fix 3 issues from Qwen-Code + GLM-5.1 R3
wenshao Mar 29, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
183 changes: 183 additions & 0 deletions docs/guides/qwen-code-user-guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -249,6 +249,189 @@ Express + TypeScript + PostgreSQL + Prisma
}
```

### modelProviders 配置（自定义模型提供商）

> 源码：`packages/core/src/models/types.ts`（ModelConfig 接口）、`packages/core/src/core/contentGenerator.ts`（generationConfig）

`modelProviders` 是 Qwen Code 最强大的配置项——可以接入任何 OpenAI 兼容 API、Anthropic、Gemini 以及本地模型。配置后通过 `/model` 切换。

**配置位置**：`~/.qwen/settings.json`（用户级）或 `.qwen/settings.json`（项目级）

**顶层结构**：

```json
{
"modelProviders": {
"openai": [ /* OpenAI 兼容的模型列表 */ ],
"anthropic": [ /* Anthropic 模型列表 */ ],

@wenshao wenshao Mar 28, 2026

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[Qwen-Code + GLM-5.1 — Round 2] 顶层结构示例只列出 openai、anthropic、gemini 三个 authType，但源码 AuthType 枚举有 5 个值：

export enum AuthType {
  USE_OPENAI = "openai",
  QWEN_OAUTH = "qwen-oauth",
  USE_GEMINI = "gemini",
  USE_VERTEX_AI = "vertex-ai",
  USE_ANTHROPIC = "anthropic",
}

建议在示例中补充注释："vertex-ai": [ /* Google Vertex AI */ ]，以及 "qwen-oauth" （内置，不可覆盖）。

"gemini": [ /* Google Gemini 模型列表 */ ]
}
}
```

三个用户可配置的 `authType` 键决定使用哪个 SDK：`openai`（OpenAI SDK）、`anthropic`（Anthropic SDK）、`gemini`（Google GenAI SDK）。DeepSeek、OpenRouter、Ollama 等 OpenAI 兼容服务都使用 `openai` 键。

**ModelConfig 字段**：

@wenshao wenshao Mar 29, 2026

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[Qwen-Code + GLM-5.1 — Round 3] 文字说"四个用户可配置的 authType 键"，但上方 JSON 代码块只有 3 个键（openai、anthropic、gemini）。两者需保持一致。

另外，关于 vertex-ai：经核查官方文档 docs/users/configuration/model-providers.md，只列出 4 个 authType（openai、anthropic、gemini、qwen-oauth），未包含 vertex-ai。AuthType 枚举中的 vertex-ai 可能仅用于 --auth-type vertex-ai CLI 流程，而非 modelProviders 配置。这是 Round 2 中我的建议不够严谨，在此纠正。

建议：改回"三个用户可配置的 authType 键"或在 vertex-ai 后标注"（待验证）"。


| 字段 | 类型 | 必须 | 说明 |
|------|------|------|------|
| `id` | string | **是** | 发送给 API 的模型 ID（如 `"gpt-4o"`、`"deepseek-chat"`） |
| `name` | string | 否 | UI 显示名称（默认为 id） |
| `description` | string | 否 | 模型描述 |
| `envKey` | string | 否 | 存放 API Key 的**环境变量名**（如 `"OPENAI_API_KEY"`）。自定义提供商通常需要，`qwen-oauth` 不需要 |
| `baseUrl` | string | 否 | API 端点覆盖（自定义提供商必须） |
| `capabilities` | object | 否 | 模型能力标记（如 `{ vision: true }`），预留字段 |
| `generationConfig` | object | 否 | 生成参数（见下方） |

@wenshao wenshao Mar 28, 2026

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[Qwen-Code + GLM-5.1] ModelConfig 字段表缺少 capabilities 字段。源码定义了：

capabilities?: ModelCapabilities;
// where ModelCapabilities = { vision?: boolean }

建议在 generationConfig 行之后补充一行：
| capabilities | object | 否 | 模型能力标记（如 { vision: true }），预留字段 |

@wenshao wenshao Mar 28, 2026

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

已补充 capabilities 字段（{ vision: true }，预留字段）。

— Claude Opus 4.6

@wenshao wenshao Mar 28, 2026

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[Qwen-Code + GLM-5.1] ModelConfig 字段表缺少 capabilities 字段。源码定义了：

capabilities?: ModelCapabilities;
// where ModelCapabilities = { vision?: boolean }

建议在 generationConfig 行之后补充一行：
| capabilities | object | 否 | 模型能力标记（如 { vision: true }），预留字段 |


**generationConfig 完整字段列表**（11 个）：

@wenshao wenshao Mar 28, 2026

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[Qwen-Code + GLM-5.1 — Round 2] 表格标题写「generationConfig 常用字段」，但实际已列出全部 11/11 个字段。建议改为「generationConfig 完整字段列表」或直接「generationConfig 字段」，避免"常用"让读者误以为还有未列出的字段。

| 字段 | 说明 |
|------|------|
| `timeout` | 请求超时（毫秒） |
| `maxRetries` | 速率限制重试次数 |
| `contextWindowSize` | 覆盖自动检测的上下文窗口大小 |
| `enableCacheControl` | 启用缓存控制（DashScope 提供商） |
| `retryErrorCodes` | 自定义触发重试的 HTTP 状态码（`number[]`） |
| `reasoning` | 推理模式：`false` 或 `{ effort?: "low"\|"medium"\|"high", budget_tokens?: number }` |
| `schemaCompliance` | Schema 合规模式：`"auto"` 或 `"openapi_30"` |
| `customHeaders` | 自定义 HTTP 头（**atomic，完全替换**，`Record<string, string>`） |
| `extra_body` | 额外请求体参数（仅 OpenAI 兼容，**atomic，完全替换**，`Record<string, unknown>`） |
| `modalities` | 输入模态控制：`{ image?, pdf?, audio?, video?: boolean }` |
| `samplingParams` | 采样参数（**atomic，完全替换不合并**）：`temperature`、`top_p`、`top_k`、`max_tokens`、`presence_penalty`、`frequency_penalty`、`repetition_penalty` |

#### 常见提供商配置示例

**DashScope（阿里云百炼编码计划）**：

```json
{
"modelProviders": {
"openai": [{
"id": "qwen3-coder-plus",
"name": "Qwen3-Coder-Plus（百炼）",
"envKey": "BAILIAN_CODING_PLAN_API_KEY",
"baseUrl": "https://coding.dashscope.aliyuncs.com/v1"
}]
}
}
```

**DeepSeek（OpenAI 兼容）**：

```json
{
"modelProviders": {
"openai": [{
"id": "deepseek-chat",
"name": "DeepSeek Chat",
"envKey": "DEEPSEEK_API_KEY",
"baseUrl": "https://api.deepseek.com/v1"
}]
}
}
```

**OpenRouter（100+ 模型聚合）**：

```json
{
"modelProviders": {
"openai": [{
"id": "openai/gpt-4o",
"name": "GPT-4o（OpenRouter）",
"envKey": "OPENROUTER_API_KEY",
"baseUrl": "https://openrouter.ai/api/v1"
}]
}
}
```

**Ollama（本地模型，无需付费）**：

```json
{
"modelProviders": {
"openai": [{
"id": "qwen2.5-7b",
"name": "Qwen2.5 7B（本地）",
"envKey": "OLLAMA_API_KEY",
"baseUrl": "http://localhost:11434/v1",
"generationConfig": {
"timeout": 300000,
"contextWindowSize": 32768
}
}]
}
}
```

> Ollama 不需要真实 API Key，设置任意占位值即可：`export OLLAMA_API_KEY="ollama"`

**Anthropic（Claude 系列）**：

```json
{
"modelProviders": {
"anthropic": [{
"id": "claude-sonnet-4-5",
"name": "Claude Sonnet 4.5",
"envKey": "ANTHROPIC_API_KEY",
"generationConfig": {
"contextWindowSize": 200000
}
}]
}
}
```

**Google Gemini**：

```json
{
"modelProviders": {
"gemini": [{
"id": "gemini-2.5-flash",
"name": "Gemini 2.5 Flash",
"envKey": "GEMINI_API_KEY",
"generationConfig": {
"contextWindowSize": 1000000
}
}]
}
}
```

#### 多提供商组合配置

```json
{
"modelProviders": {
"openai": [
{ "id": "gpt-4o", "name": "GPT-4o", "envKey": "OPENAI_API_KEY" },
{ "id": "deepseek-chat", "name": "DeepSeek", "envKey": "DEEPSEEK_API_KEY", "baseUrl": "https://api.deepseek.com/v1" },
{ "id": "qwen2.5-7b", "name": "Qwen 本地", "envKey": "OLLAMA_API_KEY", "baseUrl": "http://localhost:11434/v1" }
],
"anthropic": [
{ "id": "claude-sonnet-4-5", "name": "Claude Sonnet 4.5", "envKey": "ANTHROPIC_API_KEY" }
],
"gemini": [
{ "id": "gemini-2.5-flash", "name": "Gemini Flash", "envKey": "GEMINI_API_KEY" }
]
}
}
```

配置完成后通过 `/model` 命令切换，所有配置的模型都会出现在选择列表中。

#### 注意事项

- **API Key 不存储在配置中**——`envKey` 引用的是环境变量名，运行时从 `process.env` 读取
- **同一 authType 内不支持重复 id**——首个生效，后续重复跳过并发出警告
- **项目级覆盖用户级**——`.qwen/settings.json` 的 `modelProviders` **完全替换**（非合并）`~/.qwen/settings.json` 的同名配置
- **无效 authType 键静默忽略**——拼写错误（如 `"openai-custom"`）不会报错也不会生效
- **`samplingParams`/`customHeaders`/`extra_body` 是 atomic（完全替换）**——如果你只设置 `samplingParams: { temperature: 0.5 }`，其他参数（`top_p` 等）不会继承默认值，而是变为 `undefined`
- **`qwen-oauth` 不可覆盖**——内置的 OAuth 免费层无法通过 modelProviders 自定义

### 权限模式

```bash
Expand Down