@qwen-code/qwen-code 0.19.0 → 0.19.1-nightly.20260624.a234860a4

package/bundled/qc-helper/docs/configuration/model-providers.md

@@ -4,11 +4,11 @@ Qwen Code allows you to configure multiple model providers through the `modelPro
 
 ## Overview
 
-Use `modelProviders` to declare curated model lists per auth type that the `/model` picker can switch between. Keys must be valid auth types (`openai`, `anthropic`, `gemini`, etc.). Each entry requires an `id` and **must include `envKey`**, with optional `name`, `description`, `baseUrl`, and `generationConfig`. Credentials are never persisted in settings; the runtime reads them from `process.env[envKey]`. Qwen OAuth models remain hard-coded and cannot be overridden.
+Use `modelProviders` to declare models per auth type that the `/model` picker can switch between. Keys must be valid auth types (`openai`, `anthropic`, `gemini`, etc.). Each auth type maps to a `ProviderConfig` object with a `protocol` field and a `models` field (the array of model definitions). Each entry in `models` requires an `id`; `envKey` is **optional and recommended** (when omitted, it falls back to the auth type's default env key, e.g. `OPENAI_API_KEY` for `openai`), with optional `name`, `description`, `baseUrl`, and `generationConfig`. Credentials are never persisted in settings; the runtime reads them from `process.env[envKey]`. Qwen OAuth models remain hard-coded and cannot be overridden.
 
 > [!note]
 >
-> Only the `/model` command exposes non-default auth types. Anthropic, Gemini, etc., must be defined via `modelProviders`. The `/auth` command lists Qwen OAuth, Alibaba Cloud Coding Plan, and API Key as the built-in authentication options.
+> Only the `/model` command exposes non-default auth types. Anthropic, Gemini, etc., must be defined via `modelProviders`. The `/auth` command lists three top-level options: **Alibaba ModelStudio** (with Coding Plan, Token Plan, and Standard API Key in its sub-menu), **Third-party Providers**, and **Custom Provider**. (Qwen OAuth is no longer a selectable dialog entry; its free tier was discontinued on 2026-04-15.)
 
 > [!note]
 >
@@ -28,9 +28,10 @@ The `modelProviders` object keys must be valid `authType` values. Currently supp
 | `anthropic`  | Anthropic Claude API                                                                    |
 | `gemini`     | Google Gemini API                                                                       |
 | `qwen-oauth` | Qwen OAuth (hard-coded, cannot be overridden in `modelProviders`)                       |
+| `vertex-ai`  | Google Vertex AI (uses the `gemini` protocol and the `@google/genai` SDK in Vertex AI mode; selecting it sets `GOOGLE_GENAI_USE_VERTEXAI=true`) |
 
 > [!warning]
-> If an invalid auth type key is used (e.g., a typo like `"openai-custom"`), the configuration will be **silently skipped** and the models will not appear in the `/model` picker. Always use one of the supported auth type values listed above.
+> If an unknown auth type key is used (e.g., a typo like `"openai-custom"`), a non-empty key is accepted as-is as its own auth-type group, but it will not map to a known protocol — so its models won't work as intended and won't behave correctly in the `/model` picker. Only blank (empty or whitespace-only) keys are skipped. Always use one of the supported auth type values listed above.
 
 ### SDKs Used for API Requests
 
@@ -57,76 +58,79 @@ This auth type supports not only OpenAI's official API but also any OpenAI-compa
     "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,
-          "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
+    "openai": {
+      "protocol": "openai",
+      "models": [
+        {
+          "id": "gpt-4o",
+          "name": "GPT-4o",
+          "envKey": "OPENAI_API_KEY",
+          "baseUrl": "https://api.openai.com/v1",
+          "generationConfig": {
+            "timeout": 60000,
+            "maxRetries": 3,
+            "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": "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",
+          "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
+        },
+        {
+          "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
+            }
           }
         }
-      }
-    ]
+      ]
+    }
   }
 }
 ```
@@ -139,37 +143,40 @@ This auth type supports not only OpenAI's official API but also any OpenAI-compa
     "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
+    "anthropic": {
+      "protocol": "anthropic",
+      "models": [
+        {
+          "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
+        },
+        {
+          "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
+            }
           }
         }
-      }
-    ]
+      ]
+    }
   }
 }
 ```
@@ -182,29 +189,32 @@ This auth type supports not only OpenAI's official API but also any OpenAI-compa
     "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
+    "gemini": {
+      "protocol": "gemini",
+      "models": [
+        {
+          "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
+            }
           }
         }
-      }
-    ]
+      ]
+    }
   }
 }
 ```
@@ -221,51 +231,54 @@ Most local inference servers (vLLM, Ollama, LM Studio, etc.) provide an OpenAI-c
     "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,
-          "maxRetries": 1,
-          "contextWindowSize": 32768,
-          "samplingParams": {
-            "temperature": 0.7,
-            "top_p": 0.9,
-            "max_tokens": 4096
+    "openai": {
+      "protocol": "openai",
+      "models": [
+        {
+          "id": "qwen2.5-7b",
+          "name": "Qwen2.5 7B (Ollama)",
+          "envKey": "OLLAMA_API_KEY",
+          "baseUrl": "http://localhost:11434/v1",
+          "generationConfig": {
+            "timeout": 300000,
+            "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": "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
+        },
+        {
+          "id": "local-model",
+          "name": "Local Model (LM Studio)",
+          "envKey": "LMSTUDIO_API_KEY",
+          "baseUrl": "http://localhost:1234/v1",
+          "generationConfig": {
+            "timeout": 60000,
+            "samplingParams": {
+              "temperature": 0.5
+            }
           }
         }
-      }
-    ]
+      ]
+    }
   }
 }
 ```
@@ -332,7 +345,7 @@ When you authenticate with an Alibaba Cloud Coding Plan API key using the `/auth
    - **China**: <https://bailian.console.aliyun.com/?tab=model#/efm/coding_plan>
    - **International**: <https://modelstudio.console.alibabacloud.com/?tab=dashboard#/efm/coding_plan>
 2. Run the `/auth` command in Qwen Code
-3. Select **Alibaba Cloud Coding Plan**
+3. Select **Alibaba ModelStudio**, then choose **Coding Plan** from the sub-menu
 4. Select your region
 5. Enter your API key when prompted
 
@@ -381,15 +394,18 @@ If you prefer to manually configure Coding Plan models, you can add them to your
 ```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"
-      }
-    ]
+    "openai": {
+      "protocol": "openai",
+      "models": [
+        {
+          "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"
+        }
+      ]
+    }
   }
 }
 ```
@@ -414,10 +430,10 @@ The effective auth/model/credential values are chosen per field using the follow
 | -------------------------- | ----------------------------------- | ----------------------------------------------- | --------------------------------------------------- | ---------------------------------------------------- | ---------------------- | --------------------------------- |
 | Programmatic overrides     | `/auth`                             | `/auth` input                                   | `/auth` input                                       | `/auth` input                                        | —                      | —                                 |
 | Model provider selection   | —                                   | `modelProvider.id`                              | `env[modelProvider.envKey]`                         | `modelProvider.baseUrl`                              | `modelProvider.envKey` | —                                 |
-| CLI arguments              | `--auth-type`                       | `--model`                                       | `--openaiApiKey` (or provider-specific equivalents) | `--openaiBaseUrl` (or provider-specific equivalents) | —                      | —                                 |
+| CLI arguments              | `--auth-type`                       | `--model`                                       | `--openai-api-key` (or provider-specific equivalents) | `--openai-base-url` (or provider-specific equivalents) | —                      | —                                 |
 | Environment variables      | —                                   | Provider-specific mapping (e.g. `OPENAI_MODEL`) | Provider-specific mapping (e.g. `OPENAI_API_KEY`)   | Provider-specific mapping (e.g. `OPENAI_BASE_URL`)   | —                      | —                                 |
 | Settings (`settings.json`) | `security.auth.selectedType`        | `model.name`                                    | `security.auth.apiKey`                              | `security.auth.baseUrl`                              | —                      | —                                 |
-| Default / computed         | Falls back to `AuthType.QWEN_OAUTH` | Built-in default (OpenAI ⇒ `qwen3-coder-plus`)  | —                                                   | —                                                    | —                      | `Config.getProxy()` if configured |
+| Default / computed         | Falls back to `AuthType.QWEN_OAUTH` | Built-in default (OpenAI ⇒ `qwen3.5-plus`)  | —                                                   | —                                                    | —                      | `Config.getProxy()` if configured |
 
 \*When present, CLI auth flags override settings. Otherwise, `security.auth.selectedType` or the implicit default determine the auth type. Qwen OAuth and OpenAI are the only auth types surfaced without extra configuration.
 
@@ -469,7 +485,7 @@ The following fields are treated as atomic objects - provider values completely
 
 ### Example
 
-```json
+```jsonc
 // User settings (~/.qwen/settings.json)
 {
   "model": {
@@ -483,14 +499,17 @@ The following fields are treated as atomic objects - provider values completely
 // modelProviders configuration
 {
   "modelProviders": {
-    "openai": [{
-      "id": "gpt-4o",
-      "envKey": "OPENAI_API_KEY",
-      "generationConfig": {
-        "timeout": 60000,
-        "samplingParams": { "temperature": 0.2 }
-      }
-    }]
+    "openai": {
+      "protocol": "openai",
+      "models": [{
+        "id": "gpt-4o",
+        "envKey": "OPENAI_API_KEY",
+        "generationConfig": {
+          "timeout": 60000,
+          "samplingParams": { "temperature": 0.2 }
+        }
+      }]
+    }
   }
 }
 ```
@@ -516,22 +535,25 @@ The optional `reasoning` field under `generationConfig` controls how aggressivel
 ```jsonc
 {
   "modelProviders": {
-    "openai": [
-      {
-        "id": "deepseek-v4-pro",
-        "name": "DeepSeek V4 Pro",
-        "baseUrl": "https://api.deepseek.com/v1",
-        "envKey": "DEEPSEEK_API_KEY",
-        "generationConfig": {
-          // The four-tier scale:
-          //   'low'    | 'medium' — server-mapped to 'high' on DeepSeek
-          //   'high'   — default reasoning intensity
-          //   'max'    — DeepSeek-specific extra-strong tier
-          // Or set `false` to disable reasoning entirely.
-          "reasoning": { "effort": "max" },
+    "openai": {
+      "protocol": "openai",
+      "models": [
+        {
+          "id": "deepseek-v4-pro",
+          "name": "DeepSeek V4 Pro",
+          "baseUrl": "https://api.deepseek.com/v1",
+          "envKey": "DEEPSEEK_API_KEY",
+          "generationConfig": {
+            // The four-tier scale:
+            //   'low'    | 'medium' — server-mapped to 'high' on DeepSeek
+            //   'high'   — default reasoning intensity
+            //   'max'    — DeepSeek-specific extra-strong tier
+            // Or set `false` to disable reasoning entirely.
+            "reasoning": { "effort": "max" },
+          },
         },
-      },
-    ],
+      ],
+    },
   },
 }
 ```
@@ -598,7 +620,7 @@ When you configure a model without using `modelProviders`, Qwen Code automatical
 
 ```bash
 # This creates a RuntimeModelSnapshot with ID: $runtime|openai|my-custom-model
-qwen --auth-type openai --model my-custom-model --openaiApiKey $KEY --openaiBaseUrl https://api.example.com/v1
+qwen --auth-type openai --model my-custom-model --openai-api-key $KEY --openai-base-url https://api.example.com/v1
 ```
 
 The snapshot: