Qwen Code-Konfiguration

Konfigurationsschichten

Die Konfiguration wird in der folgenden Reihenfolge der Priorität angewendet (niedrigere Zahlen werden durch höhere Zahlen überschrieben):

Einstellungsdateien

Qwen Code verwendet JSON-Einstellungsdateien für persistente Konfigurationen. Es gibt vier Orte für diese Dateien:

Das .qwen Verzeichnis in Ihrem Projekt

Zusätzlich zu einer Projekteinstellungsdatei kann das .qwen Verzeichnis eines Projekts andere projekt-spezifische Dateien enthalten, die mit dem Betrieb von Qwen Code zusammenhängen, wie zum Beispiel:

• Benutzerdefinierte Sandbox-Profile (z.B. .qwen/sandbox-macos-custom.sb, .qwen/sandbox.Dockerfile).
• Agent Skills (experimentell) unter .qwen/skills/ (jeder Skill ist ein Verzeichnis, das eine SKILL.md enthält).

Verfügbare Einstellungen in settings.json

Einstellungen sind in Kategorien organisiert. Alle Einstellungen sollten innerhalb ihres entsprechenden Kategorie-Objekts auf oberster Ebene in Ihrer settings.json Datei platziert werden.

Allgemein

output

ui

ide

privacy

model

Beispiel model.generationConfig:

{
  "model": {
    "generationConfig": {
      "timeout": 60000,
      "disableCacheControl": false,
      "customHeaders": {
        "X-Request-ID": "req-123",
        "X-User-ID": "user-456"
      },
      "samplingParams": {
        "temperature": 0.2,
        "top_p": 0.8,
        "max_tokens": 1024
      }
    }
  }
}

Das Feld customHeaders ermöglicht es Ihnen, benutzerdefinierte HTTP-Header zu allen API-Anfragen hinzuzufügen. Dies ist nützlich für Request-Tracing, Monitoring, API-Gateway-Routing oder wenn verschiedene Modelle unterschiedliche Header benötigen. Wenn customHeaders in modelProviders[].generationConfig.customHeaders definiert ist, wird es direkt verwendet; andernfalls werden Header aus model.generationConfig.customHeaders verwendet. Es erfolgt keine Zusammenführung zwischen den beiden Ebenen.

model.openAILoggingDir Beispiele:

• "~/qwen-logs" - Protokolliert ins Verzeichnis ~/qwen-logs
• "./custom-logs" - Protokolliert nach ./custom-logs relativ zum aktuellen Verzeichnis
• "/tmp/openai-logs" - Protokolliert in den absoluten Pfad /tmp/openai-logs

modelProviders

Verwenden Sie modelProviders, um kuratierte Modelllisten pro Authentifizierungstyp zu deklarieren, zwischen denen der /model-Auswahlmodus wechseln kann. Die Schlüssel müssen gültige Authentifizierungstypen sein (openai, anthropic, gemini, vertex-ai, usw.). Jeder Eintrag erfordert eine id und muss envKey enthalten, optional sind name, description, baseUrl und generationConfig. Anmeldedaten werden niemals in den Einstellungen gespeichert; die Laufzeit liest sie aus process.env[envKey]. Qwen-OAuth-Modelle bleiben hartkodiert und können nicht überschrieben werden.

Beispiel

{
  "modelProviders": {
    "openai": [
      {
        "id": "gpt-4o",
        "name": "GPT-4o",
        "envKey": "OPENAI_API_KEY",
        "baseUrl": "https://api.openai.com/v1",
        "generationConfig": {
          "timeout": 60000,
          "maxRetries": 3,
          "customHeaders": {
            "X-Model-Version": "v1.0",
            "X-Request-Priority": "high"
          },
          "samplingParams": { "temperature": 0.2 }
        }
      }
    ],
    "anthropic": [
      {
        "id": "claude-3-5-sonnet",
        "envKey": "ANTHROPIC_API_KEY",
        "baseUrl": "https://api.anthropic.com/v1"
      }
    ],
    "gemini": [
      {
        "id": "gemini-2.0-flash",
        "name": "Gemini 2.0 Flash",
        "envKey": "GEMINI_API_KEY",
        "baseUrl": "https://generativelanguage.googleapis.com"
      }
    ],
    "vertex-ai": [
      {
        "id": "gemini-1.5-pro-vertex",
        "envKey": "GOOGLE_API_KEY",
        "baseUrl": "https://generativelanguage.googleapis.com"
      }
    ]
  }
}

[!note] Nur der Befehl /model unterstützt Nicht-Standard-Authentifizierungstypen. Anthropic, Gemini, Vertex AI usw. müssen über modelProviders definiert werden. Der Befehl /auth listet absichtlich nur die integrierten Qwen-OAuth- und OpenAI-Flows auf.

Auflösungsschichten und Atomarität

Die effektiven Werte für Authentifizierung/Modell/Credentials werden pro Feld nach folgender Rangfolge ausgewählt (zuerst vorhanden gewinnt). Sie können --auth-type mit --model kombinieren, um direkt auf einen Anbietereintrag zu verweisen; diese CLI-Flags werden vor anderen Schichten ausgeführt.

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

Vom Modellanbieter stammende Werte werden atomar angewendet: Sobald ein Anbietermodell aktiv ist, wird jedes von ihm definierte Feld vor niedrigeren Schichten geschützt, bis Sie manuell die Anmeldedaten über /auth löschen. Die endgültige generationConfig ist die Projektion über alle Schichten – niedrigere Schichten füllen nur Lücken, die von höheren Schichten übrig bleiben, und die Anbieterschicht bleibt unveränderbar.

Die Merge-Strategie für modelProviders ist ERSETZEN: Das gesamte modelProviders aus den Projekteinstellungen wird den entsprechenden Abschnitt in den Benutzereinstellungen überschreiben, anstatt die beiden zusammenzuführen.

Schichtung der Generierungskonfiguration

Pro-Feld-Rangfolge für generationConfig:

1. Programmatische Überschreibungen (z. B. Laufzeit-Änderungen von /model, /auth)
2. modelProviders[authType][].generationConfig
3. settings.model.generationConfig
4. Standardwerte des Content-Generators (getDefaultGenerationConfig für OpenAI, getParameterValue für Gemini usw.)

samplingParams und customHeaders werden beide atomar behandelt; Anbietewerte ersetzen das gesamte Objekt. Wenn modelProviders[].generationConfig diese Felder definiert, werden sie direkt verwendet; andernfalls werden Werte aus model.generationConfig verwendet. Zwischen Anbieter- und globalen Konfigurationsstufen erfolgt keine Zusammenführung. Standards des Content-Generators werden zuletzt angewendet, sodass jeder Anbieter seine optimierte Basis beibehält.

Auswahlpersistenz und Empfehlungen

[!important] Definieren Sie modelProviders nach Möglichkeit im benutzerspezifischen ~/.qwen/settings.json und vermeiden Sie das Speichern von Anmeldeinformationen in beliebigen Bereichen. Das Festhalten des Anbieterkatalogs in den Benutzereinstellungen verhindert Merge-/Überschreibekonflikte zwischen Projekt- und Benutzerbereich und stellt sicher, dass /auth und /model Updates immer in einen konsistenten Bereich geschrieben werden.

• /model und /auth speichern model.name (wenn zutreffend) und security.auth.selectedType im nächstgelegenen beschreibbaren Bereich, der bereits modelProviders definiert; andernfalls greifen sie auf den Benutzerbereich zurück. Dadurch bleiben Arbeitsbereichs-/Benutzerdateien mit dem aktiven Anbieterkatalog synchronisiert.
• Ohne modelProviders mischt der Resolver CLI/Umgebungsvariablen/Einstellungsebenen, was für Einzelanbieter-Setups in Ordnung ist, aber umständlich wird, wenn häufig gewechselt wird. Definieren Sie Anbieterkataloge immer dann, wenn Mehrfachmodell-Workflows üblich sind, damit Wechsel atomar, quellenbezogen und debuggbar bleiben.

context

Problembehandlung bei der Dateisuchleistung

Wenn Sie Leistungsprobleme bei der Dateisuche haben (z. B. bei @-Vervollständigungen), insbesondere in Projekten mit einer sehr großen Anzahl von Dateien, können Sie folgende Maßnahmen in der empfohlenen Reihenfolge ausprobieren:

1. Verwenden Sie .qwenignore: Erstellen Sie eine .qwenignore-Datei im Stammverzeichnis Ihres Projekts, um Verzeichnisse auszuschließen, die eine große Anzahl von Dateien enthalten, auf die Sie nicht verweisen müssen (z. B. Build-Artefakte, Protokolle, node_modules). Die Reduzierung der Gesamtanzahl durchsuchter Dateien ist der effektivste Weg, um die Leistung zu verbessern.
2. Deaktivieren Sie die unscharfe Suche: Falls das Ignorieren von Dateien nicht ausreicht, können Sie die unscharfe Suche deaktivieren, indem Sie disableFuzzySearch in Ihrer settings.json-Datei auf true setzen. Dadurch wird ein einfacheres, nicht-unscharfes Abgleichsalgorithmus verwendet, der schneller sein kann.
3. Deaktivieren Sie die rekursive Dateisuche: Als letztes Mittel können Sie die rekursive Dateisuche vollständig deaktivieren, indem Sie enableRecursiveFileSearch auf false setzen. Dies ist die schnellste Option, da sie ein rekursives Durchsuchen Ihres Projekts vermeidet. Allerdings müssen Sie dann beim Verwenden von @-Vervollständigungen den vollständigen Pfad zu den Dateien eingeben.

tools

mcp

Sicherheit

Erweitert

experimentell

mcpServers

Konfiguriert Verbindungen zu einem oder mehreren Model-Context Protocol (MCP)-Servern zum Entdecken und Nutzen benutzerdefinierter Tools. Qwen Code versucht, eine Verbindung zu jedem konfigurierten MCP-Server herzustellen, um verfügbare Tools zu entdecken. Wenn mehrere MCP-Server ein Tool mit demselben Namen bereitstellen, werden die Toolnamen mit dem Server-Alias versehen, den Sie in der Konfiguration definiert haben (z.B. serverAlias__actualToolName), um Konflikte zu vermeiden. Beachten Sie, dass das System bestimmte Schema-Eigenschaften aus MCP-Tool-Definitionen zur Kompatibilität entfernen könnte. Mindestens eines von command, url oder httpUrl muss angegeben werden. Wenn mehrere angegeben sind, ist die Prioritätsreihenfolge httpUrl, dann url, dann command.

telemetry

Konfiguriert das Logging und die Metrik-Erfassung für Qwen Code. Weitere Informationen finden Sie unter Telemetrie.

Beispiel settings.json

Hier ist ein Beispiel für eine settings.json-Datei mit der verschachtelten Struktur, neu ab Version 0.3.0:

{
  "general": {
    "vimMode": true,
    "preferredEditor": "code"
  },
  "ui": {
    "theme": "GitHub",
    "hideTips": false,
    "customWittyPhrases": [
      "Du vergisst jeden Tag tausend Dinge. Stelle sicher, dass dies eines davon ist",
      "Verbindung zu AGI wird hergestellt"
    ]
  },
  "tools": {
    "approvalMode": "yolo",
    "sandbox": "docker",
    "discoveryCommand": "bin/get_tools",
    "callCommand": "bin/call_tool",
    "exclude": ["write_file"]
  },
  "mcpServers": {
    "mainServer": {
      "command": "bin/mcp_server.py"
    },
    "anotherServer": {
      "command": "node",
      "args": ["mcp_server.js", "--verbose"]
    }
  },
  "telemetry": {
    "enabled": true,
    "target": "local",
    "otlpEndpoint": "http://localhost:4317",
    "logPrompts": true
  },
  "privacy": {
    "usageStatisticsEnabled": true
  },
  "model": {
    "name": "qwen3-coder-plus",
    "maxSessionTurns": 10,
    "enableOpenAILogging": false,
    "openAILoggingDir": "~/qwen-logs",
    "summarizeToolOutput": {
      "run_shell_command": {
        "tokenBudget": 100
      }
    }
  },
  "context": {
    "fileName": ["CONTEXT.md", "QWEN.md"],
    "includeDirectories": ["path/to/dir1", "~/path/to/dir2", "../path/to/dir3"],
    "loadFromIncludeDirectories": true,
    "fileFiltering": {
      "respectGitIgnore": false
    }
  },
  "advanced": {
    "excludedEnvVars": ["DEBUG", "DEBUG_MODE", "NODE_ENV"]
  }
}

Shell-Verlauf

Die CLI speichert einen Verlauf der Shell-Befehle, die Sie ausführen. Um Konflikte zwischen verschiedenen Projekten zu vermeiden, wird dieser Verlauf in einem projektspezifischen Verzeichnis innerhalb Ihres Benutzerverzeichnisses gespeichert.

• Speicherort: ~/.qwen/tmp/<project_hash>/shell_history
  • <project_hash> ist eine eindeutige Kennung, die aus dem Stammverzeichnis Ihres Projekts generiert wird.
  • Der Verlauf wird in einer Datei mit dem Namen shell_history gespeichert.

Umgebungsvariablen und .env-Dateien

Umgebungsvariablen sind ein üblicher Weg, um Anwendungen zu konfigurieren, insbesondere für sensible Informationen (wie Token) oder für Einstellungen, die sich zwischen verschiedenen Umgebungen ändern können.

Qwen Code kann Umgebungsvariablen automatisch aus .env-Dateien laden. Informationen zu authentifizierungsbezogenen Variablen (wie OPENAI_*) und dem empfohlenen Ansatz mit .qwen/.env finden Sie unter Authentifizierung.

Tabelle der Umgebungsvariablen

Befehlszeilenargumente

Argumente, die direkt beim Ausführen der CLI übergeben werden, können andere Konfigurationen für diese spezifische Sitzung überschreiben.

Befehlszeilenargumente-Tabelle

Kontextdateien (hierarchischer Anweisungskontext)

Obwohl dies nicht direkt die Konfiguration des CLI-Verhaltens betrifft, sind Kontextdateien (standardmäßig QWEN.md, aber konfigurierbar über die Einstellung context.fileName) entscheidend für die Konfiguration des anweisenden Kontexts (auch als „Speicher“ bezeichnet). Diese leistungsstarke Funktion ermöglicht es Ihnen, projektspezifische Anweisungen, Kodierungsstile oder andere relevante Hintergrundinformationen an die KI zu übermitteln, wodurch deren Antworten besser auf Ihre Bedürfnisse zugeschnitten und genauer werden. Die CLI enthält Benutzeroberflächenelemente wie einen Indikator in der Fußzeile, der die Anzahl der geladenen Kontextdateien anzeigt, um Sie über den aktiven Kontext zu informieren.

• Zweck: Diese Markdown-Dateien enthalten Anweisungen, Richtlinien oder Kontextinformationen, die das Qwen-Modell während Ihrer Interaktionen berücksichtigen soll. Das System ist so ausgelegt, dass dieser anweisende Kontext hierarchisch verwaltet wird.

Beispiel für Dateiinhalt im Kontext (z. B. QWEN.md)

Hier ist ein konzeptionelles Beispiel dafür, was eine Kontextdatei im Stammverzeichnis eines TypeScript-Projekts enthalten könnte:

# Projekt: Meine fantastische TypeScript-Bibliothek

## Allgemeine Anweisungen:
- Beim Generieren von neuem TypeScript-Code bitte den bestehenden Codierungsstil beachten.
- Sicherstellen, dass alle neuen Funktionen und Klassen über JSDoc-Kommentare verfügen.
- Wo angebracht, funktionale Programmierparadigmen bevorzugen.
- Der gesamte Code sollte mit TypeScript 5.0 und Node.js 20+ kompatibel sein.

## Codierungsstil:
- Für Einrückungen 2 Leerzeichen verwenden.
- Schnittstellennamen sollten mit `I` beginnen (z. B. `IUserService`).
- Private Klassenmember sollten mit einem Unterstrich (`_`) beginnen.
- Immer strikte Gleichheit verwenden (`===` und `!==`).

## Spezifische Komponente: `src/api/client.ts`
- Diese Datei behandelt alle ausgehenden API-Anfragen.
- Beim Hinzufügen neuer API-Aufruffunktionen sicherstellen, dass sie umfassende Fehlerbehandlung und Protokollierung enthalten.
- Für alle GET-Anfragen das vorhandene `fetchWithRetry`-Hilfsprogramm verwenden.

Bezüglich Abhängigkeiten:

• Vermeiden Sie die Einführung neuer externer Abhängigkeiten, es sei denn, sie sind absolut notwendig.
• Falls eine neue Abhängigkeit erforderlich ist, geben Sie bitte den Grund an.

Dieses Beispiel zeigt, wie Sie allgemeinen Projekt-Kontext, spezifische Kodierungsrichtlinien und sogar Hinweise zu bestimmten Dateien oder Komponenten bereitstellen können. Je relevanter und präziser Ihre Kontextdateien sind, desto besser kann die KI Ihnen helfen. Projektspezifische Kontextdateien werden dringend empfohlen, um Konventionen und Kontext festzulegen.

- **Hierarchisches Laden und Priorisierung:** Die CLI implementiert ein hierarchisches Speichersystem durch das Laden von Kontextdateien (z.B. `QWEN.md`) aus mehreren Orten. Inhalte aus Dateien weiter unten in dieser Liste (spezifischer) überschreiben oder ergänzen typischerweise Inhalte aus Dateien weiter oben (allgemeiner). Die genaue Zusammenfügungsreihenfolge und der endgültige Kontext können mit dem Befehl `/memory show` eingesehen werden. Die typische Lade-Reihenfolge ist:
  1. **Globale Kontextdatei:**
     - Ort: `~/.qwen/<konfigurierte-kontext-dateiname>` (z.B. `~/.qwen/QWEN.md` in Ihrem Benutzerverzeichnis).
     - Gültigkeitsbereich: Stellt Standardanweisungen für alle Ihre Projekte bereit.
  2. **Projektstamm- und übergeordnete Kontextdateien:**
     - Ort: Die CLI sucht nach der konfigurierten Kontextdatei im aktuellen Arbeitsverzeichnis und dann in jedem übergeordneten Verzeichnis bis zum Projektstamm (identifiziert durch einen `.git`-Ordner) oder Ihrem Home-Verzeichnis.
     - Gültigkeitsbereich: Stellt Kontext bereit, der für das gesamte Projekt oder einen signifikanten Teil davon relevant ist.
- **Zusammenfügung & UI-Anzeige:** Die Inhalte aller gefundenen Kontextdateien werden zusammengeführt (mit Trennzeichen, die ihren Ursprung und Pfad anzeigen) und als Teil des System-Prompts bereitgestellt. Die CLI-Fußzeile zeigt die Anzahl der geladenen Kontextdateien an und gibt Ihnen so einen schnellen visuellen Hinweis auf den aktiven instruktiven Kontext.
- **Inhalte importieren:** Sie können Ihre Kontextdateien modularisieren, indem Sie andere Markdown-Dateien mit der Syntax `@pfad/zu/datei.md` importieren. Weitere Details finden Sie in der [Memory Import Processor-Dokumentation](../configuration/memory).
- **Befehle zur Speicherverwaltung:**
  - Verwenden Sie `/memory refresh`, um einen erneuten Scan und Neuladen aller Kontextdateien aus allen konfigurierten Orten zu erzwingen. Dadurch wird der instruktive Kontext der KI aktualisiert.
  - Verwenden Sie `/memory show`, um den aktuell geladenen kombinierten instruktiven Kontext anzuzeigen, sodass Sie die Hierarchie und die von der KI verwendeten Inhalte überprüfen können.
  - Siehe [Befehlsdokumentation](../features/commands) für vollständige Details zum `/memory`-Befehl und seinen Unterbefehlen (`show` und `refresh`).

Durch das Verständnis und die Nutzung dieser Konfigurationsschichten und der hierarchischen Natur der Kontextdateien können Sie den Speicher der KI effektiv verwalten und die Antworten von Qwen Code an Ihre spezifischen Anforderungen und Projekte anpassen.

## Sandbox

Qwen Code kann potenziell unsichere Operationen (wie Shell-Befehle und Dateiänderungen) innerhalb einer isolierten Umgebung ausführen, um Ihr System zu schützen.

[Sandbox](../features/sandbox) ist standardmäßig deaktiviert, kann aber auf verschiedene Arten aktiviert werden:

- Mit dem Flag `--sandbox` oder `-s`.
- Durch Setzen der Umgebungsvariable `GEMINI_SANDBOX`.
- Die Sandbox ist standardmäßig aktiviert, wenn `--yolo` oder `--approval-mode=yolo` verwendet wird.

Standardmäßig wird ein vorgefertigtes Docker-Image `qwen-code-sandbox` verwendet.

Für projektspezifische Sandbox-Anforderungen können Sie eine benutzerdefinierte Dockerfile-Datei unter `.qwen/sandbox.Dockerfile` im Stammverzeichnis Ihres Projekts erstellen. Diese Dockerfile kann auf dem Basis-Sandbox-Image basieren:

FROM qwen-code-sandbox

Fügen Sie hier Ihre benutzerdefinierten Abhängigkeiten oder Konfigurationen hinzu

Zum Beispiel:

RUN apt-get update && apt-get install -y some-package

COPY ./my-config /app/my-config

Wenn `.qwen/sandbox.Dockerfile` existiert, können Sie die Umgebungsvariable `BUILD_SANDBOX` verwenden, wenn Sie Qwen Code ausführen, um automatisch das benutzerdefinierte Sandbox-Image zu erstellen:

BUILD_SANDBOX=1 qwen -s

## Nutzungsstatistiken

Um uns bei der Verbesserung von Qwen Code zu helfen, sammeln wir anonymisierte Nutzungsstatistiken. Diese Daten helfen uns zu verstehen, wie die CLI verwendet wird, häufige Probleme zu identifizieren und neue Funktionen zu priorisieren.

**Was wir sammeln:**

- **Tool-Aufrufe:** Wir protokollieren die Namen der aufgerufenen Tools, ob sie erfolgreich waren oder fehlschlugen, und wie lange sie zur Ausführung benötigten. Wir erfassen nicht die Argumente, die an die Tools übergeben wurden, oder Daten, die von ihnen zurückgegeben wurden.
- **API-Anfragen:** Wir protokollieren das Modell, das für jede Anfrage verwendet wurde, die Dauer der Anfrage und ob sie erfolgreich war. Wir erfassen nicht den Inhalt der Prompts oder Antworten.
- **Sitzungsinformationen:** Wir sammeln Informationen über die Konfiguration der CLI, wie z.B. die aktivierten Tools und den Genehmigungsmodus.

**Was wir NICHT sammeln:**

- **Personenbezogene Daten (PII):** Wir erfassen keine persönlichen Informationen wie Ihren Namen, Ihre E-Mail-Adresse oder API-Schlüssel.
- **Inhalt von Prompts und Antworten:** Wir protokollieren nicht den Inhalt Ihrer Prompts oder die Antworten des Modells.
- **Dateiinhalte:** Wir protokollieren nicht den Inhalt von Dateien, die von der CLI gelesen oder geschrieben werden.

**So deaktivieren Sie die Erfassung:**

Sie können die Erfassung von Nutzungsstatistiken jederzeit deaktivieren, indem Sie die Eigenschaft `usageStatisticsEnabled` auf `false` unter der Kategorie `privacy` in Ihrer `settings.json`-Datei setzen:

{ “privacy”: { “usageStatisticsEnabled”: false } }

> [!note]
>
> Wenn Nutzungsstatistiken aktiviert sind, werden Ereignisse an einen Alibaba Cloud RUM-Erfassungsendpunkt gesendet.