Qwen Code Configuration

Couches de configuration

La configuration est appliquée dans l’ordre de priorité suivant (les numéros inférieurs sont remplacés par les numéros supérieurs) :

Fichiers de paramètres

Qwen Code utilise des fichiers 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, comme :

• Profils sandbox personnalisés (par ex. .qwen/sandbox-macos-custom.sb, .qwen/sandbox.Dockerfile).
• Compétences de l’agent sous .qwen/skills/ (chaque compétence est un répertoire contenant un fichier SKILL.md).

Migration de la configuration

Qwen Code migre automatiquement les paramètres de configuration hérités 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 dénomination négative (disable*) à une dénomination positive (enable*) :

Politique de consolidation pour disableAutoUpdate et disableUpdateNag

Lorsque les deux paramètres hérités sont présents avec des valeurs différentes, la migration suit cette politique : si l’un ou l’autre de disableAutoUpdate ou disableUpdateNag est true, alors enableAutoUpdate devient false :

Paramètres disponibles dans settings.json

Les paramètres sont organisés par catégories. La plupart des paramètres doivent être placés dans leur objet de catégorie de premier niveau correspondant dans votre fichier settings.json. Quelques paramètres de premier niveau 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
      }
    }
  }
}

max_tokens (jetons de sortie adaptatifs) :

Lorsque samplingParams.max_tokens n’est pas défini, Qwen Code utilise une stratégie de jetons de sortie adaptatifs pour optimiser l’utilisation des ressources GPU :

1. Les requêtes commencent avec une limite par défaut de 8K jetons de sortie
2. Si la réponse est tronquée (le modèle atteint la limite), Qwen Code réessaie automatiquement avec 64K jetons
3. La sortie partielle est ignorée et remplacée par la réponse complète de la nouvelle tentative

Ceci est transparent pour les utilisateurs — vous pouvez brièvement voir un indicateur de nouvelle tentative en cas d’escalade. Étant donné que 99 % des réponses font moins de 5K jetons, la nouvelle tentative est rare (<1 % des requêtes).

Pour modifier ce comportement, définissez samplingParams.max_tokens dans vos paramètres ou utilisez la variable d’environnement QWEN_CODE_MAX_OUTPUT_TOKENS.

toolResultContentFormat :

Contrôle la manière dont les résultats d’outil textuels sont sérialisés dans les requêtes compatibles OpenAI. La valeur par défaut "parts" conserve la forme standard du tableau de parties de contenu. Définissez "string" uniquement pour les exécutions héritées compatibles OpenAI dont les modèles d’outil ignorent les parties de contenu textuel, comme les anciens modèles GLM-5.1 vLLM/SGLang. Les médias renvoyés par l’outil sont toujours contrôlés par splitToolMedia.

contextWindowSize :

Remplace la taille de fenêtre de contexte par défaut pour le modèle sélectionné. Qwen Code détermine la fenêtre de contexte à l’aide de valeurs par défaut intégrées basées sur la correspondance du nom du modèle, avec une valeur de repli 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é maximale de contexte supposée du modèle, et non une limite de jetons par requête.

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

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 de 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 sur false pour les types non pris en charge.

customHeaders :

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 surveillance, 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 de fournisseur correspondante, définissez-le dans model.generationConfig.customHeaders. Aucune fusion n’a lieu entre les deux niveaux.

Le champ extra_body vous permet d’ajouter des paramètres personnalisés au corps de la requête envoyée à 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 n’est pris en charge que 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 de fournisseur correspondante, définissez-le dans model.generationConfig.extra_body.

Exemples de model.openAILoggingDir :

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

fastModel

context

Dépannage des performances de la recherche de fichiers

Si vous rencontrez des problèmes de performances lors de la recherche de fichiers (par exemple avec les complétions @), en particulier dans des projets comportant un très grand nombre de fichiers, voici quelques pistes à essayer, classées par ordre de recommandation :

1. Utiliser un fichier d’ignorance : Créez un fichier .qwenignore ou un fichier d’ignorance personnalisé configuré à la racine de votre projet pour exclure les répertoires contenant un grand nombre de fichiers dont vous n’avez pas besoin (par exemple les artefacts de construction, les journaux, node_modules). Réduire le nombre total de fichiers parcourus 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 récursive de fichiers : En dernier recours, vous pouvez désactiver complètement la recherche récursive de fichiers en définissant enableRecursiveFileSearch sur false. Ce sera l’option la plus rapide car elle évite un parcours récursif de votre projet. Cela signifie cependant que vous devrez saisir le chemin complet des fichiers lors de l’utilisation des complétions @.

outils

memory

Voir Mémoire pour les détails sur le fonctionnement de la mémoire automatique et comment utiliser les commandes /memory, /remember et /dream.

permissions

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

Priorité de décision (la plus élevée en premier) : 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 de noms d’outils (n’importe lequel 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 fichier, utilisez ReadFile(/path/**) ou read_file(/path/**).

Exemples de syntaxe de règle :

Prévention du contournement des commandes shell :

Les règles d’autorisation 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 voir, ajouter et supprimer des règles sans modifier directement settings.json.

slashCommands

Contrôle quelles commandes slash sont disponibles dans le CLI. Utile pour verrouiller la surface de commande dans les déploiements multi-locataires ou d’entreprise.

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

Exemple — verrouiller les commandes intégrées pour un déploiement en bac à sable :

{
  "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 liste de blocage depuis leur propre portée, et les commandes désactivées n’apparaîtront pas dans l’autocomplétion et ne s’exécuteront pas lorsqu’elles sont tapées.

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

mcp

lsp

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

Le Language Server Protocol (LSP) offre des fonctionnalités d’intelligence de code comme aller à la définition, trouver les références et les diagnostics.

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

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 portant 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 éléments command, url ou httpUrl doit être fourni. Si plusieurs sont spécifiés, l’ordre de priorité est httpUrl, puis url, puis command.

télémétrie

Configure la journalisation et la collecte de métriques pour Qwen Code. Pour plus d’informations, voir télémétrie.

Exemple 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
  },
  "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

Le 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 à l’intérieur de votre dossier personnel.

• 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 & Fichiers .env

Les variables d’environnement sont un moyen courant de configurer les applications, en particulier pour les informations sensibles (comme les jetons) ou pour les paramètres qui peuvent changer selon l’environnement.

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

Tableau des variables d’environnement

Arguments en ligne de commande

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

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

Tableau des arguments en ligne de commande

Fichiers de contexte (Contexte instructionnel hiérarchique)

Bien qu’il ne s’agisse pas strictement d’une configuration du comportement du CLI, les fichiers de contexte (par défaut QWEN.md mais configurables via le paramètre context.fileName) sont essentiels pour configurer le contexte instructionnel (aussi appelé « mémoire »). Cette fonctionnalité puissante vous permet de donner des instructions spécifiques au projet, des guides de style de codage ou toute information contextuelle pertinente à l’IA, rendant ses réponses plus adaptées et précises à vos besoins. Le CLI inclut des éléments d’interface utilisateur, comme un indicateur dans le pied de page indiquant 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 un contexte que vous souhaitez que le modèle Qwen connaisse lors de vos interactions. Le système est conçu pour gérer ce contexte instructionnel de manière hiérarchique.

Exemple de contenu d’un fichier de contexte (par ex. QWEN.md)

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

# 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 codage 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 peut vous assister. Les fichiers de contexte spécifiques au projet sont fortement encouragé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 (par ex., QWEN.md) depuis plusieurs emplacements. Le contenu des fichiers plus bas dans cette liste (plus spécifiques) remplace ou complète généralement le contenu des fichiers 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> (par ex., ~/.qwen/QWEN.md dans votre répertoire personnel).
     • Portée : Fournit des instructions par défaut pour tous vos projets.
  2. Fichiers de contexte de la racine du projet et des dossiers parents :
     • 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 dans l’interface utilisateur : 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 aperçu visuel rapide du contexte instructionnel actif.
• Importation de contenu : Vous pouvez modulariser vos fichiers de contexte en important d’autres fichiers Markdown à l’aide de la syntaxe @path/to/file.md. Pour plus de détails, consultez la documentation 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 rescanner 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 et 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 dangereuses (comme des commandes shell et des modifications de fichiers) dans un environnement sandboxé pour protéger votre système.

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

• En utilisant l’option --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 un sandbox. Le mode YOLO approuve automatiquement les appels d’outils ; l’utilisation d’un sandbox doit toujours être choisie via --sandbox, QWEN_SANDBOX ou tools.sandbox. Dans les exécutions headless / non interactives avec --yolo (ou --approval-mode=yolo) et sans sandbox, le modèle peut exécuter les outils shell, d’écriture et d’édition au niveau de privilège du processus actuel — Qwen Code imprime un avertissement sur stderr dans ce cas. Supprimez-le avec QWEN_CODE_SUPPRESS_YOLO_WARNING=1 une fois que vous avez examiné le compromis. Par défaut, il utilise une image Docker pré-construite qwen-code-sandbox.

Pour les besoins de sandboxing spécifiques à un 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 sandbox de base :

FROM qwen-code-sandbox
# Ajoutez ici vos dépendances ou configurations personnalisées
# Par exemple :
# 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 l’interface CLI est utilisée, à 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, qu’ils réussissent ou échouent, et leur durée d’exécution. Nous ne collectons pas les arguments passés aux outils ni les données qu’ils renvoient.
• 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 invites ou des réponses.
• Informations de session : Nous collectons des informations sur la configuration de l’interface CLI, telles que les outils activés et le mode d’approbation.

Ce que nous NE collectons PAS :

• Informations personnelles identifiables (PII) : Nous ne collectons aucune information personnelle, comme votre nom, votre adresse e-mail ou vos clés API.
• Contenu des invites et des réponses : Nous ne journalisons pas le contenu de vos invites ni les réponses du modèle.
• Contenu des fichiers : Nous ne journalisons pas le contenu des fichiers lus ou écrits par l’interface CLI.

Comment se désinscrire :

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

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