Configuration de Qwen Code

Niveaux de configuration

La configuration est appliquée selon l’ordre de priorité suivant (les numéros les plus bas sont écrasés par les numéros les plus élevés) :

Fichiers de paramètres

Qwen Code utilise des fichiers de paramètres JSON pour la configuration persistante. Il existe quatre emplacements pour ces fichiers :

Le répertoire .qwen dans votre projet

En plus d’un fichier de paramètres de projet, le répertoire .qwen d’un projet peut contenir d’autres fichiers spécifiques au projet liés au fonctionnement de Qwen Code, tels que :

• Profils de sandbox personnalisés (par ex. .qwen/sandbox-macos-custom.sb, .qwen/sandbox.Dockerfile).
• Agent Skills sous .qwen/skills/ (chaque Skill est un répertoire contenant un SKILL.md).

Migration de la configuration

Qwen Code migre automatiquement les anciens paramètres de configuration vers le nouveau format. Les anciens fichiers de paramètres sont sauvegardés avant la migration. Les paramètres suivants ont été renommés d’une nomenclature négative (disable*) à positive (enable*) :

Politique de consolidation pour disableAutoUpdate et disableUpdateNag

Lorsque les deux anciens paramètres sont présents avec des valeurs différentes, la migration suit cette politique : si soit disableAutoUpdate soit disableUpdateNag est true, alors enableAutoUpdate devient false :

Paramètres disponibles dans settings.json

Les paramètres sont organisés en catégories. La plupart des paramètres doivent être placés dans leur objet de catégorie de niveau supérieur correspondant dans votre fichier settings.json. Quelques paramètres de niveau supérieur comme proxy et plansDirectory restent des clés racines directes pour des raisons de compatibilité.

general

output

ui

ide

privacy

model

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

timeout (délai d’expiration de la requête) :

timeout est le délai d’expiration par requête en millisecondes (par défaut 120000). Définissez-le à 0 pour désactiver le délai d’expiration de la requête — conformément à la convention QWEN_STREAM_IDLE_TIMEOUT_MS=0 — plutôt que d’interrompre la requête. Il peut également être défini via la variable d’environnement QWEN_CODE_API_TIMEOUT_MS. Ceci est distinct de QWEN_STREAM_IDLE_TIMEOUT_MS, qui limite l’inactivité entre les chunks streamés.

max_tokens (limite de tokens en sortie) :

Lorsque ni samplingParams.max_tokens ni QWEN_CODE_MAX_OUTPUT_TOKENS n’est défini, Qwen Code utilise généralement la limite de sortie déclarée du modèle sélectionné comme limite de sortie par défaut de la requête. Si la réponse atteint tout de même cette limite, Qwen Code peut réessayer avec une limite augmentée (avec un plancher de 64K) puis récupérer au fil des tours de continuation.

Pour les fournisseurs compatibles OpenAI, samplingParams sert également d’échappatoire pour le format de requête : lorsqu’il est défini, ses clés sont transmises telles quelles et Qwen Code ne synthétise pas de valeur par défaut pour max_tokens. Utilisez ceci pour les paramètres spécifiques au fournisseur tels que max_completion_tokens.

Pour forcer une limite de sortie fixe, définissez samplingParams.max_tokens dans vos paramètres ou utilisez la variable d’environnement QWEN_CODE_MAX_OUTPUT_TOKENS. Les limites explicites désactivent l’augmentation automatique des tokens en sortie.

toolResultContentFormat :

Contrôle la sérialisation des résultats d’outils contenant uniquement du texte dans les requêtes compatibles OpenAI. La valeur par défaut "parts" conserve la structure standard du tableau de parties de contenu. Définissez "string" uniquement pour les runtimes hérités compatibles OpenAI dont les modèles d’outils ignorent les parties de contenu textuel, comme les anciens modèles GLM-5.1 vLLM/SGLang. Les médias retournés par les outils restent contrôlés par splitToolMedia.

contextWindowSize :

Remplace la taille par défaut de la fenêtre de contexte pour le modèle sélectionné. Qwen Code détermine la fenêtre de contexte en utilisant des valeurs par défaut intégrées basées sur la correspondance du nom du modèle, avec une valeur de secours constante. Utilisez ce paramètre lorsque la limite de contexte effective d’un fournisseur diffère de celle par défaut de Qwen Code. Cette valeur définit la capacité de contexte maximale supposée du modèle, et non une limite de tokens par requête.

Lorsque le modèle sélectionné est défini dans modelProviders, définissez contextWindowSize dans le generationConfig de cette entrée fournisseur au lieu du model.generationConfig de premier niveau. Les entrées de modèle fournisseur sont scellées, donc les paramètres de génération de premier niveau ne remplissent pas les champs fournisseur manquants.

modalities :

Remplace les modalités d’entrée auto-détectées pour le modèle sélectionné. Qwen Code détecte automatiquement les modalités prises en charge (image, PDF, audio, vidéo) en fonction de la correspondance des motifs du nom du modèle. Utilisez ce paramètre lorsque l’auto-détection est incorrecte — par exemple, pour activer pdf pour un modèle qui le prend en charge mais n’est pas reconnu. Format : { "image": true, "pdf": true, "audio": true, "video": true }. Omettez une clé ou définissez-la à false pour les types non pris en charge.

customHeaders :

Vous permet d’ajouter des en-têtes HTTP personnalisés à toutes les requêtes API. Ceci est utile pour le traçage des requêtes, la supervision, le routage de passerelle API, ou lorsque différents modèles nécessitent des en-têtes différents. Pour les modèles de fournisseur, définissez customHeaders dans modelProviders[].generationConfig.customHeaders. Pour les modèles d’exécution sans entrée fournisseur correspondante, définissez-le dans model.generationConfig.customHeaders. Aucune fusion n’est effectuée entre les deux niveaux.

Le champ extra_body vous permet d’ajouter des paramètres personnalisés au corps de la requête envoyé à l’API. Ceci est utile pour les options spécifiques au fournisseur qui ne sont pas couvertes par les champs de configuration standard. Remarque : Ce champ est uniquement pris en charge pour les fournisseurs compatibles OpenAI (openai, qwen-oauth). Il est ignoré pour les fournisseurs Anthropic et Gemini. Pour les modèles de fournisseur, définissez extra_body dans modelProviders[].generationConfig.extra_body. Pour les modèles d’exécution sans entrée fournisseur correspondante, définissez-le dans model.generationConfig.extra_body.

Exemples pour model.openAILoggingDir :

• "~/qwen-logs" - Enregistre les logs dans le répertoire ~/qwen-logs
• "./custom-logs" - Enregistre les logs dans ./custom-logs par rapport au répertoire courant
• "/tmp/openai-logs" - Enregistre les logs dans le chemin absolu /tmp/openai-logs

fastModel

visionModel

voiceModel

modelFallbacks

modelPricing

context

Dépannage des performances de recherche de fichiers

Si vous rencontrez des problèmes de performances avec la recherche de fichiers (par exemple, avec les complétions @), en particulier dans les projets contenant un très grand nombre de fichiers, voici quelques solutions que vous pouvez essayer, par ordre de recommandation :

1. Utiliser un fichier ignore : Créez un fichier .qwenignore ou un fichier ignore personnalisé configuré à la racine de votre projet pour exclure les répertoires contenant un grand nombre de fichiers dont vous n’avez pas besoin de référencer (par exemple, les artefacts de build, les logs, node_modules). Réduire le nombre total de fichiers analysés est le moyen le plus efficace d’améliorer les performances.
2. Désactiver la recherche floue : Si ignorer des fichiers ne suffit pas, vous pouvez désactiver la recherche floue en définissant enableFuzzySearch sur false dans votre fichier settings.json. Cela utilisera un algorithme de correspondance plus simple et non flou, ce qui peut être plus rapide.
3. Désactiver la recherche de fichiers récursive : En dernier recours, vous pouvez désactiver complètement la recherche de fichiers récursive en définissant enableRecursiveFileSearch sur false. Ce sera l’option la plus rapide car elle évite une analyse récursive de votre projet. Cependant, cela signifie que vous devrez saisir le chemin complet des fichiers lors de l’utilisation des complétions @.

tools

memory

Consultez Memory pour plus de détails sur le fonctionnement de l’auto-memory et sur l’utilisation des commandes /memory, /remember et /dream.

permissions

Le système de permissions fournit un contrôle fin sur les outils qui peuvent s’exécuter, ceux qui nécessitent une confirmation et ceux qui sont bloqués.

Priorité de décision (de la plus haute à la plus basse) : deny > ask > allow > (mode par défaut/interactif)

La première règle correspondante l’emporte. Les règles utilisent le format "ToolName" ou "ToolName(specifier)".

Alias des noms d’outils (l’un ou l’autre fonctionne dans les règles) :

Méta-catégories :

Certains noms de règles couvrent automatiquement plusieurs outils :

[!important] Read(/path/**) correspond aux quatre outils de lecture (lecture de fichier, grep, glob et listage de répertoire). Pour restreindre uniquement la lecture de fichiers, utilisez ReadFile(/path/**) ou read_file(/path/**).

Exemples de syntaxe de règles :

Préfixes de motifs de chemin :

Prévention du contournement des commandes shell :

Les règles de permission pour Read, Edit et WebFetch sont également appliquées lorsque l’agent exécute des commandes shell équivalentes. Par exemple, si Read(./.env) est dans deny, l’agent ne peut pas le contourner via cat .env dans une commande shell. Les commandes shell prises en charge incluent cat, grep, curl, wget, cp, mv, rm, chmod, et bien d’autres. Les commandes inconnues/sûres (par ex. git) ne sont pas affectées par les règles de fichiers/réseau.

Migration depuis les paramètres hérités :

Exemple de configuration :

{
  "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] Utilisez /permissions dans le CLI interactif pour afficher, ajouter et supprimer des règles sans modifier settings.json directement.

slashCommands

Contrôle les commandes slash disponibles dans le CLI. Utile pour restreindre la surface de commande dans les déploiements multi-tenant ou en entreprise.

La même denylist peut également être fournie via le flag CLI --disabled-slash-commands (séparés par des virgules ou répétés) et la variable d’environnement QWEN_DISABLED_SLASH_COMMANDS ; les valeurs des trois sources sont fusionnées en union.

Exemple — verrouiller les commandes intégrées pour un déploiement en sandbox :

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

Avec ces valeurs dans un settings.json au niveau système (/etc/qwen-code/settings.json ou QWEN_CODE_SYSTEM_SETTINGS_PATH), les utilisateurs ne peuvent pas réduire la denylist depuis leur propre scope, et les commandes désactivées n’apparaîtront pas dans l’autocomplétion et ne s’exécuteront pas si elles sont tapées.

[!note] Ce paramètre contrôle uniquement les commandes slash (par ex. /auth, /mcp). Il n’affecte pas les permissions des outils — consultez permissions.deny pour cela. Il n’intercepte pas non plus les raccourcis clavier comme Ctrl+C ou Esc.

skills

Contrôle les Skills exposées au modèle.

mcp

lsp

[!warning] Fonctionnalité expérimentale : La prise en charge de LSP est actuellement expérimentale et désactivée par défaut. Activez-la à l’aide du flag de ligne de commande --experimental-lsp.

Le Language Server Protocol (LSP) fournit des fonctionnalités d’intelligence de code telles que la navigation vers la définition, la recherche de références et les diagnostics.

La configuration du serveur LSP s’effectue via des fichiers .lsp.json dans le répertoire racine de votre projet, et non via settings.json. Consultez la documentation LSP pour plus de détails et d’exemples de configuration.

security

advanced

experimental

mcpServers

Configure les connexions à un ou plusieurs serveurs Model-Context Protocol (MCP) pour découvrir et utiliser des outils personnalisés. Qwen Code tente de se connecter à chaque serveur MCP configuré pour découvrir les outils disponibles. Si plusieurs serveurs MCP exposent un outil avec le même nom, les noms des outils seront préfixés par l’alias du serveur que vous avez défini dans la configuration (par exemple, serverAlias__actualToolName) afin d’éviter les conflits. Notez que le système peut supprimer certaines propriétés de schéma des définitions d’outils MCP pour des raisons de compatibilité. Au moins l’un des paramètres command, url ou httpUrl doit être fourni. Si plusieurs sont spécifiés, l’ordre de priorité est httpUrl, puis url, puis command.

telemetry

Configure la journalisation et la collecte de métriques pour Qwen Code. Pour plus d’informations, consultez telemetry.

Exemple de settings.json

Voici un exemple de fichier settings.json avec la structure imbriquée, nouvelle depuis la v0.3.0 :

{
  "proxy": "http://localhost:7890",
  "plansDirectory": "./.qwen/plans",
  "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,
    "includeSensitiveSpanAttributes": false,
    "sensitiveSpanAttributeMaxLength": 1048576
  },
  "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"]
  }
}

Historique du shell

La CLI conserve un historique des commandes shell que vous exécutez. Pour éviter les conflits entre différents projets, cet historique est stocké dans un répertoire spécifique au projet dans le dossier personnel de votre utilisateur.

• Emplacement : ~/.qwen/tmp/<project_hash>/shell_history
  • <project_hash> est un identifiant unique généré à partir du chemin racine de votre projet.
  • L’historique est stocké dans un fichier nommé shell_history.

Variables d’environnement et fichiers .env

Les variables d’environnement sont un moyen courant de configurer les applications, en particulier pour les informations sensibles (comme les tokens) ou pour les paramètres susceptibles de changer d’un environnement à l’autre.

Qwen Code peut charger automatiquement les variables d’environnement depuis les fichiers .env. Pour les variables liées à l’authentification (comme OPENAI_*) et l’approche recommandée avec .qwen/.env, consultez Authentication.

Tableau des variables d’environnement

Arguments de ligne de commande

Les arguments passés directement lors de l’exécution du CLI peuvent remplacer d’autres configurations pour cette session spécifique.

Pour la sélection de l’image du sandbox, l’ordre de priorité est le suivant : --sandbox-image > QWEN_SANDBOX_IMAGE > tools.sandboxImage > image par défaut intégrée.

Tableau des arguments de ligne de commande

Fichiers de contexte (Contexte d’instruction hiérarchique)

Bien qu’ils ne constituent pas strictement une configuration du comportement du CLI, les fichiers de contexte (dont le nom par défaut est QWEN.md, mais configurable via le paramètre context.fileName) sont essentiels pour configurer le contexte d’instruction (également appelé « mémoire »). Cette fonctionnalité puissante vous permet de fournir des instructions spécifiques au projet, des guides de style de code ou toute information contextuelle pertinente à l’IA, afin que ses réponses soient mieux adaptées et plus précises pour vos besoins. Le CLI inclut des éléments d’interface utilisateur, comme un indicateur dans le pied de page affichant le nombre de fichiers de contexte chargés, pour vous tenir informé du contexte actif.

• Objectif : Ces fichiers Markdown contiennent des instructions, des directives ou du contexte dont vous souhaitez que le modèle Qwen ait connaissance lors de vos interactions. Le système est conçu pour gérer ce contexte d’instruction de manière hiérarchique.

Exemple de contenu de fichier de contexte (ex. QWEN.md)

Voici un exemple conceptuel de ce que pourrait contenir un fichier de contexte à la racine d’un projet TypeScript :

# 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 22+.

## 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.

Cet exemple montre comment vous pouvez fournir un contexte général de projet, des conventions de code spécifiques, et même des notes sur des fichiers ou composants particuliers. Plus vos fichiers de contexte sont pertinents et précis, mieux l’IA pourra vous assister. Les fichiers de contexte spécifiques au projet sont fortement recommandés pour établir des conventions et un contexte.

• Chargement hiérarchique et précédence : Le CLI implémente un système de mémoire hiérarchique en chargeant les fichiers de contexte (ex. QWEN.md) depuis plusieurs emplacements. Le contenu des fichiers situés plus bas dans cette liste (plus spécifiques) remplace ou complète généralement le contenu des fichiers situés plus haut (plus généraux). L’ordre exact de concaténation et le contexte final peuvent être inspectés depuis la boîte de dialogue /memory. L’ordre de chargement typique est :
  1. Fichier de contexte global :
     • Emplacement : ~/.qwen/<configured-context-filename> (ex. ~/.qwen/QWEN.md dans votre répertoire personnel).
     • Portée : Fournit les instructions par défaut pour tous vos projets.
  2. Fichiers de contexte de la racine du projet et des ancêtres :
     • Emplacement : Le CLI recherche le fichier de contexte configuré dans le répertoire de travail actuel, puis dans chaque répertoire parent jusqu’à la racine du projet (identifiée par un dossier .git) ou votre répertoire personnel.
     • Portée : Fournit un contexte pertinent pour l’ensemble du projet ou une partie significative de celui-ci.
• Concaténation et indication UI : Le contenu de tous les fichiers de contexte trouvés est concaténé (avec des séparateurs indiquant leur origine et leur chemin) et fourni dans le prompt système. Le pied de page du CLI affiche le nombre de fichiers de contexte chargés, vous donnant un repère visuel rapide sur le contexte d’instruction actif.
• Importation de contenu : Vous pouvez modulariser vos fichiers de contexte en important d’autres fichiers Markdown via la syntaxe @path/to/file.md. Pour plus de détails, consultez la documentation sur la mémoire.
• Commandes pour la gestion de la mémoire :
  • Utilisez /memory pour ouvrir la boîte de dialogue de gestion de la mémoire.
  • Actualisez la mémoire depuis la boîte de dialogue pour réanalyser et recharger les fichiers de contexte depuis tous les emplacements configurés.
  • Consultez la documentation des commandes pour tous les détails sur la commande /memory.

En comprenant et en utilisant ces couches de configuration ainsi que la nature hiérarchique des fichiers de contexte, vous pouvez gérer efficacement la mémoire de l’IA et adapter les réponses de Qwen Code à vos besoins et projets spécifiques.

Sandbox

Qwen Code peut exécuter des opérations potentiellement non sûres (comme des commandes shell et des modifications de fichiers) dans un environnement sandbox pour protéger votre système.

La sandbox est désactivée par défaut, mais vous pouvez l’activer de plusieurs manières :

• En utilisant le flag --sandbox ou -s.
• En définissant la variable d’environnement QWEN_SANDBOX.
• En définissant tools.sandbox dans les paramètres.

⚠️ --yolo n’active pas automatiquement une sandbox. Le mode YOLO approuve uniquement les appels d’outils automatiquement ; l’utilisation de la sandbox doit toujours être activée explicitement via --sandbox, QWEN_SANDBOX ou tools.sandbox. Lors d’exécutions headless / non interactives avec --yolo (ou --approval-mode=yolo) et sans sandbox, le modèle peut exécuter les outils shell, write et edit au niveau de privilège du processus actuel — Qwen Code affiche un avertissement sur stderr dans ce cas. Supprimez-le avec QWEN_CODE_SUPPRESS_YOLO_WARNING=1 une fois que vous avez évalué les compromis.

Par défaut, il utilise une image Docker préconstruite qwen-code-sandbox.

Pour des besoins de sandbox spécifiques au projet, vous pouvez créer un Dockerfile personnalisé à l’emplacement .qwen/sandbox.Dockerfile dans le répertoire racine de votre projet. Ce Dockerfile peut être basé sur l’image de sandbox de base :

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

Lorsque .qwen/sandbox.Dockerfile existe, vous pouvez utiliser la variable d’environnement BUILD_SANDBOX lors de l’exécution de Qwen Code pour construire automatiquement l’image sandbox personnalisée :

BUILD_SANDBOX=1 qwen -s

Statistiques d’utilisation

Pour nous aider à améliorer Qwen Code, nous collectons des statistiques d’utilisation anonymisées. Ces données nous aident à comprendre comment le CLI est utilisé, à identifier les problèmes courants et à prioriser les nouvelles fonctionnalités.

Ce que nous collectons :

• Appels d’outils : Nous enregistrons les noms des outils appelés, s’ils réussissent ou échouent, et le temps nécessaire à leur exécution. Nous ne collectons pas les arguments passés aux outils ni les données qu’ils retournent.
• Requêtes API : Nous enregistrons le modèle utilisé pour chaque requête, la durée de la requête et si elle a réussi. Nous ne collectons pas le contenu des prompts ni des réponses.
• Informations de session : Nous collectons des informations sur la configuration du CLI, telles que les outils activés et le mode d’approbation.

Ce que nous ne collectons PAS :

• Informations personnellement identifiables (PII) : Nous ne collectons aucune information personnelle, telle que votre nom, votre adresse e-mail ou vos clés API.
• Contenu des prompts et des réponses : Nous n’enregistrons pas le contenu de vos prompts ni les réponses du modèle.
• Contenu des fichiers : Nous n’enregistrons pas le contenu des fichiers lus ou écrits par le CLI.

Comment désactiver la collecte :

Vous pouvez désactiver la collecte des statistiques d’utilisation à tout moment en définissant la propriété usageStatisticsEnabled sur false dans la catégorie privacy de votre fichier settings.json :

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