Modell-Provider

Qwen Code ermöglicht es dir, mehrere Modell-Provider über die modelProviders-Einstellung in deiner settings.json zu konfigurieren. Dadurch kannst du mit dem /model-Befehl zwischen verschiedenen KI-Modellen und Providern wechseln.

Übersicht

Verwende modelProviders, um kuratierte Modelllisten pro Auth-Typ zu deklarieren, zwischen denen die /model-Auswahl wechseln kann. Die Schlüssel müssen gültige Auth-Typen sein (openai, anthropic, gemini usw.). Jeder Eintrag erfordert eine id und muss envKey enthalten, wobei name, description, baseUrl und generationConfig optional sind. Anmeldedaten werden niemals in den Einstellungen gespeichert; die Laufzeitumgebung liest sie aus process.env[envKey]. Qwen OAuth-Modelle bleiben fest codiert 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 deren Kombinationen zeigen.

Unterstützte Auth-Typen

Die Schlüssel des modelProviders-Objekts müssen gültige authType-Werte sein. Derzeit werden folgende Auth-Typen unterstützt:

[!warning] Wenn ein ungültiger Auth-Typ-Schlüssel verwendet wird (z. B. ein Tippfehler wie "openai-custom"), wird die Konfiguration stillschweigend übersprungen und die Modelle erscheinen nicht in der /model-Auswahl. Verwende immer einen der oben aufgeführten unterstützten Auth-Typ-Werte.

Für API-Anfragen verwendete SDKs

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

Das bedeutet, dass die von dir konfigurierte baseUrl mit dem erwarteten API-Format des entsprechenden SDKs kompatibel sein muss. Wenn du beispielsweise den Auth-Typ openai verwendest, muss der Endpunkt Anfragen 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 Modell-Provider wie OpenRouter.

{
  "env": {
    "OPENAI_API_KEY": "sk-your-actual-openai-key-here",
    "OPENROUTER_API_KEY": "sk-or-your-actual-openrouter-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
          }
        }
      },
      {
        "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
          }
        }
      }
    ]
  }
}

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

Lokale selbst gehostete Modelle (ü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": [
      {
        "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:

# 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

Der Alibaba Cloud Coding Plan bietet eine vorkonfigurierte Reihe von Qwen-Modellen, die für Coding-Aufgaben optimiert sind. Dieses Feature steht Nutzern mit API-Zugriff auf den Alibaba Cloud Coding Plan zur Verfügung und bietet ein vereinfachtes Setup mit automatischen Updates der Modellkonfiguration.

Übersicht

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

Einrichtung

1. Hole dir einen 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. Führe den /auth-Befehl in Qwen Code aus
3. Wähle Alibaba Cloud Coding Plan
4. Wähle deine Region
5. Gib deinen API-Key ein, wenn du dazu aufgefordert wirst

Die Modelle werden automatisch konfiguriert und 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 settings.json unter codingPlan.region gespeichert. Um die Region zu wechseln, führe den /auth-Befehl erneut aus und wähle eine andere Region.

API-Key-Speicherung

Wenn du den Coding Plan über den /auth-Befehl konfigurierst, wird der API-Key unter dem reservierten Umgebungsvariablennamen 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=your-api-key-here

Automatische Updates

Die Modellkonfigurationen des Coding Plans sind versioniert. Wenn Qwen Code eine neuere Version der Modellvorlage erkennt, wirst du zum Update aufgefordert. Wenn du das Update akzeptierst, passiert Folgendes:

• Die bestehenden Coding-Plan-Modellkonfigurationen werden durch die neuesten Versionen ersetzt
• Alle manuell hinzugefügten benutzerdefinierten Modellkonfigurationen 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 manuell eingreifen zu müssen.

Manuelle Konfiguration (Fortgeschritten)

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

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

Auflösungsebenen und Atomarität

Die effektiven Werte für Auth/Modell/Anmeldedaten werden pro Feld nach folgender Priorität ausgewählt (das erste vorhandene 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.

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

Schichtung der Generation Config: Die undurchlässige Provider-Ebene

Die Konfigurationsauflösung folgt einem strengen Schichtungsmodell mit einer entscheidenden Regel: Die modelProvider-Ebene ist undurchlässig (impermeable).

Funktionsweise

1. Wenn ein modelProvider-Modell AUSGEWÄHLT wird (z. B. über den /model-Befehl, der ein provider-konfiguriertes Modell auswählt):

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

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

   • Die Auflösung fällt auf untere Ebenen zurück
   • Felder werden aus CLI → env → Einstellungen → Standards befüllt
   • Dies erstellt ein Runtime Model (siehe nächster Abschnitt)

Feldweise Priorität für 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

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

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

• timeout = 60000 (vom Provider, überschreibt 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 sind)

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

• timeout = 30000 (aus Einstellungen)
• samplingParams.temperature = 0.5 (aus Einstellungen)
• samplingParams.max_tokens = 1000 (aus 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 zu mergen.

Provider-Modelle vs. Runtime-Modelle

Qwen Code unterscheidet zwischen zwei Arten von Modellkonfigurationen:

Provider-Modell

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

Runtime-Modell

• Wird dynamisch erstellt, wenn rohe Modell-IDs über CLI (--model), Umgebungsvariablen oder Einstellungen verwendet werden
• Nicht in modelProviders definiert
• Konfiguration wird durch „Projektion“ durch die Auflösungsebenen aufgebaut (CLI → env → Einstellungen → Standards)
• Wird automatisch als RuntimeModelSnapshot erfasst, wenn eine vollständige Konfiguration erkannt wird
• Ermöglicht Wiederverwendung ohne erneute Eingabe von Anmeldedaten

RuntimeModelSnapshot-Lebenszyklus

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

# 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

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 gewechselt werden

Wichtige Unterschiede

Wann was verwendet werden sollte

• Verwende Provider-Modelle, wenn: Du Standardmodelle hast, die teamweit geteilt werden, konsistente Konfigurationen benötigst oder versehentliche Overrides verhindern möchtest
• Verwende Runtime-Modelle, wenn: Du schnell ein neues Modell testest, temporäre Anmeldedaten nutzt oder mit Ad-hoc-Endpunkten arbeitest

Persistenz der Auswahl und Empfehlungen

• /model und /auth persistieren model.name (wo zutreffend) und security.auth.selectedType im nächstgelegenen beschreibbaren Scope, der bereits modelProviders definiert; andernfalls fallen sie auf den Benutzer-Scope zurück. Dies hält Workspace-/Benutzerdateien mit dem aktiven Provider-Katalog synchron.
• Ohne modelProviders mischt der Resolver CLI-/env-/Einstellungs-Ebenen und erstellt Runtime-Modelle. Das ist für Single-Provider-Setups in Ordnung, wird aber beim häufigen Wechsel umständlich. Definiere Provider-Kataloge immer dann, wenn Multi-Modell-Workflows üblich sind, damit Wechsel atomar, quellattribuiert und debugbar bleiben.