Model Providers

Qwen Code allows you to configure multiple model providers through the modelProviders setting in your settings.json. This enables you to switch between different AI models and providers using the /model command.

Overview

Use modelProviders to declare models per provider id that the /model picker can switch between. Each key is a provider id and its value is an array of model definitions (ModelConfig[]). For built-in providers the key must be a valid auth type (openai, anthropic, gemini, vertex-ai); a custom provider id (e.g. idealab) is allowed as long as you map it to a protocol via the top-level providerProtocol setting. Each model entry 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.

Image generation routes

Set supportsImageGeneration: true when a route can be used by the built-in image_gen tool. This capability is independent from image input support such as capabilities.vision or generationConfig.modalities.image.

Use imageOnly: true when the route is dedicated to image generation and must not appear in ordinary model selectors. For backward compatibility, imageOnly: true also implies image-generation capability, so existing settings do not need to be migrated.

A dual-role route can be selected both as the main model and through /model --image:

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

A dedicated image route sets both fields. The legacy form with only imageOnly: true remains valid:

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

The selected route must declare an explicit HTTPS baseUrl and a non-empty envKey. Image generation uses the same endpoint and credential as the route; if chat and image generation require different endpoints or credentials, configure two routes instead.

Override reasoning capabilities

Set capabilities.reasoning on a model entry to override its reasoning format, offered effort tiers and default. Known models inherit omitted fields from the provider catalog at the selected endpoint; for example, "capabilities": { "reasoning": { "defaultEffort": "medium" } } makes a DashScope qwen3.8-max route use medium when no explicit effort is selected. For an unknown alias, declare all three fields:

{
  "id": "company-model-v2",
  "baseUrl": "https://gateway.example.com/v1",
  "envKey": "COMPANY_MODEL_API_KEY",
  "capabilities": {
    "reasoning": {
      "profile": "openai-effort",
      "efforts": ["low", "medium", "high"],
      "defaultEffort": "medium"
    }
  }
}

efforts replaces the supported subset of low/medium/high/xhigh/max. An explicit default must belong to that subset. Profiles reuse existing formats: Chat accepts openai-effort, openai-reasoning, deepseek-openai, dashscope-effort, dashscope-thinking and qwen-chat-template; Responses accepts openai-reasoning; Anthropic accepts anthropic-manual, anthropic-adaptive and deepseek-anthropic; Gemini/Vertex uses gemini. The two toggle-only profiles omit efforts and defaultEffort. Gemini uses low/medium/high. An adaptive profile selects adaptive thinking even when a legacy manual budget is configured. Existing complete capability declarations continue to work.

Reasoning changes apply before the next user prompt. Its requests, retries and child agents share the captured reasoning configuration. Invalid updates retain the previous configuration and log the model/field error. Invalid declarations in fresh sessions safely fall back to the existing model behavior. Explicit user choices and provider-native overrides in reasoning, samplingParams and extra_body retain their existing precedence; a model default is not saved as a user choice. This mechanism does not change endpoint, credential or image-model lifecycles.

Configuration Examples by Auth Type

Below are comprehensive configuration examples for different authentication types, showing the available parameters and their combinations.

Supported Auth Types

Use one of the built-in provider ids below, or map a custom id with providerProtocol:

[!note] Vertex AI entries can authenticate with Application Default Credentials. Set GOOGLE_CLOUD_PROJECT (and optionally GOOGLE_CLOUD_LOCATION, which defaults to global) and leave envKey unset, along with every other key source the resolver reads: GOOGLE_API_KEY, settings.security.auth.apiKey, and the CLI key flags. Any API key value that reaches a Vertex entry switches the Google SDK to Vertex Express mode, which ignores the project, the location and your ADC credentials. An entry that declares an envKey is never routed to ADC, so a key that fails to be injected keeps failing on that variable instead of silently authenticating as a different principal.

[!warning] A provider id that is neither a built-in protocol nor mapped via providerProtocol (e.g. a typo like "openai-custom") cannot be routed, so its whole entry is skipped with a warning — its models simply won’t appear in the /model picker. Use one of the supported auth type values above for built-in providers, or add a providerProtocol mapping for a custom id.

Custom provider ids (providerProtocol)

Built-in provider ids (openai, gemini, anthropic, vertex-ai, qwen-oauth) are routed to their SDK protocol automatically. To use a custom provider id — for example to group several OpenAI-compatible endpoints under a friendlier name — declare it under modelProviders and map it to a built-in protocol with the top-level providerProtocol setting:

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

Without a matching providerProtocol entry, a custom provider id is skipped (see the warning above).

Selecting the OpenAI API

Set wireApi beside id, envKey, and baseUrl on an OpenAI-compatible model:

{
  "modelProviders": {
    "openai": [
      {
        "id": "my-model",
        "wireApi": "responses",
        "envKey": "OPENAI_API_KEY",
        "baseUrl": "https://api.openai.com/v1"
      }
    ]
  },
  "security": { "auth": { "selectedType": "openai" } },
  "model": { "name": "my-model" }
}

The supported values are chat-completions and responses. Omitting wireApi uses Chat Completions for openai, including custom providers mapped to openai. Other values, or wireApi on an Anthropic, Gemini, Vertex AI, or Qwen OAuth model, are configuration errors.

Use openai with per-model wireApi for new configurations. The modelProviders.openai-responses format and providerProtocol mappings to openai-responses released in v0.23.3 remain readable. Explicit provider mappings take precedence over bucket names; explicit wireApi takes precedence over either OpenAI protocol. Loading does not rewrite settings or change credential references. Reconfiguration writes the selected routes in the new format and removes only their matching old entries in the writable scope; entries under a provider id that contains a dot are left in place, and unrelated models, endpoints, APIs and scopes remain unchanged. api is not an alias for wireApi.

wireApi is local routing metadata; it does not belong in generationConfig or extra_body and is not sent in the request body. New custom setup shares one credential slot for the same OpenAI endpoint across both APIs, so rotating that key updates both routes. Manually configured models can use distinct explicit envKey references when independent credentials are needed. In /auth → Custom Provider, select OpenAI-compatible and then the API format.

At startup, selectedType: "openai" can resolve a model explicitly configured with wireApi: "responses" when there is no matching Chat route at the selected configured endpoint. The model picker and recorded sessions retain the effective protocol (openai or openai-responses) so both routes can be selected and resumed independently. No endpoint detection or automatic fallback occurs when an API request fails.

Transports Used for API Requests

The effective model protocol determines the transport. Both OpenAI APIs use the openai provider group; wireApi selects Chat Completions or Responses:

This means the baseUrl you configure should be compatible with the corresponding transport’s expected API format. For example, wireApi: "responses" requires a Responses-compatible endpoint.

OpenAI-compatible providers (openai)

This auth type supports not only OpenAI’s official API but also any OpenAI-compatible endpoint, including aggregated model providers like OpenRouter and 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
          }
        }
      }
    ]
  }
}

When pointing an entry at a hosted OpenAI-compatible gateway, set baseUrl to the API’s /v1 root (for example, https://gateway.example.com/v1) rather than the full /v1/chat/completions path — the SDK appends the request path itself.

OpenAI Responses API (openai-responses)

Use openai with wireApi: "responses" to target OpenAI’s /v1/responses endpoint. When the endpoint returns encrypted reasoning with visible thought text, it replays prior-turn reasoning across turns and --resume via reasoning.encrypted_content. Compatible endpoints that stream response.reasoning_text.delta also display their reasoning, but endpoints without encrypted_content cannot replay the opaque reasoning state. Use reasoning.effort (not extra_body.enable_thinking, which the Chat Completions wires use) to control reasoning intensity.

{
  "env": {
    "OPENAI_API_KEY": "sk-your-actual-openai-key-here"
  },
  "modelProviders": {
    "openai": [
      {
        "id": "gpt-5.1",
        "wireApi": "responses",
        "name": "GPT-5.1 (Responses API)",
        "envKey": "OPENAI_API_KEY",
        "baseUrl": "https://api.openai.com/v1",
        "generationConfig": {
          "timeout": 60000,
          "reasoning": {
            "effort": "high"
          },
          "samplingParams": {
            "temperature": 0.7,
            "max_tokens": 4096
          }
        }
      }
    ]
  }
}

[!note] extra_body on this wire is fill-only: a key is written to the request body only when the generated request has no value for it, so it cannot override a field the pipeline already set (model, input, reasoning, temperature, max_output_tokens, …). The legacy enable_thinking key is the one exception to even that — it is removed rather than forwarded (it isn’t a Responses API field), and translated into reasoning.effort: "medium" when no explicit reasoning is set. Set reasoning.effort directly instead of extra_body.enable_thinking for this provider.

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
          }
        }
      }
    ]
  }
}

For a vision model that can also follow the normal Qwen Code agent policy and use tools, opt in to full-turn image routing with both capabilities:

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

When a text-only primary uses that model as its configured vision fallback, the complete image-bearing turn stays on that exact provider, model, and endpoint across tool calls and retries. The next independent turn returns to the primary, and each model request receives only media modalities supported by its target. Omit agent (or set it to false) to keep the safer Vision Bridge transcription flow.

Local Self-Hosted Models (via OpenAI-compatible API)

Most local inference servers (vLLM, Ollama, LM Studio, etc.) provide an OpenAI-compatible API endpoint. Configure them using the openai auth type with a local 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
          }
        }
      }
    ]
  }
}

For queued or slow local OpenAI-compatible servers, streamIdleTimeoutMs controls how long this model may stay silent between streamed chunks. It overrides the global QWEN_STREAM_IDLE_TIMEOUT_MS value for the selected provider entry; set it to 0 to disable the idle guard. The separate 15-minute stream lifetime cap still applies unless QWEN_STREAM_MAX_LIFETIME_MS is raised or disabled.

For local servers that don’t require authentication, you can use any placeholder value for the 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"

Alibaba Cloud Coding Plan

Alibaba Cloud Coding Plan provides a pre-configured set of Qwen models optimized for coding tasks. This feature is available for users with Alibaba Cloud Coding Plan API access and offers a simplified setup experience with automatic model configuration updates.

Overview

When you authenticate with an Alibaba Cloud Coding Plan API key using the /auth command, Qwen Code automatically configures the following models:

Setup

1. Obtain an Alibaba Cloud Coding Plan API key:
   • 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 ModelStudio, then choose Coding Plan from the sub-menu
4. Select your region
5. Enter your API key when prompted

The models will be automatically configured and added to your /model picker.

Regions

Alibaba Cloud Coding Plan supports two regions:

The region is selected during authentication and stored in settings.json under the modelProviders configuration. To switch regions, re-run the /auth command and select a different region.

API Key Storage

When you configure Coding Plan through the /auth command, the API key is stored using the reserved environment variable name BAILIAN_CODING_PLAN_API_KEY. By default, it is stored in the env field of your settings.json file.

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

Automatic Updates

Coding Plan model configurations are versioned. When Qwen Code detects a newer version of the model template, you will be prompted to update. Accepting the update will:

• Replace the existing Coding Plan model configurations with the latest versions
• Preserve any custom model configurations you’ve added manually
• Leave your selected model unchanged; if it is no longer in the updated configuration, use /model to choose a new one

The update process refreshes the model configurations and features without changing your selected model.

Manual Configuration (Advanced)

If you prefer to manually configure Coding Plan models, you can add them to your settings.json like any OpenAI-compatible provider:

{
  "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"
      }
    ]
  }
}

Resolution Layers and Atomicity

The effective auth/model/credential values are chosen per field using the following precedence (first present wins). You can combine --auth-type with --model to point directly at a provider entry; these CLI flags run before other layers.

*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.

Generation Config Layering: The Impermeable Provider Layer

The configuration resolution follows a strict layering model with one crucial rule: the modelProvider layer is impermeable.

How it works

1. When a modelProvider model IS selected (e.g., via /model command choosing a provider-configured model):

   • The entire generationConfig from the provider is applied atomically
   • The provider layer is completely impermeable — lower layers (CLI, env, settings) do not participate in generationConfig resolution at all
   • All fields defined in modelProviders[].generationConfig use the provider’s values
   • All fields not defined by the provider are set to undefined (not inherited from settings)
   • This ensures provider configurations act as a complete, self-contained “sealed package”

   If a model is listed in modelProviders, put all model-specific generation settings for that model in the matching provider entry. Top-level model.generationConfig values, including contextWindowSize, modalities, customHeaders, and extra_body, are ignored for provider models. Configure those fields under modelProviders[authType][].generationConfig for them to apply.

2. When NO modelProvider model is selected (e.g., using --model with a raw model ID, or using CLI/env/settings directly):

   • The resolution falls through to lower layers
   • Fields are populated from CLI → env → settings → defaults
   • This creates a Runtime Model (see next section)

Per-field precedence for generationConfig

Dynamic values in customHeaders

A customHeaders value may contain the placeholder ${session_id}, which is expanded per request with the current Qwen Code session ID. Use it for gateways that require a stable per-conversation identifier — OpenCode Go, for example, rejects requests without x-opencode-session:

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

Because the value is resolved per request rather than baked into the SDK client, /new and /resume rotate it without a restart.

⚠️ Two steps are required. The provider entry above is only half of it — a placeholder is inert until you also switch on outboundCorrelation.allowDynamicHeaderValues:

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

Until you do, a value containing a placeholder is dropped rather than sent, and Qwen Code prints a warning at startup naming the header and this setting. The header is never sent with a literal ${session_id} in it.

The switch is global because it is a consent decision, separate from where the value goes: an expanded value carries live session state to whoever receives it, and the switch controls only whether ${session_id} may be expanded. It does not identify which settings source supplied the header.

Privacy note: the session ID is a stable identifier for the life of a conversation, so any host you send it to can group every request of that conversation. Which hosts those are is decided by which provider entries carry the header — there is no separate host list to keep in sync with your baseUrl.

Atomic field treatment

The following fields are treated as atomic objects - provider values completely replace the entire object, no merging occurs:

• samplingParams - Temperature, top_p, max_tokens, etc.
• customHeaders - Custom HTTP headers (may contain ${session_id}; see Dynamic values)
• extra_body - Extra request body parameters

Example

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

When gpt-4o is selected from modelProviders:

• timeout = 60000 (from provider, overrides settings)
• samplingParams.temperature = 0.2 (from provider, completely replaces settings object)
• samplingParams.max_tokens = undefined (not defined in provider, and provider layer does not inherit from settings — fields are explicitly set to undefined if not provided)

When using a raw model via --model gpt-4 (not from modelProviders, creates a Runtime Model):

• timeout = 30000 (from settings)
• samplingParams.temperature = 0.5 (from settings)
• samplingParams.max_tokens = 1000 (from settings)

The merge strategy for modelProviders itself is REPLACE: the entire modelProviders from project settings will override the corresponding section in user settings, rather than merging the two.

Reasoning / thinking configuration

The optional reasoning field under generationConfig controls how aggressively the model reasons before responding. The Anthropic and Gemini converters always honor it. The OpenAI-compatible pipeline honors it unless generationConfig.samplingParams is set. Known GPT-5 models and GPT-6 Astra are an exception: unrelated sampling keys do not suppress configured effort. See “Interaction with samplingParams” below.

{
  "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" },
        },
      },
    ],
  },
}

Per-provider behavior

reasoning: false

Setting reasoning: false (the literal boolean) explicitly disables thinking on models that support disabling — useful for cheap side queries that don’t benefit from reasoning. This is honored at the request level too via request.config.thinkingConfig.includeThoughts: false for one-off calls (e.g. suggestion generation).

On a api.deepseek.com baseURL, the OpenAI pipeline emits the explicit thinking: { type: 'disabled' } field that DeepSeek V4+ requires — the server-side default is 'enabled', so simply omitting reasoning_effort would still pay thinking latency/cost. Self-hosted DeepSeek backends (sglang/vllm) and other OpenAI-compatible servers do not receive this field; if you need to disable thinking on those, inject thinking: { type: 'disabled' } (or whatever knob your inference framework exposes) via samplingParams/extra_body.

For known GPT models that allow disabling, non-OpenRouter endpoints receive reasoning_effort: 'none'; OpenRouter receives nested reasoning: { enabled: false } instead. Mandatory-thinking models reject off in model controls and omit unsupported disable values from requests, so reasoning: false cannot turn their thinking off. An explicit model reasoning capability takes precedence over the built-in tier list and selects the native disable field; OpenRouter keeps its provider-level disable behavior. The built-in mandatory set is gpt-5, gpt-5-mini, gpt-5-nano, gpt-5-pro, gpt-5.1-codex, gpt-5.1-codex-max, gpt-5.2-codex, gpt-5.3-codex, gpt-5.2-pro, gpt-5.4-pro, gpt-5.5-pro, and gpt-6-astra.

On an openrouter.ai baseURL, the OpenAI pipeline emits OpenRouter’s provider-level reasoning: { enabled: false } field when reasoning is disabled. Mandatory-thinking models do not receive this disable field. Other OpenAI-compatible servers do not automatically receive this OpenRouter-specific field; use their native disable knob.

Interaction with samplingParams (OpenAI-compatible only)

budget_tokens

You can pin an exact thinking-token budget by including budget_tokens alongside effort:

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

For Anthropic this becomes thinking.budget_tokens. For OpenAI/DeepSeek the field is preserved but currently ignored by the server — reasoning_effort is the load-bearing knob.

Provider Models vs Runtime Models

Qwen Code distinguishes between two types of model configurations:

Provider Model

• Defined in modelProviders configuration
• Has a complete, atomic configuration package
• When selected, its configuration is applied as an impermeable layer
• Appears in /model command list with full metadata (name, description, capabilities)
• Recommended for multi-model workflows and team consistency

Runtime Model

• Created dynamically when using raw model IDs via CLI (--model), environment variables, or settings
• Not defined in modelProviders
• Configuration is built by “projecting” through resolution layers (CLI → env → settings → defaults)
• Automatically captured as a RuntimeModelSnapshot when a complete configuration is detected
• Allows reuse without re-entering credentials

RuntimeModelSnapshot lifecycle

When you configure a model without using modelProviders, Qwen Code automatically creates a RuntimeModelSnapshot to preserve your configuration:

# This creates a RuntimeModelSnapshot with ID: $runtime|openai|my-custom-model
qwen --auth-type openai --model my-custom-model --openai-api-key $KEY --openai-base-url https://api.example.com/v1

The snapshot:

• Captures model ID, API key, base URL, and generation config
• Persists across sessions (stored in memory during runtime)
• Appears in the /model command list as a runtime option
• Can be switched to using /model $runtime|openai|my-custom-model

Key differences

When to use each

• Use Provider Models when: You have standard models shared across a team, need consistent configurations, or want to prevent accidental overrides
• Use Runtime Models when: Quickly testing a new model, using temporary credentials, or working with ad-hoc endpoints

Selection Persistence and Recommendations

• /model and /auth persist model.name (where applicable) and security.auth.selectedType to the closest writable scope that already defines modelProviders; otherwise they fall back to the user scope. This keeps workspace/user files in sync with the active provider catalog.
• Without modelProviders, the resolver mixes CLI/env/settings layers, creating Runtime Models. This is fine for single-provider setups but cumbersome when frequently switching. Define provider catalogs whenever multi-model workflows are common so that switches stay atomic, source-attributed, and debuggable.