From ade536ac7d3f5289e9e01534a49ed3544dd0fa18 Mon Sep 17 00:00:00 2001 From: wenshao Date: Sun, 29 Mar 2026 07:37:53 +0800 Subject: [PATCH 1/4] Add modelProviders configuration guide to Qwen Code user guide (+177 lines) - Full ModelConfig field reference (id, name, envKey, baseUrl, generationConfig) - generationConfig fields (timeout, contextWindowSize, reasoning, samplingParams) - 6 provider examples: DashScope, DeepSeek, OpenRouter, Ollama, Anthropic, Gemini - Multi-provider combined config example - 5 behavioral notes (envKey security, duplicate handling, project override, etc.) - Source: packages/core/src/models/types.ts (ModelConfig interface) Co-Authored-By: Claude Opus 4.6 (1M context) --- docs/guides/qwen-code-user-guide.md | 177 ++++++++++++++++++++++++++++ 1 file changed, 177 insertions(+) diff --git a/docs/guides/qwen-code-user-guide.md b/docs/guides/qwen-code-user-guide.md index 0ac2e904..7b737c39 100644 --- a/docs/guides/qwen-code-user-guide.md +++ b/docs/guides/qwen-code-user-guide.md @@ -249,6 +249,183 @@ Express + TypeScript + PostgreSQL + Prisma } ``` +### modelProviders 配置（自定义模型提供商） + +> 源码：`packages/core/src/models/types.ts`（ModelConfig 接口） + +`modelProviders` 是 Qwen Code 最强大的配置项——可以接入任何 OpenAI 兼容 API、Anthropic、Gemini 以及本地模型。配置后通过 `/model` 切换。 + +**配置位置**：`~/.qwen/settings.json`（用户级）或 `.qwen/settings.json`（项目级） + +**顶层结构**： + +```json +{ + "modelProviders": { + "openai": [ /* OpenAI 兼容的模型列表 */ ], + "anthropic": [ /* Anthropic 模型列表 */ ], + "gemini": [ /* Google Gemini 模型列表 */ ] + } +} +``` + +三个 `authType` 键决定使用哪个 SDK：`openai`（OpenAI SDK）、`anthropic`（Anthropic SDK）、`gemini`（Google GenAI SDK）。DeepSeek、OpenRouter、Ollama 等 OpenAI 兼容服务都使用 `openai` 键。 + +**ModelConfig 字段**： + +| 字段 | 类型 | 必须 | 说明 | +|------|------|------|------| +| `id` | string | **是** | 发送给 API 的模型 ID（如 `"gpt-4o"`、`"deepseek-chat"`） | +| `name` | string | 否 | UI 显示名称（默认为 id） | +| `description` | string | 否 | 模型描述 | +| `envKey` | string | **是** | 存放 API Key 的**环境变量名**（如 `"OPENAI_API_KEY"`） | +| `baseUrl` | string | 否 | API 端点覆盖（自定义提供商必须） | +| `generationConfig` | object | 否 | 生成参数（见下方） | + +**generationConfig 常用字段**： + +| 字段 | 说明 | +|------|------| +| `timeout` | 请求超时（毫秒） | +| `maxRetries` | 速率限制重试次数 | +| `contextWindowSize` | 覆盖自动检测的上下文窗口大小 | +| `enableCacheControl` | 启用缓存控制（DashScope 提供商） | +| `reasoning` | 推理模式：`false` 或 `{ effort: "low"\|"medium"\|"high" }` | +| `customHeaders` | 自定义 HTTP 头 | +| `samplingParams` | 采样参数：`temperature`、`top_p`、`top_k`、`max_tokens` 等 | + +#### 常见提供商配置示例 + +**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"`）不会报错也不会生效 +- **`qwen-oauth` 不可覆盖**——内置的 OAuth 免费层无法通过 modelProviders 自定义 + ### 权限模式 ```bash From 54815790b5c67c55c8e0bdaf8658a28b2a08c4f4 Mon Sep 17 00:00:00 2001 From: wenshao Date: Sun, 29 Mar 2026 07:52:10 +0800 Subject: [PATCH 2/4] Fix 5 issues from Qwen-Code + GLM-5.1 source code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 1. envKey: "必须" → "否" (source: envKey?: string, optional with ?) 2. Add capabilities field to ModelConfig table ({ vision: true }) 3. Add 4 missing generationConfig fields: retryErrorCodes, schemaCompliance, extra_body, modalities (7/11 → 11/11) 4. reasoning: add budget_tokens parameter 5. Add contentGenerator.ts to source reference Co-Authored-By: Claude Opus 4.6 (1M context) --- docs/guides/qwen-code-user-guide.md | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/docs/guides/qwen-code-user-guide.md b/docs/guides/qwen-code-user-guide.md index 7b737c39..388ac196 100644 --- a/docs/guides/qwen-code-user-guide.md +++ b/docs/guides/qwen-code-user-guide.md @@ -251,7 +251,7 @@ Express + TypeScript + PostgreSQL + Prisma ### modelProviders 配置（自定义模型提供商） -> 源码：`packages/core/src/models/types.ts`（ModelConfig 接口） +> 源码：`packages/core/src/models/types.ts`（ModelConfig 接口）、`packages/core/src/core/contentGenerator.ts`（generationConfig） `modelProviders` 是 Qwen Code 最强大的配置项——可以接入任何 OpenAI 兼容 API、Anthropic、Gemini 以及本地模型。配置后通过 `/model` 切换。 @@ -278,8 +278,9 @@ Express + TypeScript + PostgreSQL + Prisma | `id` | string | **是** | 发送给 API 的模型 ID（如 `"gpt-4o"`、`"deepseek-chat"`） | | `name` | string | 否 | UI 显示名称（默认为 id） | | `description` | string | 否 | 模型描述 | -| `envKey` | string | **是** | 存放 API Key 的**环境变量名**（如 `"OPENAI_API_KEY"`） | +| `envKey` | string | 否 | 存放 API Key 的**环境变量名**（如 `"OPENAI_API_KEY"`）。自定义提供商通常需要，`qwen-oauth` 不需要 | | `baseUrl` | string | 否 | API 端点覆盖（自定义提供商必须） | +| `capabilities` | object | 否 | 模型能力标记（如 `{ vision: true }`），预留字段 | | `generationConfig` | object | 否 | 生成参数（见下方） | **generationConfig 常用字段**： @@ -290,8 +291,12 @@ Express + TypeScript + PostgreSQL + Prisma | `maxRetries` | 速率限制重试次数 | | `contextWindowSize` | 覆盖自动检测的上下文窗口大小 | | `enableCacheControl` | 启用缓存控制（DashScope 提供商） | -| `reasoning` | 推理模式：`false` 或 `{ effort: "low"\|"medium"\|"high" }` | -| `customHeaders` | 自定义 HTTP 头 | +| `retryErrorCodes` | 自定义触发重试的 HTTP 状态码（`number[]`） | +| `reasoning` | 推理模式：`false` 或 `{ effort?: "low"\|"medium"\|"high", budget_tokens?: number }` | +| `schemaCompliance` | Schema 合规模式：`"auto"` 或 `"openapi_30"` | +| `customHeaders` | 自定义 HTTP 头（`Record`） | +| `extra_body` | 额外请求体参数（仅 OpenAI 兼容，`Record`） | +| `modalities` | 输入模态控制（如 `{ image: true }`） | | `samplingParams` | 采样参数：`temperature`、`top_p`、`top_k`、`max_tokens` 等 | #### 常见提供商配置示例 From 7398d7e14354d4b498938caed16896db97a001f2 Mon Sep 17 00:00:00 2001 From: wenshao Date: Sun, 29 Mar 2026 08:03:27 +0800 Subject: [PATCH 3/4] Fix 5 issues from Qwen-Code + GLM-5.1 R2 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 1. "常用字段" → "完整字段列表" (now 11/11, not "commonly used") 2. Add atomic behavior warning for samplingParams/customHeaders/extra_body 3. samplingParams: add 3 missing fields (presence/frequency/repetition_penalty) 4. Add vertex-ai as 4th user-configurable authType 5. modalities: expand to full 4-field format (image/pdf/audio/video) Co-Authored-By: Claude Opus 4.6 (1M context) --- docs/guides/qwen-code-user-guide.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/guides/qwen-code-user-guide.md b/docs/guides/qwen-code-user-guide.md index 388ac196..5277fd1c 100644 --- a/docs/guides/qwen-code-user-guide.md +++ b/docs/guides/qwen-code-user-guide.md @@ -269,7 +269,7 @@ Express + TypeScript + PostgreSQL + Prisma } ``` -三个 `authType` 键决定使用哪个 SDK：`openai`（OpenAI SDK）、`anthropic`（Anthropic SDK）、`gemini`（Google GenAI SDK）。DeepSeek、OpenRouter、Ollama 等 OpenAI 兼容服务都使用 `openai` 键。 +四个用户可配置的 `authType` 键决定使用哪个 SDK：`openai`（OpenAI SDK）、`anthropic`（Anthropic SDK）、`gemini`（Google GenAI SDK）、`vertex-ai`（Google Vertex AI SDK）。DeepSeek、OpenRouter、Ollama 等 OpenAI 兼容服务都使用 `openai` 键。 **ModelConfig 字段**： @@ -283,7 +283,7 @@ Express + TypeScript + PostgreSQL + Prisma | `capabilities` | object | 否 | 模型能力标记（如 `{ vision: true }`），预留字段 | | `generationConfig` | object | 否 | 生成参数（见下方） | -**generationConfig 常用字段**： +**generationConfig 完整字段列表**（11 个）： | 字段 | 说明 | |------|------| @@ -296,8 +296,8 @@ Express + TypeScript + PostgreSQL + Prisma | `schemaCompliance` | Schema 合规模式：`"auto"` 或 `"openapi_30"` | | `customHeaders` | 自定义 HTTP 头（`Record`） | | `extra_body` | 额外请求体参数（仅 OpenAI 兼容，`Record`） | -| `modalities` | 输入模态控制（如 `{ image: true }`） | -| `samplingParams` | 采样参数：`temperature`、`top_p`、`top_k`、`max_tokens` 等 | +| `modalities` | 输入模态控制：`{ image?, pdf?, audio?, video?: boolean }` | +| `samplingParams` | 采样参数（**atomic，完全替换不合并**）：`temperature`、`top_p`、`top_k`、`max_tokens`、`presence_penalty`、`frequency_penalty`、`repetition_penalty` | #### 常见提供商配置示例 @@ -429,6 +429,7 @@ Express + TypeScript + PostgreSQL + Prisma - **同一 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 自定义 ### 权限模式 From 4c3a83e5b8c8c4ebfb0fb75846725e7ae1be8d6c Mon Sep 17 00:00:00 2001 From: wenshao Date: Sun, 29 Mar 2026 08:10:14 +0800 Subject: [PATCH 4/4] Fix 3 issues from Qwen-Code + GLM-5.1 R3 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 1. Revert vertex-ai: 4 authTypes → 3 (vertex-ai not in official modelProviders docs, only in CLI --auth-type; GLM-5.1 self-corrected their R2 suggestion) 2. Add atomic annotation to customHeaders and extra_body table rows (consistent with samplingParams) 3. Issue #4 (Resolution Layers): deferred — advanced topic beyond user guide scope Co-Authored-By: Claude Opus 4.6 (1M context) --- docs/guides/qwen-code-user-guide.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/guides/qwen-code-user-guide.md b/docs/guides/qwen-code-user-guide.md index 5277fd1c..3c7da826 100644 --- a/docs/guides/qwen-code-user-guide.md +++ b/docs/guides/qwen-code-user-guide.md @@ -269,7 +269,7 @@ Express + TypeScript + PostgreSQL + Prisma } ``` -四个用户可配置的 `authType` 键决定使用哪个 SDK：`openai`（OpenAI SDK）、`anthropic`（Anthropic SDK）、`gemini`（Google GenAI SDK）、`vertex-ai`（Google Vertex AI SDK）。DeepSeek、OpenRouter、Ollama 等 OpenAI 兼容服务都使用 `openai` 键。 +三个用户可配置的 `authType` 键决定使用哪个 SDK：`openai`（OpenAI SDK）、`anthropic`（Anthropic SDK）、`gemini`（Google GenAI SDK）。DeepSeek、OpenRouter、Ollama 等 OpenAI 兼容服务都使用 `openai` 键。 **ModelConfig 字段**： @@ -294,8 +294,8 @@ Express + TypeScript + PostgreSQL + Prisma | `retryErrorCodes` | 自定义触发重试的 HTTP 状态码（`number[]`） | | `reasoning` | 推理模式：`false` 或 `{ effort?: "low"\|"medium"\|"high", budget_tokens?: number }` | | `schemaCompliance` | Schema 合规模式：`"auto"` 或 `"openapi_30"` | -| `customHeaders` | 自定义 HTTP 头（`Record`） | -| `extra_body` | 额外请求体参数（仅 OpenAI 兼容，`Record`） | +| `customHeaders` | 自定义 HTTP 头（**atomic，完全替换**，`Record`） | +| `extra_body` | 额外请求体参数（仅 OpenAI 兼容，**atomic，完全替换**，`Record`） | | `modalities` | 输入模态控制：`{ image?, pdf?, audio?, video?: boolean }` | | `samplingParams` | 采样参数（**atomic，完全替换不合并**）：`temperature`、`top_p`、`top_k`、`max_tokens`、`presence_penalty`、`frequency_penalty`、`repetition_penalty` |