Configuration de Qwen Code

Couches de configuration

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

Fichiers de configuration

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 configuration du 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 sandbox personnalisés (par exemple .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 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 nomenclature négative (disable*) à 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 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
      }
    }
  }
}

max_tokens (jetons de sortie adaptatifs) :

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

1. Les requêtes démarrent 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 relance automatiquement avec 64K jetons
3. La sortie partielle est ignorée et remplacée par la réponse complète de la nouvelle tentative

Ce processus est transparent pour l’utilisateur — vous pouvez brièvement voir un indicateur de nouvelle tentative en cas d’escalade. Comme 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 façon dont les résultats d’outils textuels sont sérialisés dans les requêtes compatibles OpenAI. La valeur par défaut "parts" conserve la structure standard de tableau de parties de contenu. Définissez "string" uniquement pour les environnements d’exécution compatibles OpenAI hérités dont les templates d’outils ignorent les parties de contenu textuel, comme les anciens templates GLM-5.1 vLLM/SGLang. Les médias renvoyés par les outils 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 en utilisant les 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 la valeur 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 jetons par requête.

Lorsque le modèle sélectionné est défini dans modelProviders, définissez contextWindowSize dans l’entrée generationConfig de ce fournisseur plutôt que dans le model.generationConfig de haut niveau. Les entrées de modèle de fournisseur sont scellées, donc les paramètres de génération de haut niveau ne remplissent pas les champs manquants du fournisseur.

modalities :

Remplace les modalités d’entrée détectées automatiquement 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 du nom du modèle. Utilisez ce paramètre lorsque la détection automatique 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. 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’est effectuée entre les deux niveaux.

Le champ extra_body permet d’ajouter des paramètres personnalisés au corps de la requête envoyée à l’API. Utile pour des 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" - Journalise dans le répertoire ~/qwen-logs
• "./custom-logs" - Journalise dans ./custom-logs relatif au répertoire actuel
• "/tmp/openai-logs" - Journalise dans le chemin absolu /tmp/openai-logs

fastModel

context

Résolution des problèmes de 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 avec un très grand nombre de fichiers, voici quelques pistes à essayer, par ordre de recommandation :

1. Utilisez un fichier d’ignor : Créez un fichier .qwenignore ou un fichier d’ignor personnalisé configuré à la racine de votre projet pour exclure les répertoires contenant un grand nombre de fichiers que vous n’avez pas besoin de référencer (par exemple, artefacts de build, journaux, node_modules). Réduire le nombre total de fichiers parcourus est le moyen le plus efficace d’améliorer les performances.
2. Désactivez la recherche floue : Si l’ignor de 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, non flou, qui peut être plus rapide.
3. Désactivez 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. Cependant, cela signifie que vous devrez saisir le chemin complet des fichiers lors de l’utilisation des complétions @.

tools

mémoire

Voir Mémoire pour les détails sur le fonctionnement de la mémoire automatique et l’utilisation des commandes /memory, /remember et /dream.

permissions

Le système de permissions offre un contrôle fin sur les outils autorisés, ceux nécessitant une confirmation et ceux bloqués.

Priorité de décision (la plus élevée en premier) : deny > ask > allow > (défaut/mode interactif)

La première règle correspondante l’emporte. Les règles utilisent le format "NomOutil" ou "NomOutil(préciseur)".

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(/chemin/**) correspond aux quatre outils de lecture (lecture de fichier, grep, glob et liste de répertoires). Pour restreindre uniquement la lecture de fichiers, utilisez ReadFile(/chemin/**) ou read_file(/chemin/**).

Exemples de syntaxe de règles :

Préfixes de motifs de chemin :

Prévention du contournement des commandes shell :

Les règles de permissions 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 contourner cela 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 exemple 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 éditer directement settings.json.

slashCommands

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

La même liste de blocage peut également être fournie via le drapeau 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 fichier settings.json de 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 contexte, et les commandes désactivées n’apparaîtront pas dans l’autocomplétion ni ne s’exécuteront lorsqu’elles seront tapées.

[!note] Ce paramètre ne concerne que les commandes slash (par exemple /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 Echap.

mcp

lsp

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

Language Server Protocol (LSP) fournit 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. Voir 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 avec le même nom, les noms d’outils seront préfixés par l’alias du serveur que vous avez défini dans la configuration (par exemple, aliasServeur__nomOutilRéel) pour é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 de 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, consultez télémétrie.

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": [
      "Vous oubliez mille choses chaque jour. Assurez-vous que celle-ci en fait partie.",
      "Connexion à l'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 des commandes 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 dans le dossier personnel de l’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 jetons) ou pour les paramètres qui peuvent varier entre les environnements.

Qwen Code peut charger automatiquement les variables d’environnement à partir de 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 surcharger les autres configurations pour cette session spécifique.

Pour la sélection de l’image sandbox, la priorité est : --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 de la 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 (également 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 de contexte pertinente à l’IA, rendant ses réponses plus adaptées et précises à vos besoins. La 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 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 de fichier de contexte (p. 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, plus l’IA peut vous aider efficacement. 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 : La CLI implémente un système de mémoire hiérarchique en chargeant les fichiers de contexte (par exemple, 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 le suivant :
  1. Fichier de contexte global :
     • Emplacement : ~/.qwen/<nom-du-fichier-de-contexte-configuré> (par exemple, ~/.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 répertoires parents :
     • Emplacement : La CLI cherche 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 indicateur 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 de la 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 en utilisant la syntaxe @chemin/vers/fichier.md. Pour plus de détails, consultez la documentation sur la mémoire.
• Commandes de gestion de la mémoire :
  • Utilisez /memory pour ouvrir la boîte de dialogue de gestion de la mémoire.
  • Rafraîchissez la mémoire depuis la boîte de dialogue pour re-scanner et recharger les fichiers de contexte depuis tous les emplacements configurés.
  • Consultez la documentation sur les commandes pour plus de 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.

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

• En utilisant le drapeau --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 se contente d’approuver automatiquement les appels d’outils ; le sandboxing doit toujours être activé via --sandbox, QWEN_SANDBOX ou tools.sandbox. Dans les exécutions sans tête / 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 affiche un avertissement sur stderr dans ce cas. Supprimez-le avec QWEN_CODE_SUPPRESS_YOLO_WARNING=1 après avoir examiné le compromis.

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

Pour des besoins de sandboxing spécifiques au projet, vous pouvez créer un Dockerfile personnalisé dans .qwen/sandbox.Dockerfile à la racine de votre projet. Ce Dockerfile peut être basé sur l’image 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 la 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, s’ils réussissent ou échouent, et le temps qu’ils prennent pour s’exécuter. 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 ou des réponses.
• Informations de session : Nous collectons des informations sur la configuration de la CLI, comme 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, adresse e-mail ou clés API.
• Contenu des prompts et des réponses : Nous ne journalisons pas le contenu de vos prompts ni les réponses du modèle.
• Contenu des fichiers : Nous ne journalisons pas le contenu des fichiers lus ou écrits par la CLI.

Comment se désinscrire :

Vous pouvez vous désinscrire de la collecte de 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
  }
}