diff --git a/docs/users/configuration/_meta.ts b/docs/users/configuration/_meta.ts index af332d49620..f5ce7e54de2 100644 --- a/docs/users/configuration/_meta.ts +++ b/docs/users/configuration/_meta.ts @@ -1,6 +1,7 @@ export default { settings: 'Settings', auth: 'Authentication', + 'model-providers': 'Model Providers', 'qwen-ignore': 'Ignoring Files', 'trusted-folders': 'Trusted Folders', themes: 'Themes', diff --git a/docs/users/configuration/auth.md b/docs/users/configuration/auth.md index f037d6e14f8..9c2cffafffd 100644 --- a/docs/users/configuration/auth.md +++ b/docs/users/configuration/auth.md @@ -1,10 +1,14 @@ # Authentication -Qwen Code supports three authentication methods. Pick the one that matches how you want to run the CLI: +Qwen Code's first-run `/auth` menu has three top-level options. Pick the one that matches how you want to run the CLI: -- **Qwen OAuth**: sign in with your `qwen.ai` account in a browser. **Free tier discontinued on 2026-04-15** — switch to another method. -- **Alibaba Cloud Coding Plan**: use an API key from Alibaba Cloud. Paid subscription with diverse model options and higher quotas. -- **API Key**: bring your own API key. Flexible to your own needs — supports OpenAI, Anthropic, Gemini, and other compatible endpoints. +- **Alibaba ModelStudio**: official recommended setup. Opens a sub-menu with **Coding Plan** (for individual developers · weekly quota included), **Token Plan** (for teams and companies · usage-based billing with a dedicated endpoint), or **Standard API Key** (connect with an existing ModelStudio API key). +- **Third-party Providers**: choose a built-in provider and connect with an API key (DeepSeek, MiniMax, Z.AI, Idealab, ModelScope, OpenRouter, Requesty). +- **Custom Provider**: manually connect a local server, proxy, or unsupported provider — supports OpenAI, Anthropic, Gemini, and other compatible endpoints. + +> [!note] +> +> **Qwen OAuth** is no longer a selectable dialog entry — its free tier was discontinued on 2026-04-15. It remains documented below as a hard-coded, discontinued provider only. ## Option 1: Qwen OAuth (Discontinued) @@ -23,7 +27,7 @@ Start the CLI and follow the browser flow: qwen ``` -Then run `/auth` and choose the OAuth provider from the interactive dialog. +Qwen OAuth is no longer offered as a selectable entry in the `/auth` dialog; run `/auth` and choose one of the current options (Alibaba ModelStudio, Third-party Providers, or Custom Provider) instead. > [!note] > @@ -48,7 +52,7 @@ Alibaba Cloud Coding Plan is available in two regions: ### Interactive setup -Enter `qwen` in the terminal to launch Qwen Code, then run the `/auth` command and select **Alibaba Cloud Coding Plan**. Choose your region, then enter your `sk-sp-xxxxxxxxx` key. +Enter `qwen` in the terminal to launch Qwen Code, then run the `/auth` command, select **Alibaba ModelStudio**, and choose **Coding Plan** from the sub-menu. Choose your region, then enter your `sk-sp-xxxxxxxxx` key. After authentication, use the `/model` command to switch between all Alibaba Cloud Coding Plan supported models (including qwen3.5-plus, qwen3.6-plus, qwen3.7-plus, qwen3-coder-plus, qwen3-coder-next, qwen3-max-2026-01-23, glm-5, glm-4.7, kimi-k2.5, and MiniMax-M2.5). @@ -71,15 +75,18 @@ If you prefer to skip the interactive `/auth` flow, add the following to `~/.qwe ```json { "modelProviders": { - "openai": [ - { - "id": "qwen3-coder-plus", - "name": "qwen3-coder-plus (Coding Plan)", - "baseUrl": "https://coding.dashscope.aliyuncs.com/v1", - "description": "qwen3-coder-plus from Alibaba Cloud Coding Plan", - "envKey": "BAILIAN_CODING_PLAN_API_KEY" - } - ] + "openai": { + "protocol": "openai", + "models": [ + { + "id": "qwen3-coder-plus", + "name": "qwen3-coder-plus (Coding Plan)", + "baseUrl": "https://coding.dashscope.aliyuncs.com/v1", + "description": "qwen3-coder-plus from Alibaba Cloud Coding Plan", + "envKey": "BAILIAN_CODING_PLAN_API_KEY" + } + ] + } }, "env": { "BAILIAN_CODING_PLAN_API_KEY": "sk-sp-xxxxxxxxx" @@ -110,15 +117,18 @@ The simplest way to get started with API Key authentication is to put everything ```json { "modelProviders": { - "openai": [ - { - "id": "qwen3-coder-plus", - "name": "qwen3-coder-plus", - "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1", - "description": "Qwen3-Coder via Dashscope", - "envKey": "DASHSCOPE_API_KEY" - } - ] + "openai": { + "protocol": "openai", + "models": [ + { + "id": "qwen3-coder-plus", + "name": "qwen3-coder-plus", + "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1", + "description": "Qwen3-Coder via Dashscope", + "envKey": "DASHSCOPE_API_KEY" + } + ] + } }, "env": { "DASHSCOPE_API_KEY": "sk-xxxxxxxxxxxxx" @@ -158,10 +168,11 @@ The key concept is **Model Providers** (`modelProviders`): Qwen Code supports mu | OpenAI-compatible | `openai` | `OPENAI_API_KEY`, `OPENAI_BASE_URL`, `OPENAI_MODEL` | OpenAI, Azure OpenAI, OpenRouter, Requesty, ModelScope, Alibaba Cloud, any OpenAI-compatible endpoint | | Anthropic | `anthropic` | `ANTHROPIC_API_KEY`, `ANTHROPIC_BASE_URL`, `ANTHROPIC_MODEL` | Anthropic Claude | | Google GenAI | `gemini` | `GEMINI_API_KEY`, `GEMINI_MODEL` | Google Gemini | +| Vertex AI | `vertex-ai` | `GOOGLE_API_KEY`, `GOOGLE_MODEL` (sets `GOOGLE_GENAI_USE_VERTEXAI=true`; uses the `gemini` protocol) | Google Vertex AI | #### Step 1: Configure models and providers in `~/.qwen/settings.json` -Define which models are available for each protocol. Each model entry requires at minimum an `id` and an `envKey` (the environment variable name that holds your API key). +Define which models are available for each protocol. Each model entry requires at minimum an `id`; `envKey` (the environment variable name that holds your API key) is optional and recommended — when omitted, it falls back to the auth type's default env key (e.g. `OPENAI_API_KEY` for `openai`). > [!important] > @@ -172,28 +183,37 @@ Edit `~/.qwen/settings.json` (create it if it doesn't exist). You can mix multip ```json { "modelProviders": { - "openai": [ - { - "id": "gpt-4o", - "name": "GPT-4o", - "envKey": "OPENAI_API_KEY", - "baseUrl": "https://api.openai.com/v1" - } - ], - "anthropic": [ - { - "id": "claude-sonnet-4-20250514", - "name": "Claude Sonnet 4", - "envKey": "ANTHROPIC_API_KEY" - } - ], - "gemini": [ - { - "id": "gemini-2.5-pro", - "name": "Gemini 2.5 Pro", - "envKey": "GEMINI_API_KEY" - } - ] + "openai": { + "protocol": "openai", + "models": [ + { + "id": "gpt-4o", + "name": "GPT-4o", + "envKey": "OPENAI_API_KEY", + "baseUrl": "https://api.openai.com/v1" + } + ] + }, + "anthropic": { + "protocol": "anthropic", + "models": [ + { + "id": "claude-sonnet-4-20250514", + "name": "Claude Sonnet 4", + "envKey": "ANTHROPIC_API_KEY" + } + ] + }, + "gemini": { + "protocol": "gemini", + "models": [ + { + "id": "gemini-2.5-pro", + "name": "Gemini 2.5 Pro", + "envKey": "GEMINI_API_KEY" + } + ] + } } } ``` @@ -208,7 +228,7 @@ Edit `~/.qwen/settings.json` (create it if it doesn't exist). You can mix multip | ------------------ | -------- | -------------------------------------------------------------------- | | `id` | Yes | Model ID sent to the API (e.g. `gpt-4o`, `claude-sonnet-4-20250514`) | | `name` | No | Display name in the `/model` picker (defaults to `id`) | -| `envKey` | Yes | Environment variable name for the API key (e.g. `OPENAI_API_KEY`) | +| `envKey` | No | Environment variable name for the API key (e.g. `OPENAI_API_KEY`); optional/recommended — defaults to the auth type's default env key when omitted | | `baseUrl` | No | API endpoint override (useful for proxies or custom endpoints) | | `generationConfig` | No | Fine-tune `timeout`, `maxRetries`, `samplingParams`, etc. | diff --git a/docs/users/configuration/model-providers.md b/docs/users/configuration/model-providers.md index 73e9bece41e..51271719918 100644 --- a/docs/users/configuration/model-providers.md +++ b/docs/users/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**: - **International**: 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: diff --git a/docs/users/configuration/settings.md b/docs/users/configuration/settings.md index 28b687f83f5..b108329cb01 100644 --- a/docs/users/configuration/settings.md +++ b/docs/users/configuration/settings.md @@ -88,12 +88,16 @@ Settings are organized into categories. Most settings should be placed within th | `general.gitCoAuthor.pr` | boolean | Append a Qwen Code attribution line to pull request descriptions when running `gh pr create`. | `true` | | `general.defaultFileEncoding` | string | Default encoding for new files. Use `"utf-8"` (default) for UTF-8 without BOM, or `"utf-8-bom"` for UTF-8 with BOM. Only change this if your project specifically requires BOM. | `"utf-8"` | | `general.cleanupPeriodDays` | number | Days to retain `~/.qwen/file-history/` session backups used by `/rewind`. Backups older than this are removed by a background pass that runs at most once per day. `0` = minimum retention (~1 hour): keeps sessions touched in the last hour plus the currently active one. Changes take effect after restart. | `30` | +| `general.language` | enum | Language for the user interface. Use `"auto"` to detect from system settings, or a language code (e.g. `"zh-CN"`, `"fr"`). Custom codes can be added by placing JS locale files in `~/.qwen/locales/`. See [i18n](../features/language). Requires restart. | `"auto"` | +| `general.outputLanguage` | string | Language for model output. Use `"auto"` to detect from system settings, or set a specific language. Requires restart. | `"auto"` | +| `general.dynamicCommandTranslation` | boolean | Enable AI translation of dynamic slash-command descriptions. When disabled, dynamic commands keep their original descriptions and skip translation model calls. | `false` | #### output | Setting | Type | Description | Default | Possible Values | | --------------- | ------ | ----------------------------- | -------- | ------------------ | -| `output.format` | string | The format of the CLI output. | `"text"` | `"text"`, `"json"` | +| `output.format` | string | The format of the CLI output. | `"text"` | `"text"`, `"json"` | +| `output.showTimestamps` | boolean | Show an `[HH:MM:SS]` timestamp before each assistant response. | `false` | | #### ui @@ -122,7 +126,6 @@ Settings are organized into categories. Most settings should be placed within th | `ui.enableFollowupSuggestions` | boolean | Enable [followup suggestions](../features/followup-suggestions) that predict what you want to type next after the model responds. Suggestions appear as placeholder text and are accepted with Tab, Enter, or Right Arrow (which fill the input — they do not auto-submit). On by default; set to `false` to opt out. | `true` | | `ui.enableCacheSharing` | boolean | Use cache-aware forked queries for suggestion generation. Reduces cost on providers that support prefix caching (experimental). | `true` | | `ui.enableSpeculation` | boolean | Speculatively execute accepted suggestions before submission. Results appear instantly when you accept (experimental). | `false` | -| `experimental.emitToolUseSummaries` | boolean | Generate short LLM-based labels summarizing each tool-call batch. See [Tool-Use Summaries](../features/tool-use-summaries). Requires `fastModel` to be configured; silently skipped otherwise. Can be overridden per-session with `QWEN_CODE_EMIT_TOOL_USE_SUMMARIES=0` or `=1`. | `true` | #### ide @@ -459,6 +462,19 @@ LSP server configuration is done through `.lsp.json` files in your project root | `advanced.bugCommand` | object | Configuration for the bug report command. Overrides the default URL for the `/bug` command. Properties: `urlTemplate` (string): A URL that can contain `{title}` and `{info}` placeholders. Example: `"bugCommand": { "urlTemplate": "https://bug.example.com/new?title={title}&info={info}" }` | `undefined` | | `plansDirectory` | string | Custom directory for approved Plan Mode files. Relative paths are resolved from the project root, and the resolved path must stay within the project root. If unset, plan files are stored in `~/.qwen/plans`. **Requires restart.** If the directory is inside the project root, add it to `.gitignore` to avoid committing plan files. | `undefined` | +#### experimental + +> [!warning] +> +> **Experimental features.** These toggles gate in-development capabilities and may change or be removed in future releases. + +| Setting | Type | Description | Default | +| ----------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | +| `experimental.cron` | boolean | Enable in-session cron/loop tools (`cron_create`, `cron_list`, `cron_delete`) so the model can create recurring prompts. Can be disabled via the `QWEN_CODE_DISABLE_CRON=1` environment variable. Requires restart. | `true` | +| `experimental.agentTeam` | boolean | Enable agent-team collaboration tools (`team_create`, `task_create`, `task_update`, `send_message`, etc.) for multi-agent coordination. Can also be enabled via `QWEN_CODE_ENABLE_AGENT_TEAM=1`. Requires restart. | `false` | +| `experimental.artifact` | boolean | Enable the Artifact tool, letting the model publish a self-contained HTML page and open it in the browser. Interactive, non-SDK sessions only. Toggle via `QWEN_CODE_ENABLE_ARTIFACT=1` / `QWEN_CODE_DISABLE_ARTIFACT=1`. Requires restart. | `false` | +| `experimental.emitToolUseSummaries` | boolean | Generate a short LLM-based label after each tool-call batch completes. See [Tool-Use Summaries](../features/tool-use-summaries). Requires a fast model to be configured (`fastModel`); silently skipped otherwise. Can be overridden per-session with `QWEN_CODE_EMIT_TOOL_USE_SUMMARIES=0` or `=1`. | `true` | + #### mcpServers Configures connections to one or more Model-Context Protocol (MCP) servers for discovering and using custom tools. Qwen Code attempts to connect to each configured MCP server to discover available tools. If multiple MCP servers expose a tool with the same name, the tool names will be prefixed with the server alias you defined in the configuration (e.g., `serverAlias__actualToolName`) to avoid conflicts. Note that the system might strip certain schema properties from MCP tool definitions for compatibility. At least one of `command`, `url`, or `httpUrl` must be provided. If multiple are specified, the order of precedence is `httpUrl`, then `url`, then `command`. diff --git a/docs/users/features/commands.md b/docs/users/features/commands.md index 393c6211a4a..52baa685b2f 100644 --- a/docs/users/features/commands.md +++ b/docs/users/features/commands.md @@ -43,10 +43,13 @@ Commands for adjusting interface appearance and work environment. | `/clear` | Clear terminal screen content | `/clear` (shortcut: `Ctrl+L`) | | `/context` | Show context window usage breakdown | `/context` | | → `detail` | Show per-item context usage breakdown | `/context detail` | +| `/history` | Control history display preferences and visibility | `/history collapse-on-resume`, `/history expand-on-resume`, `/history expand-now` | | `/diff` | Open an interactive diff viewer showing uncommitted changes and per-turn diffs. Use ←/→ to switch between current git diff and individual conversation turns, ↑/↓ to browse files | `/diff` | | `/theme` | Change Qwen Code visual theme | `/theme` | | `/vim` | Turn input area Vim editing mode on/off | `/vim` | +| `/voice` | Toggle voice dictation input | `/voice`, `/voice status` | | `/directory` | Manage multi-directory support workspace | `/dir add ./src,./tests` | +| `/cd` | Move this session to a new working directory | `/cd ../other-project` | | `/editor` | Open dialog to select supported editor | `/editor` | | `/statusline` | Open interactive [status line](./status-line.md) preset dialog | `/statusline` | | `/statusline ` | Generate a command-mode [status line](./status-line.md) via agent | `/statusline show model and git branch` | @@ -72,6 +75,7 @@ Commands for managing AI tools and models. | Command | Description | Usage Examples | | ---------------- | --------------------------------------------- | --------------------------------------------- | | `/mcp` | List configured MCP servers and tools | `/mcp`, `/mcp desc` | +| `/import-config` | Import MCP servers from Claude configs | `/import-config claude-code`, `/import-config claude-desktop --scope project` | | `/tools` | Display currently available tool list | `/tools`, `/tools desc` | | `/skills` | List and run available skills | `/skills`, `/skills ` | | `/plan` | Switch to plan mode or exit plan mode | `/plan`, `/plan `, `/plan exit` | @@ -81,8 +85,9 @@ Commands for managing AI tools and models. | →`auto-edit` | Automatically approve edits | Trusted environment | | →`auto` | Classifier-evaluated approval | Autonomous sessions with safety guardrails | | →`yolo` | Automatically approve all | Quick prototyping | -| `/model` | Switch model used in current session | `/model` | +| `/model` | Switch model used in current session | `/model`, `/model ` (switch immediately) | | `/model --fast` | Set a lighter model for prompt suggestions | `/model --fast qwen3-coder-flash` | +| `/model --voice` | Set the model used for voice transcription | `/model --voice ` | | `/extensions` | List all active extensions in current session | `/extensions` | | `/memory` | Open the Memory Manager dialog | `/memory` | | `/remember` | Save a durable memory | `/remember Prefer terse responses` | diff --git a/docs/users/overview.md b/docs/users/overview.md index c9ed58196cd..367cef2b6ef 100644 --- a/docs/users/overview.md +++ b/docs/users/overview.md @@ -40,7 +40,7 @@ cd your-project qwen ``` -Choose your authentication method — **API Key** or **[Alibaba Cloud Coding Plan](https://bailian.console.aliyun.com/cn-beijing/?tab=coding-plan#/efm/coding-plan-index)** ([intl](https://modelstudio.console.alibabacloud.com/?tab=coding-plan#/efm/coding-plan-index)) — and follow the prompts to configure. See the API setup guide ([Beijing](https://bailian.console.aliyun.com/cn-beijing/?tab=doc#/doc/?type=model&url=3023091) / [intl](https://modelstudio.console.alibabacloud.com/ap-southeast-1?tab=doc#/doc/?type=model&url=2974721)) for step-by-step instructions. Then let's start with understanding your codebase. Try one of these commands: +On first launch you'll be prompted to connect a model provider. The menu offers **Alibaba ModelStudio** (Coding Plan, Token Plan, or Standard API Key), **Third-party Providers** (built-in providers such as DeepSeek, MiniMax, Z.AI, and OpenRouter, connected with an API key), and **Custom Provider** (a local server, proxy, or unsupported provider). For the [Alibaba Cloud Coding Plan](https://bailian.console.aliyun.com/cn-beijing/?tab=coding-plan#/efm/coding-plan-index) ([intl](https://modelstudio.console.alibabacloud.com/?tab=coding-plan#/efm/coding-plan-index)), choose **Alibaba ModelStudio → Coding Plan**; to use a ModelStudio API key, choose **Alibaba ModelStudio → Standard API Key** and follow the API setup guide ([Beijing](https://bailian.console.aliyun.com/cn-beijing/?tab=doc#/doc/?type=model&url=3023091) / [intl](https://modelstudio.console.alibabacloud.com/ap-southeast-1?tab=doc#/doc/?type=model&url=2974721)). Then let's start with understanding your codebase. Try one of these commands: ``` what does this project do? diff --git a/docs/users/quickstart.md b/docs/users/quickstart.md index 10bc4da31f3..83896f5f36f 100644 --- a/docs/users/quickstart.md +++ b/docs/users/quickstart.md @@ -10,7 +10,7 @@ Make sure you have: - A **terminal** or command prompt open - A code project to work with -- An API key from Alibaba Cloud Model Studio ([Beijing](https://bailian.console.aliyun.com/) / [intl](https://modelstudio.console.alibabacloud.com/)), or an Alibaba Cloud Coding Plan ([Beijing](https://bailian.console.aliyun.com/cn-beijing/?tab=coding-plan#/efm/coding-plan-index) / [intl](https://modelstudio.console.alibabacloud.com/?tab=coding-plan#/efm/coding-plan-index)) subscription +- An API key from Alibaba Cloud ModelStudio ([Beijing](https://bailian.console.aliyun.com/) / [intl](https://modelstudio.console.alibabacloud.com/)), or an Alibaba Cloud Coding Plan ([Beijing](https://bailian.console.aliyun.com/cn-beijing/?tab=coding-plan#/efm/coding-plan-index) / [intl](https://modelstudio.console.alibabacloud.com/?tab=coding-plan#/efm/coding-plan-index)) subscription ## Step 1: Install Qwen Code @@ -66,10 +66,14 @@ qwen /auth ``` -Choose your preferred authentication method: +The first-run menu lets you connect a model provider. Choose one of: -- **Alibaba Cloud Coding Plan**: Select `Alibaba Cloud Coding Plan` for a fixed monthly fee with diverse model options. See the [Coding Plan guide](https://bailian.console.aliyun.com/cn-beijing/?tab=coding-plan#/efm/coding-plan-index) ([intl](https://modelstudio.console.alibabacloud.com/?tab=coding-plan#/efm/coding-plan-index)) for setup instructions. -- **API Key**: Select `API Key`, then enter your API key from Alibaba Cloud Model Studio ([Beijing](https://bailian.console.aliyun.com/) / [intl](https://modelstudio.console.alibabacloud.com/)). See the API setup guide ([Beijing](https://bailian.console.aliyun.com/cn-beijing/?tab=doc#/doc/?type=model&url=3023091) / [intl](https://modelstudio.console.alibabacloud.com/ap-southeast-1?tab=doc#/doc/?type=model&url=2974721)) for details. +- **Alibaba ModelStudio** — the recommended setup. Opens a sub-menu: + - **Coding Plan**: for individual developers, with an included weekly quota and diverse model options. See the [Coding Plan guide](https://bailian.console.aliyun.com/cn-beijing/?tab=coding-plan#/efm/coding-plan-index) ([intl](https://modelstudio.console.alibabacloud.com/?tab=coding-plan#/efm/coding-plan-index)) for setup instructions. + - **Token Plan**: usage-based billing with a dedicated endpoint, aimed at teams and companies. + - **Standard API Key**: connect with an existing API key from Alibaba Cloud ModelStudio ([Beijing](https://bailian.console.aliyun.com/) / [intl](https://modelstudio.console.alibabacloud.com/)). See the API setup guide ([Beijing](https://bailian.console.aliyun.com/cn-beijing/?tab=doc#/doc/?type=model&url=3023091) / [intl](https://modelstudio.console.alibabacloud.com/ap-southeast-1?tab=doc#/doc/?type=model&url=2974721)) for details. +- **Third-party Providers** — choose a built-in provider (DeepSeek, MiniMax, Z.AI, ModelScope, OpenRouter, Requesty, and more) and connect with an API key. +- **Custom Provider** — manually connect a local server, proxy, or unsupported provider. > ⚠️ **Note**: Qwen OAuth was discontinued on April 15, 2026. If you were previously using Qwen OAuth, please switch to one of the methods above. @@ -86,7 +90,7 @@ Choose your preferred authentication method: Open your terminal in any project directory and start Qwen Code: ```bash -# optiona +# optional cd /path/to/your/project # start qwen qwen diff --git a/packages/core/src/skills/bundled/qc-helper/SKILL.md b/packages/core/src/skills/bundled/qc-helper/SKILL.md index e825fd58603..987497fc220 100644 --- a/packages/core/src/skills/bundled/qc-helper/SKILL.md +++ b/packages/core/src/skills/bundled/qc-helper/SKILL.md @@ -61,11 +61,19 @@ Use this index to locate the right document for the user's question. Load only t | Headless / non-interactive mode | `docs/features/headless.md` | | LSP integration | `docs/features/lsp.md` | | Token caching | `docs/features/token-caching.md` | -| Language / i18n | `docs/features/language.md` | -| Arena mode | `docs/features/arena.md` | -| Status line | `docs/features/status-line.md` | -| Scheduled tasks (cron/loop) | `docs/features/scheduled-tasks.md` | -| Worktree | `docs/features/worktree.md` | +| Language / i18n | `docs/features/language.md` | +| Arena mode | `docs/features/arena.md` | +| Status line | `docs/features/status-line.md` | +| Scheduled tasks (cron/loop) | `docs/features/scheduled-tasks.md` | +| Worktree | `docs/features/worktree.md` | +| Code review (`/review`) | `docs/features/code-review.md` | +| Structured output (JSON schema) | `docs/features/structured-output.md` | +| Dual output | `docs/features/dual-output.md` | +| Tool-use summaries | `docs/features/tool-use-summaries.md` | +| Followup suggestions | `docs/features/followup-suggestions.md` | +| Markdown rendering | `docs/features/markdown-rendering.md` | +| Contextual tips | `docs/features/tips.md` | +| Channels (Telegram/WeChat/DingTalk/etc.) | `docs/features/channels/overview.md` | ### IDE Integration