Configuration de Qwen Code

Niveaux de configuration

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

Fichiers de paramètres

Qwen Code utilise des fichiers de paramètres JSON pour la configuration persistante. Ces fichiers peuvent se trouver à quatre emplacements :

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 sandbox personnalisés (par ex. .qwen/sandbox-macos-custom.sb, .qwen/sandbox.Dockerfile).
• Compétences d’agent (Agent Skills) sous .qwen/skills/ (chaque compétence 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 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 l’objet de catégorie de premier niveau correspondant dans votre fichier settings.json. Quelques paramètres de compatibilité, comme proxy, sont des clés de premier niveau.

Premier niveau

general

output

ui

ide

privacy

model

Exemple 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 (tokens de sortie adaptatifs) :

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

1. Les requêtes commencent avec une limite par défaut de 8K tokens de sortie
2. Si la réponse est tronquée (le modèle atteint la limite), Qwen Code réessaie automatiquement avec 64K tokens
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 les utilisateurs — vous pourrez brièvement voir un indicateur de nouvelle tentative si une escalade se produit. Comme 99 % des réponses font moins de 5K tokens, la nouvelle tentative est rare (<1 % des requêtes).

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

contextWindowSize :

Écrase 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 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 tokens par requête.

modalities :

Écrase 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 de motifs 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. Si customHeaders est défini dans modelProviders[].generationConfig.customHeaders, il sera utilisé directement ; sinon, les en-têtes de model.generationConfig.customHeaders seront utilisés. Aucune fusion n’a lieu entre les deux niveaux.

Le champ extra_body permet d’ajouter des paramètres personnalisés au corps de la requête envoyé à l’API. Utile pour les options spécifiques au fournisseur non 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. Si extra_body est défini dans modelProviders[].generationConfig.extra_body, il sera utilisé directement ; sinon, les valeurs de model.generationConfig.extra_body seront utilisées.

Exemples model.openAILoggingDir :

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

fastModel

context

Dépannage des performances de recherche de fichiers

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

1. Utilisez .qwenignore : Créez un fichier .qwenignore à 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 ex. artefacts de build, journaux, node_modules). Réduire le nombre total de fichiers parcourus est la méthode la plus efficace pour améliorer les performances.
2. Désactivez la recherche floue : Si ignorer les 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 entièrement 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 taper le chemin complet des fichiers lors de l’utilisation des complétions @.

tools

memory

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

permissions

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

Priorité de décision (la plus haute 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 (l’un de ceux-ci 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 liste de répertoires). 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 bypass de 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 bypasser 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 anciens paramètres :

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 la CLI interactive pour afficher, ajouter et supprimer des règles sans modifier directement settings.json.

slashCommands

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

La même liste de blocage peut également être fournie via l’indicateur 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.

Exemple — verrouillage des intégrées pour un déploiement 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 liste de blocage depuis leur propre scope, et les commandes désactivées n’apparaîtront pas dans l’autocomplétion ni ne s’exécuteront 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 tels que 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 via l’indicateur en ligne de commande --experimental-lsp.

Le 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 s’effectue 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 les exemples.

security

advanced

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 avec l’alias du serveur que vous avez défini dans la configuration (par ex. serverAlias__actualToolName) 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 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.

telemetry

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

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

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 une méthode courante pour configurer les applications, notamment pour les informations sensibles (comme les tokens) ou pour les paramètres susceptibles de varier entre les environnements.

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

Tableau des variables d’environnement

Arguments en ligne de commande

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

Pour la sélection de l’image sandbox, l’ordre de 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 configurable via le paramètre context.fileName) sont essentiels pour configurer le contexte instructionnel (également appelé “mémoire”). Cette fonctionnalité puissante vous permet de fournir 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. La CLI inclut des éléments d’interface, 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 prenne en compte pendant 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 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.

Cet exemple montre comment 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 pourra 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 priorité : La 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) écrase ou complète généralement le contenu des fichiers plus hauts (plus généraux). L’ordre exact de concaténation et le contexte final peuvent être inspectés via la commande /memory show. 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 racine du projet et ancêtres :
     • Emplacement : La 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 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 indicateur visuel rapide sur le contexte instructionnel 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, voir la documentation Memory Import Processor.
• Commandes pour la gestion de la mémoire :
  • Utilisez /memory refresh pour forcer une nouvelle analyse et un rechargement de tous les fichiers de contexte depuis tous les emplacements configurés. Cela met à jour le contexte instructionnel de l’IA.
  • Utilisez /memory show pour afficher le contexte instructionnel combiné actuellement chargé, vous permettant de vérifier la hiérarchie et le contenu utilisés par l’IA.
  • Voir la documentation Commands pour tous les détails sur la commande /memory et ses sous-commandes (show et refresh).

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 façons :

• Via l’indicateur --sandbox ou -s.
• En définissant la variable d’environnement QWEN_SANDBOX.
• Le sandbox est activé par défaut lors de l’utilisation de --yolo ou --approval-mode=yolo.

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

Pour les besoins de sandbox spécifiques au projet, vous pouvez créer un Dockerfile personnalisé à .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
# 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 journalisons les noms des outils appelés, s’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 retournent.
• Requêtes API : Nous journalisons 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 personnellement identifiables (PII) : Nous ne collectons aucune information personnelle, telle que votre nom, adresse e-mail ou clés API.
• Contenu des prompts et réponses : Nous ne journalisons pas le contenu de vos prompts ou 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ésengager :

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

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