Qwen Code-Konfiguration

Konfigurationsebenen

Die Konfiguration wird in folgender Prioritätsreihenfolge angewendet (niedrigere Nummern werden durch höhere überschrieben):

Einstellungsdateien

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

Das .qwen-Verzeichnis in deinem Projekt

Zusätzlich zu einer Projekteinstellungsdatei kann das .qwen-Verzeichnis eines Projekts weitere projektspezifische Dateien im Zusammenhang mit dem Betrieb von Qwen Code enthalten, wie z. B.:

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

Konfigurationsmigration

Qwen Code migriert veraltete Konfigurationseinstellungen automatisch in das neue Format. Alte Einstellungsdateien werden vor der Migration gesichert. Die folgenden Einstellungen wurden von negativer (disable*) zu positiver (enable*) Benennung umbenannt:

Zusammenführungsrichtlinie für disableAutoUpdate und disableUpdateNag

Wenn beide veralteten Einstellungen mit unterschiedlichen Werten vorhanden sind, folgt die Migration dieser Richtlinie: Wenn entweder disableAutoUpdate oder disableUpdateNag auf true gesetzt ist, wird enableAutoUpdate auf false gesetzt:

Verfügbare Einstellungen in settings.json

Die Einstellungen sind in Kategorien organisiert. Die meisten Einstellungen sollten innerhalb ihres entsprechenden Top-Level-Kategorieobjekts in deiner settings.json-Datei platziert werden. Einige Kompatibilitätseinstellungen, wie proxy, sind Top-Level-Keys.

top-level

general

output

ui

ide

privacy

model

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

max_tokens (adaptive Output-Tokens):

Wenn samplingParams.max_tokens nicht gesetzt ist, verwendet Qwen Code eine adaptive Output-Token-Strategie zur Optimierung der GPU-Ressourcennutzung:

1. Anfragen starten mit einem Standardlimit von 8K Output-Tokens
2. Wenn die Antwort abgeschnitten wird (das Modell erreicht das Limit), wiederholt Qwen Code die Anfrage automatisch mit 64K Tokens
3. Die Teil-Ausgabe wird verworfen und durch die vollständige Antwort aus dem Retry ersetzt

Dies ist für Benutzer transparent – du siehst möglicherweise kurz einen Retry-Indikator, wenn eine Eskalation erfolgt. Da 99 % der Antworten unter 5K Tokens liegen, erfolgt der Retry selten (<1 % der Anfragen).

Um dieses Verhalten zu überschreiben, setze entweder samplingParams.max_tokens in deinen Einstellungen oder verwende die Umgebungsvariable QWEN_CODE_MAX_OUTPUT_TOKENS.

contextWindowSize:

Überschreibt die standardmäßige Context-Window-Größe für das ausgewählte Modell. Qwen Code bestimmt die Context-Window-Größe anhand interner Standards basierend auf Modellnamens-Matching, mit einem konstanten Fallback-Wert. Verwende diese Einstellung, wenn das effektive Context-Limit eines Providers von Qwen Codes Standard abweicht. Dieser Wert definiert die angenommene maximale Context-Kapazität des Modells, nicht ein Token-Limit pro Anfrage.

modalities:

Überschreibt die automatisch erkannten Eingabemodalitäten für das ausgewählte Modell. Qwen Code erkennt automatisch unterstützte Modalitäten (Bild, PDF, Audio, Video) basierend auf Modellnamens-Pattern-Matching. Verwende diese Einstellung, wenn die Auto-Erkennung falsch ist – z. B. um pdf für ein Modell zu aktivieren, das es unterstützt, aber nicht erkannt wird. Format: { "image": true, "pdf": true, "audio": true, "video": true }. Lasse einen Key weg oder setze ihn auf false für nicht unterstützte Typen.

customHeaders:

Ermöglicht das Hinzufügen benutzerdefinierter HTTP-Header zu allen API-Anfragen. 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 kein Merging zwischen den beiden Ebenen.

Das extra_body-Feld ermöglicht das Hinzufügen benutzerdefinierter Parameter zum Request-Body, der an die API gesendet wird. Dies ist nützlich für Provider-spezifische Optionen, die nicht von den Standardkonfigurationsfeldern abgedeckt werden. Hinweis: Dieses Feld wird nur für OpenAI-kompatible Provider (openai, qwen-oauth) unterstützt. Es wird für Anthropic- und Gemini-Provider ignoriert. Wenn extra_body in modelProviders[].generationConfig.extra_body definiert ist, wird es direkt verwendet; andernfalls werden Werte aus model.generationConfig.extra_body verwendet.

Beispiele für model.openAILoggingDir:

• "~/qwen-logs" - Logs im ~/qwen-logs-Verzeichnis
• "./custom-logs" - Logs in ./custom-logs relativ zum aktuellen Verzeichnis
• "/tmp/openai-logs" - Logs im absoluten Pfad /tmp/openai-logs

fastModel

context

Fehlerbehebung bei der Dateisuchleistung

Wenn du Leistungsprobleme bei der Dateisuche (z. B. mit @-Vervollständigungen) hast, insbesondere in Projekten mit sehr vielen Dateien, kannst du folgende Schritte in empfohlener Reihenfolge ausprobieren:

1. Verwende .qwenignore: Erstelle eine .qwenignore-Datei im Projektstamm, um Verzeichnisse auszuschließen, die viele Dateien enthalten, auf die du nicht verweisen musst (z. B. Build-Artefakte, Logs, node_modules). Die Reduzierung der insgesamt durchsuchten Dateien ist der effektivste Weg, die Leistung zu verbessern.
2. Deaktiviere Fuzzy Search: Wenn das Ignorieren von Dateien nicht ausreicht, kannst du die Fuzzy-Suche deaktivieren, indem du enableFuzzySearch in deiner settings.json-Datei auf false setzt. Dies verwendet einen einfacheren, nicht-fuzzy Matching-Algorithmus, der schneller sein kann.
3. Deaktiviere rekursive Dateisuche: Als letzten Ausweg kannst du die rekursive Dateisuche vollständig deaktivieren, indem du enableRecursiveFileSearch auf false setzt. Dies ist die schnellste Option, da sie einen rekursiven Scan deines Projekts vermeidet. Allerdings musst du dann bei @-Vervollständigungen den vollständigen Pfad zu Dateien eingeben.

tools

memory

Siehe Memory für Details zur Funktionsweise von Auto-Memory und zur Verwendung der /memory-, /remember- und /dream-Befehle.

permissions

Das Berechtigungssystem bietet feingranulare Kontrolle darüber, welche Tools ausgeführt werden können, welche eine Bestätigung erfordern und welche blockiert sind.

Entscheidungspriorität (höchste zuerst): deny > ask > allow > (Standard/interaktiver Modus)

Die erste passende Regel gewinnt. Regeln verwenden das Format "ToolName" oder "ToolName(specifier)".

Tool-Namen-Aliase (alle diese funktionieren in Regeln):

Meta-Kategorien:

Einige Regelnamen decken automatisch mehrere Tools ab:

[!important] Read(/path/**) matcht alle vier Read-Tools (Dateilesen, Grep, Glob und Verzeichnisauflistung). Um nur das Dateilesen einzuschränken, verwende ReadFile(/path/**) oder read_file(/path/**).

Beispiele für Regelsyntax:

Pfad-Präfixe für Patterns:

Verhinderung von Shell-Befehls-Umgehungen:

Berechtigungsregeln für Read, Edit und WebFetch werden auch erzwungen, wenn der Agent äquivalente Shell-Befehle ausführt. Wenn beispielsweise Read(./.env) in deny steht, kann der Agent dies nicht über cat .env in einem Shell-Befehl umgehen. Unterstützte Shell-Befehle umfassen cat, grep, curl, wget, cp, mv, rm, chmod und viele mehr. Unbekannte/sichere Befehle (z. B. git) werden von Datei-/Netzwerkregeln nicht beeinflusst.

Migration von veralteten Einstellungen:

Beispielkonfiguration:

{
  "permissions": {
    "allow": ["Bash(git *)", "Bash(npm run *)", "Read(//Users/alice/code/**)"],
    "ask": ["Bash(git push *)", "Edit"],
    "deny": ["Bash(rm -rf *)", "Read(.env)", "WebFetch(malicious.com)"]
  }
}

[!tip] Verwende /permissions in der interaktiven CLI, um Regeln anzuzeigen, hinzuzufügen und zu entfernen, ohne settings.json direkt zu bearbeiten.

slashCommands

Steuert, welche Slash-Befehle in der CLI verfügbar sind. Nützlich zum Einschränken der Befehlsoberfläche in Multi-Tenant- oder Enterprise-Deployments.

Die gleiche Denylist kann auch über das --disabled-slash-commands-CLI-Flag (kommagetrennt oder wiederholt) und die QWEN_DISABLED_SLASH_COMMANDS-Umgebungsvariable bereitgestellt werden; Werte aus allen drei Quellen werden vereinigt.

Beispiel — Eingebaute Befehle für ein sandboxed Deployment sperren:

{
  "slashCommands": {
    "disabled": ["auth", "mcp", "extensions", "ide", "quit"]
  }
}

Mit diesen Werten in einer systemweiten settings.json (/etc/qwen-code/settings.json oder QWEN_CODE_SYSTEM_SETTINGS_PATH) können Benutzer die Denylist nicht aus ihrem eigenen Scope heraus verkleinern, und die deaktivierten Befehle erscheinen weder in der Autovervollständigung noch werden sie bei Eingabe ausgeführt.

[!note] Diese Einstellung betrifft nur Slash-Befehle (z. B. /auth, /mcp). Sie hat keinen Einfluss auf Tool-Berechtigungen – siehe dafür permissions.deny. Sie fängt auch keine Tastenkürzel wie Ctrl+C oder Esc ab.

mcp

lsp

[!warning] Experimentelles Feature: LSP-Unterstützung ist derzeit experimentell und standardmäßig deaktiviert. Aktiviere sie mit dem --experimental-lsp-Befehlszeilenflag.

Das Language Server Protocol (LSP) bietet Code-Intelligence-Features wie Go-to-Definition, Referenzen finden und Diagnosen.

Die LSP-Serverkonfiguration erfolgt über .lsp.json-Dateien in deinem Projektstammverzeichnis, nicht über settings.json. Siehe die LSP-Dokumentation für Konfigurationsdetails und Beispiele.

security

advanced

mcpServers

Konfiguriert Verbindungen zu einem oder mehreren Model-Context Protocol (MCP)-Servern zum Entdecken und Verwenden 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 Tool-Namen mit dem Server-Alias, den du in der Konfiguration definiert hast, präfixiert (z. B. serverAlias__actualToolName), um Konflikte zu vermeiden. Beachte, dass das System bestimmte Schema-Eigenschaften aus MCP-Tool-Definitionen zur Kompatibilität entfernen kann. Mindestens einer der Werte command, url oder httpUrl muss angegeben werden. Wenn mehrere angegeben sind, ist die Prioritätsreihenfolge httpUrl, dann url, dann command.

telemetry

Konfiguriert Logging und Metrik-Sammlung für Qwen Code. Weitere Informationen siehe telemetry.

Beispiel für settings.json

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

{
  "proxy": "http://localhost:7890",
  "general": {
    "vimMode": true,
    "preferredEditor": "code"
  },
  "ui": {
    "theme": "GitHub",
    "hideTips": false,
    "customWittyPhrases": [
      "You forget a thousand things every day. Make sure this is one of 'em",
      "Connecting to AGI"
    ]
  },
  "tools": {
    "approvalMode": "yolo",
    "sandbox": "docker",
    "sandboxImage": "ghcr.io/qwenlm/qwen-code:0.14.1",
    "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 dir ausgeführten Shell-Befehle. Um Konflikte zwischen verschiedenen Projekten zu vermeiden, wird dieser Verlauf in einem projektspezifischen Verzeichnis innerhalb deines Benutzer-Home-Ordners gespeichert.

• Speicherort: ~/.qwen/tmp/<project_hash>/shell_history
  • <project_hash> ist ein eindeutiger Identifier, der aus dem Root-Pfad deines Projekts generiert wird.
  • Der Verlauf wird in einer Datei namens shell_history gespeichert.

Umgebungsvariablen & .env-Dateien

Umgebungsvariablen sind eine gängige Methode zur Konfiguration von Anwendungen, insbesondere für sensible Informationen (wie Tokens) oder für Einstellungen, die sich zwischen Umgebungen ändern können.

Qwen Code kann Umgebungsvariablen automatisch aus .env-Dateien laden. Für authentifizierungsbezogene Variablen (wie OPENAI_*) und den empfohlenen .qwen/.env-Ansatz siehe Authentication.

Tabelle der Umgebungsvariablen

Befehlszeilenargumente

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

Für die Sandbox-Image-Auswahl gilt folgende Priorität: --sandbox-image > QWEN_SANDBOX_IMAGE > tools.sandboxImage > integriertes Standard-Image.

Tabelle der Befehlszeilenargumente

Kontextdateien (Hierarchischer Instruktionskontext)

Obwohl sie nicht streng genommen zur Konfiguration des CLI-Verhaltens gehören, sind Kontextdateien (standardmäßig QWEN.md, aber konfigurierbar über die context.fileName-Einstellung) entscheidend für die Konfiguration des Instruktionskontexts (auch als „Memory” bezeichnet). Dieses leistungsstarke Feature ermöglicht es dir, projektspezifische Anweisungen, Coding-Style-Guides oder relevante Hintergrundinformationen für die KI bereitzustellen, wodurch ihre Antworten gezielter und präziser auf deine Bedürfnisse zugeschnitten werden. Die CLI enthält UI-Elemente, wie einen Indikator in der Fußzeile, der die Anzahl der geladenen Kontextdateien anzeigt, um dich über den aktiven Kontext zu informieren.

• Zweck: Diese Markdown-Dateien enthalten Anweisungen, Richtlinien oder Kontext, den du dem Qwen-Modell während deiner Interaktionen zur Verfügung stellen möchtest. Das System ist darauf ausgelegt, diesen Instruktionskontext hierarchisch zu verwalten.

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

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

# Project: My Awesome TypeScript Library

## General Instructions:
- When generating new TypeScript code, please follow the existing coding style.
- Ensure all new functions and classes have JSDoc comments.
- Prefer functional programming paradigms where appropriate.
- All code should be compatible with TypeScript 5.0 and Node.js 20+.

## Coding Style:
- Use 2 spaces for indentation.
- Interface names should be prefixed with `I` (e.g., `IUserService`).
- Private class members should be prefixed with an underscore (`_`).
- Always use strict equality (`===` and `!==`).

## Specific Component: `src/api/client.ts`
- This file handles all outbound API requests.
- When adding new API call functions, ensure they include robust error handling and logging.
- Use the existing `fetchWithRetry` utility for all GET requests.

## Regarding Dependencies:
- Avoid introducing new external dependencies unless absolutely necessary.
- If a new dependency is required, please state the reason.

Dieses Beispiel zeigt, wie du allgemeinen Projektkontext, spezifische Coding-Konventionen und sogar Notizen zu bestimmten Dateien oder Komponenten bereitstellen kannst. Je relevanter und präziser deine Kontextdateien sind, desto besser kann die KI dich unterstützen. Projektspezifische Kontextdateien werden dringend empfohlen, um Konventionen und Kontext festzulegen.

• Hierarchisches Laden und Priorität: Die CLI implementiert ein hierarchisches Memory-System, indem sie Kontextdateien (z. B. QWEN.md) aus mehreren Speicherorten lädt. Inhalte von Dateien, die weiter unten in dieser Liste stehen (spezifischer), überschreiben oder ergänzen typischerweise Inhalte von Dateien weiter oben (allgemeiner). Die genaue Verkettungsreihenfolge und der finale Kontext können mit dem /memory show-Befehl inspiziert werden. Die typische Ladereihenfolge ist:
  1. Globale Kontextdatei:
     • Speicherort: ~/.qwen/<configured-context-filename> (z. B. ~/.qwen/QWEN.md in deinem Benutzer-Home-Verzeichnis).
     • Scope: Bietet Standardanweisungen für alle deine Projekte.
  2. Projektstamm- & Vorfahren-Kontextdateien:
     • Speicherort: Die CLI sucht nach der konfigurierten Kontextdatei im aktuellen Arbeitsverzeichnis und dann in jedem übergeordneten Verzeichnis bis entweder zum Projektstamm (identifiziert durch einen .git-Ordner) oder deinem Home-Verzeichnis.
     • Scope: Bietet Kontext, der für das gesamte Projekt oder einen signifikanten Teil davon relevant ist.
• Verkettung & UI-Indikator: Die Inhalte aller gefundenen Kontextdateien werden verkettet (mit Trennzeichen, die ihre Herkunft und ihren Pfad angeben) und als Teil des System-Prompts bereitgestellt. Die CLI-Fußzeile zeigt die Anzahl der geladenen Kontextdateien an, was dir einen schnellen visuellen Hinweis auf den aktiven Instruktionskontext gibt.
• Importieren von Inhalten: Du kannst deine Kontextdateien modularisieren, indem du andere Markdown-Dateien mit der @path/to/file.md-Syntax importierst. Für weitere Details siehe die Memory Import Processor-Dokumentation.
• Befehle zur Memory-Verwaltung:
  • Verwende /memory refresh, um einen erneuten Scan und Neuladen aller Kontextdateien aus allen konfigurierten Speicherorten zu erzwingen. Dies aktualisiert den Instruktionskontext der KI.
  • Verwende /memory show, um den kombinierten Instruktionskontext anzuzeigen, der aktuell geladen ist, damit du die Hierarchie und den von der KI verwendeten Inhalt überprüfen kannst.
  • Siehe die Commands-Dokumentation für vollständige Details zum /memory-Befehl und seinen Sub-Befehlen (show und refresh).

Indem du diese Konfigurationsebenen und die hierarchische Natur von Kontextdateien verstehst und nutzt, kannst du das Memory der KI effektiv verwalten und die Antworten von Qwen Code gezielt auf deine spezifischen Anforderungen und Projekte zuschneiden.

Sandbox

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

Sandbox ist standardmäßig deaktiviert, kann aber auf verschiedene Weise aktiviert werden:

• Verwendung des --sandbox- oder -s-Flags.
• Setzen der QWEN_SANDBOX-Umgebungsvariable.
• Sandbox ist standardmäßig aktiviert, wenn --yolo oder --approval-mode=yolo verwendet wird.

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

Für projektspezifische Sandbox-Anforderungen kannst du ein benutzerdefiniertes Dockerfile unter .qwen/sandbox.Dockerfile im Stammverzeichnis deines Projekts erstellen. Dieses Dockerfile kann auf dem Basis-Sandbox-Image aufbauen:

FROM qwen-code-sandbox
# Add your custom dependencies or configurations here
# For example:
# RUN apt-get update && apt-get install -y some-package
# COPY ./my-config /app/my-config

Wenn .qwen/sandbox.Dockerfile existiert, kannst du beim Ausführen von Qwen Code die BUILD_SANDBOX-Umgebungsvariable verwenden, um das benutzerdefinierte Sandbox-Image automatisch zu bauen:

BUILD_SANDBOX=1 qwen -s

Nutzungsstatistiken

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

Was wir sammeln:

• Tool-Aufrufe: Wir loggen die Namen der aufgerufenen Tools, ob sie erfolgreich waren oder fehlgeschlagen sind, und wie lange ihre Ausführung gedauert hat. Wir sammeln nicht die an die Tools übergebenen Argumente oder von ihnen zurückgegebene Daten.
• API-Anfragen: Wir loggen das für jede Anfrage verwendete Modell, die Dauer der Anfrage und ob sie erfolgreich war. Wir sammeln nicht den Inhalt der Prompts oder Antworten.
• Sitzungsinformationen: Wir sammeln Informationen zur Konfiguration der CLI, wie die aktivierten Tools und den Genehmigungsmodus.

Was wir NICHT sammeln:

• Personenbezogene Daten (PII): Wir sammeln keine persönlichen Informationen wie deinen Namen, deine E-Mail-Adresse oder API-Keys.
• Prompt- und Antwortinhalt: Wir loggen nicht den Inhalt deiner Prompts oder die Antworten des Modells.
• Dateiinhalte: Wir loggen nicht den Inhalt von Dateien, die von der CLI gelesen oder geschrieben werden.

So kannst du dich abmelden:

Du kannst der Sammlung von Nutzungsstatistiken jederzeit widersprechen, indem du die usageStatisticsEnabled-Eigenschaft unter der privacy-Kategorie in deiner settings.json-Datei auf false setzt:

{
  "privacy": {
    "usageStatisticsEnabled": false
  }
}