Qwen-Code-Konfiguration

Konfigurationsebenen

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

Einstellungsdateien

Qwen Code verwendet JSON-Einstellungsdateien für eine dauerhafte Konfiguration. Es gibt vier Speicherorte für diese Dateien:

Das Verzeichnis .qwen in Ihrem Projekt

Neben einer Projekteinstellungsdatei kann das Verzeichnis .qwen Ihres Projekts weitere projektspezifische Dateien enthalten, die für den Betrieb von Qwen Code relevant sind, beispielsweise:

• Benutzerdefinierte Sandbox-Profile (z. B. .qwen/sandbox-macos-custom.sb, .qwen/sandbox.Dockerfile).
• Agenten-Skills im Verzeichnis .qwen/skills/ (jeder Skill ist ein Verzeichnis mit einer Datei SKILL.md).

Konfigurationsmigration

Qwen Code migriert automatisch veraltete Konfigurationseinstellungen in das neue Format. Vor der Migration werden alte Einstellungsdateien gesichert. Die folgenden Einstellungen wurden von einer negativen (disable*) in eine positive (enable*) Benennung umbenannt:

Konsolidierungsrichtlinie für disableAutoUpdate und disableUpdateNag

Wenn beide veralteten Einstellungen mit unterschiedlichen Werten vorhanden sind, erfolgt die Migration nach folgender Richtlinie: Falls entweder disableAutoUpdate oder disableUpdateNag den Wert true hat, wird enableAutoUpdate auf false gesetzt:

Verfügbare Einstellungen in settings.json

Einstellungen sind in Kategorien gruppiert. Alle Einstellungen müssen innerhalb des entsprechenden obersten Kategorieobjekts in Ihrer Datei settings.json platziert werden.

Allgemein

Ausgabe

ui

IDE

Datenschutz

Modell

Beispiel für model.generationConfig:

{
  "model": {
    "generationConfig": {
      "timeout": 60000,
      "contextWindowSize": 128000,
      "modalities": {
        "image": true
      },
      "enableCacheControl": true,
      "customHeaders": {
        "X-Client-Request-ID": "req-123"
      },
      "extra_body": {
        "enable_thinking": true
      },
      "samplingParams": {
        "temperature": 0.2,
        "top_p": 0.8,
        "max_tokens": 1024
      }
    }
  }
}

contextWindowSize:

Überschreibt die Standard-Kontextfenstergröße für das ausgewählte Modell. Qwen Code bestimmt das Kontextfenster anhand integrierter Standardwerte, die auf Namensmustern des Modells basieren, mit einem konstanten Fallback-Wert. Verwenden Sie diese Einstellung, wenn die effektive Kontextgrenze eines Anbieters von der Standard-Kontextgrenze von Qwen Code abweicht. Dieser Wert definiert die vom Modell angenommene maximale Kontextkapazität, nicht eine pro Anfrage geltende Token-Grenze.

modalities:

Überschreibt die automatisch erkannten Eingabemodalitäten für das ausgewählte Modell. Qwen Code erkennt unterstützte Modalitäten (Bild, PDF, Audio, Video) automatisch anhand von Namensmustern des Modells. Verwenden Sie diese Einstellung, wenn die automatische Erkennung fehlerhaft ist – z. B., um pdf für ein Modell zu aktivieren, das dies unterstützt, aber nicht erkannt wird. Format: { "image": true, "pdf": true, "audio": true, "video": true }. Lassen Sie einen Schlüssel weg oder setzen Sie ihn auf false, um nicht unterstützte Typen auszuschließen.

customHeaders:

Ermöglicht das Hinzufügen benutzerdefinierter HTTP-Header zu allen API-Anfragen. Dies ist nützlich für Request-Tracing, Monitoring, Routing über API-Gateways oder wenn verschiedene Modelle unterschiedliche Header benötigen. Falls customHeaders in modelProviders[].generationConfig.customHeaders definiert ist, wird dieser direkt verwendet; andernfalls werden die Header aus model.generationConfig.customHeaders genutzt. Zwischen beiden Ebenen findet keine Zusammenführung statt.

Das Feld extra_body ermöglicht das Hinzufügen benutzerdefinierter Parameter zum Anfragetext, der an die API gesendet wird. Dies ist nützlich für anbieterspezifische Optionen, die nicht durch die Standardkonfigurationsfelder abgedeckt sind. Hinweis: Dieses Feld wird nur für OpenAI-kompatible Anbieter (openai, qwen-oauth) unterstützt. Für Anthropic- und Gemini-Anbieter wird es ignoriert. Falls extra_body in modelProviders[].generationConfig.extra_body definiert ist, wird dieser direkt verwendet; andernfalls werden die Werte aus model.generationConfig.extra_body genutzt.

Beispiele für model.openAILoggingDir:

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

Kontext

Problembehandlung bei der Dateisuchleistung

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

1. Verwenden Sie .qwenignore: Erstellen Sie eine Datei .qwenignore im Stammverzeichnis Ihres Projekts, um Verzeichnisse auszuschließen, die eine große Anzahl von Dateien enthalten, auf die Sie nicht zugreifen müssen (z. B. Build-Artefakte, Protokolldateien oder node_modules). Die Reduzierung der Gesamtanzahl durchsuchter Dateien ist die effektivste Methode zur Leistungsverbesserung.
2. Deaktivieren Sie die unscharfe Suche: Falls das Ausschließen von Dateien nicht ausreicht, können Sie die unscharfe Suche deaktivieren, indem Sie in Ihrer Datei settings.json die Einstellung enableFuzzySearch auf false setzen. Dadurch wird ein einfacherer, nicht-unscharfer 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 in Ihrer settings.json auf false setzen. Dies ist die schnellste Option, da sie eine rekursive Durchsuchung Ihres Projekts vermeidet. Allerdings müssen Sie dann beim Einsatz von @-Vervollständigungen den vollständigen Pfad zu den Dateien eingeben.

Tools

mcp

LSP

[!warning] Experimentelle Funktion: Die LSP-Unterstützung ist derzeit experimentell und standardmäßig deaktiviert. Aktivieren Sie sie mithilfe des Befehlszeilenflags --experimental-lsp.

Das Language Server Protocol (LSP) bietet Code-Intelligenzfunktionen wie „Gehe zu Definition“, „Finde Verweise“ und Diagnosen.

Die Konfiguration des LSP-Servers erfolgt über .lsp.json-Dateien im Stammverzeichnis Ihres Projekts, nicht über settings.json. Weitere Informationen zur Konfiguration sowie Beispiele finden Sie in der LSP-Dokumentation.

Sicherheit

Erweitert

mcpServers

Konfiguriert Verbindungen zu einem oder mehreren Model-Context-Protocol-(MCP-)Servern, um benutzerdefinierte Tools zu entdecken und zu nutzen. Qwen Code versucht, eine Verbindung zu jedem konfigurierten MCP-Server herzustellen, um verfügbare Tools zu ermitteln. Falls mehrere MCP-Server ein Tool mit demselben Namen bereitstellen, werden die Toolnamen mit dem von Ihnen in der Konfiguration definierten Server-Alias präfixiert (z. B. serverAlias__actualToolName), um Namenskonflikte zu vermeiden. Beachten Sie, dass das System bestimmte Schemaeigenschaften aus den MCP-Tooldefinitionen aus Kompatibilitätsgründen entfernen kann. Mindestens einer der folgenden Werte muss angegeben werden: command, url oder httpUrl. Werden mehrere Werte angegeben, gilt folgende Priorisierungsreihenfolge: httpUrl, dann url, dann command.

Telemetrie

Konfiguriert die Protokollierung und Erfassung von Metriken für Qwen Code. Weitere Informationen finden Sie unter Telemetrie.

Beispiel für settings.json

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

{
  "general": {
    "vimMode": true,
    "preferredEditor": "code"
  },
  "ui": {
    "theme": "GitHub",
    "hideTips": false,
    "customWittyPhrases": [
      "Sie vergessen täglich tausend Dinge. Stellen Sie sicher, dass dies eine davon ist.",
      "Verbinde mit AGI"
    ]
  },
  "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",
  },
  "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 von Ihnen ausgeführten Shell-Befehle. Um Konflikte zwischen verschiedenen Projekten zu vermeiden, wird dieser Verlauf in einem projektbezogenen Verzeichnis innerhalb des Home-Ordners Ihres Benutzers 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 namens shell_history gespeichert.

Umgebungsvariablen und .env-Dateien

Umgebungsvariablen sind eine gängige Methode, um Anwendungen zu konfigurieren – insbesondere für sensible Informationen (wie Tokens) oder für Einstellungen, die sich je nach Umgebung unterscheiden können.

Qwen Code kann Umgebungsvariablen automatisch aus .env-Dateien laden.
Weitere Informationen zu authentifizierungsspezifischen Variablen (z. B. OPENAI_*) sowie zum 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 instruktiver Kontext)

Obwohl Kontextdateien (standardmäßig QWEN.md, aber konfigurierbar über die Einstellung context.fileName) nicht streng genommen die Verhaltensweise der CLI konfigurieren, sind sie entscheidend für die Konfiguration des instruktiven Kontexts (auch als „Gedächtnis“ bezeichnet). Diese leistungsstarke Funktion ermöglicht es Ihnen, dem KI-Modell projektspezifische Anweisungen, Richtlinien für den Codierstil oder sonstige relevante Hintergrundinformationen bereitzustellen, wodurch die Antworten präziser und besser auf Ihre Anforderungen zugeschnitten werden. Die CLI enthält Benutzeroberflächenelemente – beispielsweise einen Indikator in der Fußzeile, der die Anzahl der geladenen Kontextdateien anzeigt –, um Sie stets ü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 konzipiert, dass es diesen instruktiven Kontext hierarchisch verwaltet.

Beispielinhalt einer Kontextdatei (z. B. QWEN.md)

Hier ist ein konzeptionelles Beispiel für den Inhalt einer Kontextdatei im Stammverzeichnis eines TypeScript-Projekts:

# Projekt: Meine großartige TypeScript-Bibliothek

## Allgemeine Anweisungen:
- Generieren Sie neuen TypeScript-Code stets im Einklang mit dem bestehenden Codierungsstil.
- Stellen Sie sicher, dass alle neuen Funktionen und Klassen JSDoc-Kommentare enthalten.
- Verwenden Sie dort, wo sinnvoll, funktionale Programmierparadigmen.
- Der gesamte Code muss mit TypeScript 5.0 und Node.js 20+ kompatibel sein.

## Codierungsstil:
- Verwenden Sie zwei Leerzeichen für die Einrückung.
- Schnittstellennamen müssen mit `I` beginnen (z. B. `IUserService`).
- Private Klassenmember müssen mit einem Unterstrich (`_`) beginnen.
- Verwenden Sie stets strenge Gleichheit (`===` und `!==`).

## Spezifische Komponente: `src/api/client.ts`
- Diese Datei verarbeitet alle ausgehenden API-Anfragen.
- Wenn Sie neue API-Aufruffunktionen hinzufügen, stellen Sie sicher, dass sie eine robuste Fehlerbehandlung und Protokollierung enthalten.
- Verwenden Sie das vorhandene Hilfsprogramm `fetchWithRetry` für alle GET-Anfragen.

## Zu Abhängigkeiten:
- Vermeiden Sie die Einführung neuer externer Abhängigkeiten, sofern dies nicht unbedingt erforderlich ist.
- Falls eine neue Abhängigkeit benötigt wird, geben Sie bitte den Grund dafür an.

Dieses Beispiel zeigt, wie Sie allgemeinen Projektzusammenhang, spezifische Codierkonventionen und sogar Hinweise zu bestimmten Dateien oder Komponenten bereitstellen können. Je relevanter und präziser Ihre Kontextdateien sind, desto besser kann die KI Sie unterstützen. Projekt-spezifische Kontextdateien werden ausdrücklich empfohlen, um Konventionen und Kontext festzulegen.

• Hierarchisches Laden und Priorisierung: Die CLI implementiert ein hierarchisches Speichersystem, indem sie Kontextdateien (z. B. QWEN.md) aus mehreren Standorten lädt. Inhalte aus Dateien weiter unten in dieser Liste (spezifischer) überschreiben oder ergänzen in der Regel Inhalte aus Dateien weiter oben (allgemeiner). Die genaue Reihenfolge der Zusammenfassung und der endgültige Kontext können mithilfe des Befehls /memory show überprüft werden. Die typische Lade-Reihenfolge lautet:
  1. Globale Kontextdatei:
     • Ort: ~/.qwen/<konfigurierter-kontext-dateiname> (z. B. ~/.qwen/QWEN.md im Home-Verzeichnis Ihres Benutzers).
     • Gültigkeitsbereich: Stellt Standardanweisungen für alle Ihre Projekte bereit.
  2. Kontextdateien im Projektstammverzeichnis und in übergeordneten Verzeichnissen:
     • Ort: Die CLI sucht nach der konfigurierten Kontextdatei im aktuellen Arbeitsverzeichnis und anschließend in jedem übergeordneten Verzeichnis bis hin zum Projektstamm (identifiziert durch einen .git-Ordner) oder bis zu Ihrem Home-Verzeichnis.
     • Gültigkeitsbereich: Stellt Kontext bereit, der für das gesamte Projekt oder einen größeren Teil davon relevant ist.
• Zusammenfassung und UI-Anzeige: Die Inhalte aller gefundenen Kontextdateien werden zusammengeführt (mit Trennzeichen, die Herkunft und Pfad kennzeichnen) und als Teil der Systemanweisung bereitgestellt. In der Fußzeile der CLI wird die Anzahl der geladenen Kontextdateien angezeigt, sodass Sie auf einen Blick erkennen können, welcher instruktive Kontext gerade aktiv ist.
• Importieren von Inhalten: Sie können Ihre Kontextdateien modularisieren, indem Sie andere Markdown-Dateien mit der Syntax @pfad/zur/datei.md importieren. Weitere Details finden Sie in der Dokumentation zum Memory-Import-Prozessor.
• Befehle zur Speicherverwaltung:
  • Verwenden Sie /memory refresh, um einen erneuten Scan und Neuladen aller Kontextdateien aus allen konfigurierten Standorten zu erzwingen. Dadurch wird der instruktive Kontext der KI aktualisiert.
  • Verwenden Sie /memory show, um den aktuell zusammengeführten instruktiven Kontext anzuzeigen und so die Hierarchie und den von der KI verwendeten Inhalt zu überprüfen.
  • Weitere Informationen zum /memory-Befehl und seinen Unterbefehlen (show und refresh) finden Sie in der Dokumentation zu Befehlen.

Indem Sie diese Konfigurationsebenen und die hierarchische Struktur von Kontextdateien verstehen und nutzen, können Sie den Speicher der KI effektiv verwalten und die Antworten von Qwen Code gezielt an Ihre spezifischen Anforderungen und Projekte anpassen.

Sandbox

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

Der Sandbox-Modus ist standardmäßig deaktiviert, kann jedoch auf verschiedene Weisen aktiviert werden:

• Mit dem Flag --sandbox oder -s.
• Durch Festlegen der Umgebungsvariablen QWEN_SANDBOX.
• Der Sandbox-Modus ist standardmäßig aktiviert, wenn --yolo oder --approval-mode=yolo verwendet wird.

Standardmäßig wird das vorgefertigte Docker-Image qwen-code-sandbox verwendet.

Für projektbezogene Sandbox-Anforderungen können Sie im Stammverzeichnis Ihres Projekts eine benutzerdefinierte Dockerfile unter .qwen/sandbox.Dockerfile 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

# 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 beim Ausführen von Qwen Code die Umgebungsvariable `BUILD_SANDBOX` verwenden, um das benutzerdefinierte Sandbox-Image automatisch zu erstellen:

BUILD_SANDBOX=1 qwen -s

## Nutzungsstatistiken

Um die Weiterentwicklung von Qwen Code zu unterstützen, erfassen wir anonymisierte Nutzungsstatistiken. Diese Daten helfen uns dabei, die Nutzung der CLI besser zu verstehen, häufig auftretende Probleme zu identifizieren und neue Funktionen entsprechend ihrer Relevanz zu priorisieren.

**Was wir erfassen:**

- **Tool-Aufrufe:** Wir protokollieren die Namen der aufgerufenen Tools, ob sie erfolgreich waren oder fehlgeschlagen sind, sowie ihre Ausführungszeit. Die an die Tools übergebenen Argumente sowie sämtliche von ihnen zurückgegebenen Daten werden nicht erfasst.
- **API-Anfragen:** Wir protokollieren das für jede Anfrage verwendete Modell, die Dauer der Anfrage und ob sie erfolgreich war. Der Inhalt der Prompts oder Antworten wird nicht erfasst.
- **Sitzungsinformationen:** Wir erfassen Informationen zur Konfiguration der CLI, beispielsweise welche Tools aktiviert sind und welcher Genehmigungsmodus verwendet wird.

**Was wir NICHT erfassen:**

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

**Wie Sie die Erfassung deaktivieren können:**

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

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

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