Model-Provider

Mit Qwen Code kannst du mehrere Model-Provider über die modelProviders-Einstellung in deiner settings.json konfigurieren. So kannst du mit dem /model-Befehl zwischen verschiedenen KI-Modellen und -Providern wechseln.

Übersicht

Verwende modelProviders, um Modelle pro Auth-Typ zu deklarieren, zwischen denen der /model-Picker wechseln kann. Die Keys müssen gültige Auth-Typen sein (openai, anthropic, gemini usw.). Jeder Auth-Typ wird auf ein ProviderConfig-Objekt mit einem protocol-Feld und einem models-Feld (das Array der Modelldefinitionen) gemappt. Jeder Eintrag in models erfordert eine id; envKey ist optional, aber empfohlen (wenn weggelassen, wird auf den Standard-Env-Key des Auth-Typs zurückgegriffen, z. B. OPENAI_API_KEY für openai), zusammen mit den optionalen Feldern name, description, baseUrl und generationConfig. Credentials werden niemals in den Einstellungen gespeichert; die Runtime liest sie aus process.env[envKey]. Qwen OAuth-Modelle bleiben hartcodiert und können nicht überschrieben werden.

Konfigurationsbeispiele nach Auth-Typ

Im Folgenden findest du umfassende Konfigurationsbeispiele für verschiedene Authentifizierungstypen, die die verfügbaren Parameter und ihre Kombinationen zeigen.

Unterstützte Auth-Typen

Die Keys des modelProviders-Objekts müssen gültige authType-Werte sein. Derzeit unterstützte Auth-Typen sind:

[!warning] Wenn ein unbekannter Auth-Typ-Key verwendet wird (z. B. ein Tippfehler wie "openai-custom"), wird ein nicht-leerer Key wie er ist als eigene Auth-Typ-Gruppe akzeptiert, aber er wird nicht auf ein bekanntes Protokoll gemappt – seine Modelle funktionieren also nicht wie beabsichtigt und verhalten sich im /model-Picker nicht korrekt. Nur leere (leere oder nur aus Leerzeichen bestehende) Keys werden übersprungen. Verwende immer einen der oben aufgeführten unterstützten Auth-Typ-Werte.

Für API-Requests verwendete SDKs

Qwen Code verwendet die folgenden offiziellen SDKs, um Requests an jeden Provider zu senden:

Das bedeutet, dass die von dir konfigurierte baseUrl mit dem erwarteten API-Format des entsprechenden SDK kompatibel sein sollte. Wenn du beispielsweise den Auth-Typ openai verwendest, muss der Endpunkt Requests im OpenAI-API-Format akzeptieren.

OpenAI-kompatible Provider (openai)

Dieser Auth-Typ unterstützt nicht nur die offizielle API von OpenAI, sondern auch jeden OpenAI-kompatiblen Endpunkt, einschließlich aggregierter Model-Provider wie OpenRouter und 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": {
      "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": "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
            }
          }
        }
      ]
    }
  }
}

Anthropic (anthropic)

{
  "env": {
    "ANTHROPIC_API_KEY": "sk-ant-your-actual-anthropic-key-here"
  },
  "modelProviders": {
    "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
            }
          }
        }
      ]
    }
  }
}

Google Gemini (gemini)

{
  "env": {
    "GEMINI_API_KEY": "AIza-your-actual-gemini-key-here"
  },
  "modelProviders": {
    "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
            }
          }
        }
      ]
    }
  }
}

Lokale Self-Hosted Models (über OpenAI-kompatible API)

Die meisten lokalen Inference-Server (vLLM, Ollama, LM Studio usw.) bieten einen OpenAI-kompatiblen API-Endpunkt. Konfiguriere sie mit dem Auth-Typ openai und einer lokalen baseUrl:

{
  "env": {
    "OLLAMA_API_KEY": "ollama",
    "VLLM_API_KEY": "not-needed",
    "LMSTUDIO_API_KEY": "lm-studio"
  },
  "modelProviders": {
    "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": "local-model",
          "name": "Local Model (LM Studio)",
          "envKey": "LMSTUDIO_API_KEY",
          "baseUrl": "http://localhost:1234/v1",
          "generationConfig": {
            "timeout": 60000,
            "samplingParams": {
              "temperature": 0.5
            }
          }
        }
      ]
    }
  }
}

Für lokale Server, die keine Authentifizierung erfordern, kannst du einen beliebigen Platzhalterwert für den API-Key verwenden:

# Für Ollama (keine Auth erforderlich)
export OLLAMA_API_KEY="ollama"
 
# Für vLLM (wenn keine Auth konfiguriert ist)
export VLLM_API_KEY="not-needed"

Alibaba Cloud Coding Plan

Der Alibaba Cloud Coding Plan bietet eine vorkonfigurierte Auswahl an Qwen-Modellen, die für Coding-Aufgaben optimiert sind. Dieses Feature ist für Nutzer mit API-Zugang zum Alibaba Cloud Coding Plan verfügbar und bietet eine vereinfachte Einrichtung mit automatischen Updates für die Modellkonfiguration.

Überblick

Wenn du dich mit einem API-Key für den Alibaba Cloud Coding Plan über den Befehl /auth authentifizierst, konfiguriert Qwen Code automatisch die folgenden Modelle:

Einrichtung

1. Besorge dir einen API-Key für den Alibaba Cloud Coding Plan:
   • China: https://bailian.console.aliyun.com/?tab=model#/efm/coding_plan 
   • International: https://modelstudio.console.alibabacloud.com/?tab=dashboard#/efm/coding_plan 
2. Führe den Befehl /auth in Qwen Code aus
3. Wähle Alibaba ModelStudio und dann Coding Plan aus dem Untermenü
4. Wähle deine Region aus
5. Gib deinen API-Key ein, wenn du dazu aufgefordert wirst

Die Modelle werden automatisch konfiguriert und zu deiner /model-Auswahl hinzugefügt.

Regionen

Der Alibaba Cloud Coding Plan unterstützt zwei Regionen:

Die Region wird während der Authentifizierung ausgewählt und in der modelProviders-Konfiguration in der settings.json gespeichert. Um die Region zu wechseln, führe den Befehl /auth erneut aus und wähle eine andere Region.

API-Key-Speicherung

Wenn du den Coding Plan über den Befehl /auth konfigurierst, wird der API-Key unter Verwendung des reservierten Umgebungsvariablennamens BAILIAN_CODING_PLAN_API_KEY gespeichert. Standardmäßig wird er im env-Feld deiner settings.json-Datei gespeichert.

# ~/.qwen/.env
BAILIAN_CODING_PLAN_API_KEY=dein-api-key-hier

Automatische Updates

Die Modellkonfigurationen des Coding Plans sind versioniert. Wenn Qwen Code eine neuere Version der Modellvorlage erkennt, wirst du zu einem Update aufgefordert. Wenn du das Update akzeptierst, wird Folgendes durchgeführt:

• Die bestehenden Coding-Plan-Modellkonfigurationen werden durch die neuesten Versionen ersetzt
• Alle benutzerdefinierten Modellkonfigurationen, die du manuell hinzugefügt hast, bleiben erhalten
• Es wird automatisch zum ersten Modell in der aktualisierten Konfiguration gewechselt

Der Update-Prozess stellt sicher, dass du immer Zugriff auf die neuesten Modellkonfigurationen und Features hast, ohne dass ein manueller Eingriff erforderlich ist.

Manuelle Konfiguration (Fortgeschritten)

Wenn du Coding-Plan-Modelle lieber manuell konfigurieren möchtest, kannst du sie wie jeden OpenAI-kompatiblen Provider zu deiner settings.json hinzufügen:

{
  "modelProviders": {
    "openai": {
      "protocol": "openai",
      "models": [
        {
          "id": "qwen3-coder-plus",
          "name": "qwen3-coder-plus",
          "description": "Qwen3-Coder über den Alibaba Cloud Coding Plan",
          "envKey": "YOUR_CUSTOM_ENV_KEY",
          "baseUrl": "https://coding.dashscope.aliyuncs.com/v1"
        }
      ]
    }
  }
}

Auflösungsebenen und Atomarität

Die effektiven Auth-/Modell-/Credential-Werte werden feldweise anhand der folgenden Priorität ausgewählt (der zuerst vorhandene Wert gewinnt). Du kannst --auth-type mit --model kombinieren, um direkt auf einen Provider-Eintrag zu verweisen; diese CLI-Flags werden vor anderen Ebenen ausgeführt.

*Wenn vorhanden, überschreiben CLI-Auth-Flags die Einstellungen. Andernfalls bestimmen security.auth.selectedType oder der implizite Standard den Auth-Typ. Qwen OAuth und OpenAI sind die einzigen Auth-Typen, die ohne zusätzliche Konfiguration verfügbar sind.

Generation-Config-Layering: Die undurchdringliche Provider-Ebene

Die Konfigurationsauflösung folgt einem strikten Layering-Modell mit einer entscheidenden Regel: Die modelProvider-Ebene ist undurchdringlich.

Funktionsweise

1. Wenn ein modelProvider-Modell ausgewählt IST (z. B. über den Befehl /model, bei dem ein provider-konfiguriertes Modell gewählt wird):

   • Die gesamte generationConfig des Providers wird atomar angewendet
   • Die Provider-Ebene ist vollständig undurchdringlich – tiefere Ebenen (CLI, env, settings) nehmen überhaupt nicht an der Auflösung der generationConfig teil
   • Alle in modelProviders[].generationConfig definierten Felder verwenden die Werte des Providers
   • Alle vom Provider nicht definierten Felder werden auf undefined gesetzt (nicht von den Einstellungen geerbt)
   • Dies stellt sicher, dass Provider-Konfigurationen als vollständiges, in sich geschlossenes “versiegeltes Paket” fungieren

   Wenn ein Modell in modelProviders aufgeführt ist, platziere alle modellspezifischen Generation-Einstellungen für dieses Modell im passenden Provider-Eintrag. Top-Level- model.generationConfig-Werte, einschließlich contextWindowSize, modalities, customHeaders und extra_body, werden für Provider- Modelle ignoriert. Konfiguriere diese Felder unter modelProviders[authType][].generationConfig, damit sie angewendet werden.

2. Wenn KEIN modelProvider-Modell ausgewählt ist (z. B. bei Verwendung von --model mit einer rohen Modell-ID oder bei direkter Verwendung von CLI/env/settings):

   • Die Auflösung fällt auf tiefere Ebenen zurück
   • Felder werden aus CLI → env → settings → Defaults befüllt
   • Dies erzeugt ein Runtime Model (siehe nächster Abschnitt)

Priorität pro Feld für die generationConfig

Atomare Feldbehandlung

Die folgenden Felder werden als atomare Objekte behandelt – Provider-Werte ersetzen das gesamte Objekt vollständig, es findet kein Merging statt:

• samplingParams – Temperature, top_p, max_tokens usw.
• customHeaders – Benutzerdefinierte HTTP-Header
• extra_body – Zusätzliche Request-Body-Parameter

Beispiel

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

Wenn gpt-4o aus modelProviders ausgewählt wird:

• timeout = 60000 (vom Provider, überschreibt die Einstellungen)
• samplingParams.temperature = 0.2 (vom Provider, ersetzt das Einstellungsobjekt vollständig)
• samplingParams.max_tokens = undefined (nicht im Provider definiert, und die Provider-Ebene erbt nicht von den Einstellungen – Felder werden explizit auf undefined gesetzt, wenn sie nicht angegeben werden)

Bei Verwendung eines Raw-Modells über --model gpt-4 (nicht aus modelProviders, erstellt ein Runtime Model):

• timeout = 30000 (aus den Einstellungen)
• samplingParams.temperature = 0.5 (aus den Einstellungen)
• samplingParams.max_tokens = 1000 (aus den Einstellungen)

Die Merge-Strategie für modelProviders selbst ist REPLACE: Das gesamte modelProviders aus den Projekt-Einstellungen überschreibt den entsprechenden Abschnitt in den Benutzer-Einstellungen, anstatt die beiden zusammenzuführen.

Reasoning / Thinking-Konfiguration

Das optionale reasoning-Feld unter generationConfig steuert, wie intensiv das Modell vor der Antwort reasoniert. Die Anthropic- und Gemini-Konverter berücksichtigen dies immer. Die OpenAI-kompatible Pipeline berücksichtigt dies nur, wenn generationConfig.samplingParams nicht gesetzt ist — siehe den Hinweis “Interaktion mit samplingParams” weiter unten.

{
  "modelProviders": {
    "openai": {
      "protocol": "openai",
      "models": [
        {
          "id": "deepseek-v4-pro",
          "name": "DeepSeek V4 Pro",
          "baseUrl": "https://api.deepseek.com/v1",
          "envKey": "DEEPSEEK_API_KEY",
          "generationConfig": {
            // Die vierstufige Skala:
            //   'low'    | 'medium' — serverseitig auf 'high' bei DeepSeek gemappt
            //   'high'   — Standard-Reasoning-Intensität
            //   'max'    — DeepSeek-spezifische extra-starke Stufe
            // Oder `false` setzen, um Reasoning vollständig zu deaktivieren.
            "reasoning": { "effort": "max" },
          },
        },
      ],
    },
  },
}

Verhalten pro Provider

reasoning: false

Das Setzen von reasoning: false (der boolesche Literalwert) deaktiviert Thinking bei jedem Provider explizit – nützlich für günstige Nebenabfragen, die nicht von Reasoning profitieren. Dies wird auch auf Request-Ebene über request.config.thinkingConfig.includeThoughts: false für einmalige Aufrufe (z. B. Vorschlagsgenerierung) berücksichtigt.

Bei einer api.deepseek.com-baseURL gibt die OpenAI-Pipeline das explizite Feld thinking: { type: 'disabled' } aus, das DeepSeek V4+ erfordert – der serverseitige Standard ist 'enabled', daher würde das einfache Weglassen von reasoning_effort immer noch Thinking-Latenz/-Kosten verursachen. Self-hosted DeepSeek-Backends (sglang/vllm) und andere OpenAI-kompatible Server erhalten dieses Feld nicht; wenn du Thinking dort deaktivieren musst, injiziere thinking: { type: 'disabled' } (oder welchen Regler dein Inference-Framework auch immer bereitstellt) über samplingParams/extra_body.

Interaktion mit samplingParams (nur OpenAI-kompatibel)

budget_tokens

Du kannst ein exaktes Thinking-Token-Budget festlegen, indem du budget_tokens zusammen mit effort angibst:

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

Für Anthropic wird dies zu thinking.budget_tokens. Für OpenAI/DeepSeek bleibt das Feld erhalten, wird aber derzeit vom Server ignoriert – reasoning_effort ist der entscheidende Regler.

Provider Models vs. Runtime Models

Qwen Code unterscheidet zwischen zwei Arten von Modellkonfigurationen:

Provider Model

• Definiert in der modelProviders-Konfiguration
• Verfügt über ein vollständiges, atomares Konfigurationspaket
• Bei Auswahl wird seine Konfiguration als undurchdringliche Ebene angewendet
• Erscheint in der /model-Befehlsliste mit vollständigen Metadaten (Name, Beschreibung, Fähigkeiten)
• Empfohlen für Multi-Model-Workflows und Team-Konsistenz

Runtime Model

• Wird dynamisch erstellt, wenn Raw-Modell-IDs über CLI (--model), Umgebungsvariablen oder Einstellungen verwendet werden
• Nicht in modelProviders definiert
• Die Konfiguration wird durch “Projektion” durch die Auflösungs-Ebenen aufgebaut (CLI → env → settings → defaults)
• Wird automatisch als RuntimeModelSnapshot erfasst, wenn eine vollständige Konfiguration erkannt wird
• Ermöglicht Wiederverwendung ohne erneute Eingabe der Credentials

RuntimeModelSnapshot-Lebenszyklus

Wenn du ein Modell ohne Verwendung von modelProviders konfigurierst, erstellt Qwen Code automatisch einen RuntimeModelSnapshot, um deine Konfiguration zu speichern:

# Dies erstellt einen RuntimeModelSnapshot mit der 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

Der Snapshot:

• Erfasst Modell-ID, API-Key, Base-URL und Generation-Config
• Bleibt über Sessions hinweg erhalten (während der Laufzeit im Speicher gespeichert)
• Erscheint in der /model-Befehlsliste als Runtime-Option
• Kann über /model $runtime|openai|my-custom-model umgeschaltet werden

Wichtige Unterschiede

Wann was zu verwenden ist

• Provider Models verwenden, wenn: Du Standardmodelle hast, die im ganzen Team geteilt werden, konsistente Konfigurationen benötigst oder unbeabsichtigte Überschreibungen verhindern willst
• Runtime Models verwenden, wenn: Du schnell ein neues Modell testest, temporäre Credentials verwendest oder mit Ad-hoc-Endpoints arbeitest

Persistenz der Auswahl und Empfehlungen

• /model und /auth persistieren model.name (wo zutreffend) und security.auth.selectedType in den nächstgelegenen beschreibbaren Scope, der bereits modelProviders definiert; andernfalls fallen sie auf den Benutzer-Scope zurück. Dies hält Workspace-/Benutzer-Dateien synchron mit dem aktiven Provider-Katalog.
• Ohne modelProviders mischt der Resolver CLI-/env-/settings-Ebenen und erstellt Runtime Models. Das ist für Single-Provider-Setups in Ordnung, aber umständlich bei häufigem Wechseln. Definiere Provider-Kataloge, wann immer Multi-Model-Workflows üblich sind, damit Wechsel atomar, quellzuordenbar und debugbar bleiben.