Configuration de Qwen Code

Couches de configuration

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

Fichiers de configuration

Qwen Code utilise des fichiers de configuration JSON pour la persistance des paramètres. 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 personnalisés de sandbox (par exemple .qwen/sandbox-macos-custom.sb, .qwen/sandbox.Dockerfile).
• Compétences d’agent situées dans .qwen/skills/ (chaque compétence est un répertoire contenant un fichier SKILL.md).

Migration de la configuration

Qwen Code migre automatiquement les anciens paramètres de configuration vers le nouveau format. Les anciens fichiers de configuration sont sauvegardés avant la migration. Les paramètres suivants ont été renommés, passant d’une dénomination négative (disable*) à une dénomination 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 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 en catégories. Tous les paramètres doivent être placés dans leur objet de catégorie de premier niveau correspondant dans votre fichier settings.json.

général

output

ui

ide

confidentialité

model

Exemple model.generationConfig :

{
  "model": {
    "generationConfig": {
      "timeout": 60000,
      "contextWindowSize": 128000,
      "enableCacheControl": true,
      "customHeaders": {
        "X-Request-ID": "req-123",
        "X-User-ID": "user-456"
      },
      "extra_body": {
        "enable_thinking": true
      },
      "samplingParams": {
        "temperature": 0.2,
        "top_p": 0.8,
        "max_tokens": 1024
      }
    }
  }
}

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 des noms de modèles, 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é maximale de contexte supposée du modèle, pas une limite de jetons par requête.

customHeaders :

Vous permet d’ajouter des en-têtes HTTP personnalisés à toutes les requêtes API. Ceci est utile pour le suivi des requêtes, la surveillance, le routage via 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 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 non couvertes par les champs de configuration standards. 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" - Journalise dans le répertoire ~/qwen-logs
• "./custom-logs" - Journalise dans ./custom-logs relatif au répertoire courant
• "/tmp/openai-logs" - Journalise dans le chemin absolu /tmp/openai-logs

modelProviders

Utilisez modelProviders pour déclarer des listes de modèles organisées par type d’authentification entre lesquelles le sélecteur /model peut basculer. Les clés doivent être des types d’authentification valides (openai, anthropic, gemini, vertex-ai, etc.). Chaque entrée nécessite un id et doit inclure envKey, avec des champs optionnels name, description, baseUrl et generationConfig. Les identifiants ne sont jamais persistés dans les paramètres ; le runtime les lit depuis process.env[envKey]. Les modèles OAuth de Qwen restent codés en dur et ne peuvent pas être remplacés.

Exemple

{
  "modelProviders": {
    "openai": [
      {
        "id": "gpt-4o",
        "name": "GPT-4o",
        "envKey": "OPENAI_API_KEY",
        "baseUrl": "https://api.openai.com/v1",
        "generationConfig": {
          "timeout": 60000,
          "maxRetries": 3,
          "customHeaders": {
            "X-Model-Version": "v1.0",
            "X-Request-Priority": "high"
          },
          "extra_body": {
            "enable_thinking": true
          },
          "samplingParams": { "temperature": 0.2 }
        }
      }
    ],
    "anthropic": [
      {
        "id": "claude-3-5-sonnet",
        "envKey": "ANTHROPIC_API_KEY",
        "baseUrl": "https://api.anthropic.com/v1"
      }
    ],
    "gemini": [
      {
        "id": "gemini-2.0-flash",
        "name": "Gemini 2.0 Flash",
        "envKey": "GEMINI_API_KEY",
        "baseUrl": "https://generativelanguage.googleapis.com"
      }
    ],
    "vertex-ai": [
      {
        "id": "gemini-1.5-pro-vertex",
        "envKey": "GOOGLE_API_KEY",
        "baseUrl": "https://generativelanguage.googleapis.com"
      }
    ]
  }
}

[!note] Seule la commande /model expose les types d’authentification non par défaut. Anthropic, Gemini, Vertex AI, etc., doivent être définis via modelProviders. La commande /auth liste intentionnellement uniquement les flux OAuth intégrés de Qwen et OpenAI.

Couches de résolution et atomicité

Les valeurs effectives d’authentification/modèle/identifiants sont choisies par champ en utilisant la priorité suivante (la première présente l’emporte). Vous pouvez combiner --auth-type avec --model pour pointer directement vers une entrée de fournisseur ; ces indicateurs CLI s’exécutent avant les autres couches.

*Lorsqu’ils sont présents, les indicateurs d’authentification CLI remplacent les paramètres. Sinon, security.auth.selectedType ou la valeur implicite par défaut déterminent le type d’authentification. Qwen OAuth et OpenAI sont les seuls types d’authentification disponibles sans configuration supplémentaire.

Les valeurs provenant du fournisseur de modèle sont appliquées de manière atomique : une fois qu’un modèle de fournisseur est actif, chaque champ qu’il définit est protégé contre les couches inférieures jusqu’à ce que vous effaciez manuellement les identifiants via /auth. Le generationConfig final est la projection à travers toutes les couches—les couches inférieures ne remplissent que les lacunes laissées par les couches supérieures, et la couche fournisseur reste imperméable.

La stratégie de fusion pour modelProviders est REMPLACER : l’intégralité des modelProviders provenant des paramètres du projet remplacera la section correspondante dans les paramètres utilisateur, plutôt que de fusionner les deux.

Imbrication de la configuration de génération

Précédence par champ pour generationConfig :

1. Remplacements programmatiques (par exemple modifications d’exécution /model, /auth)
2. modelProviders[authType][].generationConfig
3. settings.model.generationConfig
4. Valeurs par défaut du générateur de contenu (getDefaultGenerationConfig pour OpenAI, getParameterValue pour Gemini, etc.)

samplingParams, customHeaders et extra_body sont tous traités de manière atomique ; les valeurs du fournisseur remplacent l’objet entier. Si modelProviders[].generationConfig définit ces champs, ils sont utilisés directement ; sinon, les valeurs de model.generationConfig sont utilisées. Aucune fusion n’a lieu entre les niveaux de configuration du fournisseur et global. Les valeurs par défaut du générateur de contenu s’appliquent en dernier afin que chaque fournisseur conserve sa base optimisée.

Persistance de la sélection et recommandations

[!important] Définissez modelProviders dans le fichier utilisateur ~/.qwen/settings.json chaque fois que possible et évitez de conserver les substitutions d’identifiants dans n’importe quelle portée. Le fait de garder le catalogue du fournisseur dans les paramètres utilisateur empêche les conflits de fusion/remplacement entre les portées projet et utilisateur, et garantit que les mises à jour /auth et /model s’écrivent toujours dans une portée cohérente.

• /model et /auth conservent model.name (lorsque applicable) et security.auth.selectedType dans la portée inscriptible la plus proche qui définit déjà modelProviders ; sinon, ils reviennent à la portée utilisateur. Cela permet de maintenir la synchronisation des fichiers de l’espace de travail/utilisateur avec le catalogue de fournisseurs actif.
• Sans modelProviders, le résolveur mélange les couches CLI/env/settings, ce qui convient aux configurations mono-fournisseur mais devient fastidieux lors de changements fréquents. Définissez des catalogues de fournisseurs chaque fois que les flux de travail multi-modèles sont courants afin que les changements restent atomiques, correctement attribués et débogables.

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 @), particulièrement dans des projets contenant un très grand nombre de fichiers, voici quelques éléments à essayer selon un 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érence (par exemple, les artefacts de compilation, les 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 l’ignorance des fichiers n’est pas suffisante, vous pouvez désactiver la recherche floue en définissant enableFuzzySearch à 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é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 à 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 lorsque vous utilisez les complétions @.

outils

mcp

lsp

[!warning] Fonctionnalité expérimentale : Le support du protocole LSP est actuellement expérimental et désactivé par défaut. Activez-le à l’aide de l’option --experimental-lsp.

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

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

sécurité

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é afin de découvrir les outils disponibles. Si plusieurs serveurs MCP exposent un outil portant 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 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 assurer la compatibilité. Au moins l’un des paramètres suivants doit être fourni : command, url ou httpUrl. 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 des 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 à partir de la version 0.3.0 :

{
  "general": {
    "vimMode": true,
    "preferredEditor": "code"
  },
  "ui": {
    "theme": "GitHub",
    "hideTips": false,
    "customWittyPhrases": [
      "Tu oublies mille choses chaque jour. Assure-toi que celle-ci en fait partie",
      "Connexion à l'AGI"
    ]
  },
  "tools": {
    "approvalMode": "yolo",
    "sandbox": "docker",
    "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",
    "summarizeToolOutput": {
      "run_shell_command": {
        "tokenBudget": 100
      }
    }
  },
  "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 situé 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 constituent un moyen courant de configurer les applications, en particulier pour les informations sensibles (comme les jetons) ou pour les paramètres qui peuvent varier selon les environnements.

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

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.

Tableau des arguments de ligne de commande

Fichiers de contexte (Contexte instructif hiérarchique)

Bien que ne constituant pas strictement une configuration du comportement du CLI, les fichiers de contexte (nommés par défaut QWEN.md mais configurables via le paramètre context.fileName) sont essentiels pour configurer le contexte instructif (é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 autre information pertinente au modèle d’intelligence artificielle, rendant ainsi ses réponses plus adaptées et précises à vos besoins. Le CLI inclut des éléments d’interface utilisateur, tels qu’un indicateur dans le pied de page affichant le nombre de fichiers de contexte chargés, afin de vous tenir informé du contexte actif.

• Objectif : Ces fichiers Markdown contiennent des instructions, des directives ou des informations de contexte que vous souhaitez que le modèle Qwen prenne en compte durant vos interactions. Le système est conçu pour gérer ce contexte instructif de manière hiérarchique.

Exemple de contenu de fichier de contexte (par exemple QWEN.md)

Voici un exemple conceptuel du contenu que pourrait avoir un fichier de contexte à la racine d’un projet TypeScript :

# Projet : Ma fantastique bibliothèque TypeScript

## Instructions générales :
- Lors de la génération de nouveau code TypeScript, veuillez suivre le style de codage existant.
- Assurez-vous que toutes les nouvelles fonctions et classes disposent de commentaires JSDoc.
- Préférez les paradigmes de programmation fonctionnelle lorsque c'est approprié.
- Tout le code doit être compatible avec TypeScript 5.0 et Node.js 20+.

## Style de codage :
- Utilisez 2 espaces pour l'indentation.
- Les noms d'interfaces doivent être préfixés par `I` (par exemple, `IUserService`).
- Les membres privés des classes doivent être préfixés par un trait de soulignement (`_`).
- Utilisez toujours l'égalité stricte (`===` et `!==`).

## Composant spécifique : `src/api/client.ts`
- Ce fichier gère toutes les requêtes API sortantes.
- Lors de l'ajout de nouvelles fonctions d'appel d'API, assurez-vous qu'elles incluent une gestion d'erreurs et une journalisation robustes.
- Utilisez l'utilitaire existant `fetchWithRetry` pour toutes les requêtes GET.

À propos des dépendances :

• Évitez d’introduire de nouvelles dépendances externes à moins que ce ne soit absolument nécessaire.
• Si une nouvelle dépendance est requise, veuillez indiquer la raison.

Cet exemple montre comment vous pouvez fournir un contexte général sur le projet, des conventions de codage spécifiques et même des notes concernant des fichiers ou composants particuliers. Plus vos fichiers de contexte sont pertinents et précis, mieux l'IA pourra vous aider. Il est fortement recommandé de créer des fichiers de contexte spécifiques au projet afin d'établir des conventions et du contexte.

- **Chargement hiérarchique et priorité :** Le 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 consultés à l'aide de la commande `/memory show`. 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 racine du projet et 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'au répertoire racine du projet (identifié 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 :** Les contenus de tous les fichiers de contexte trouvés sont concaténés (avec des séparateurs indiquant leur origine et leur chemin) et fournis comme partie du prompt système. Le pied de page du CLI affiche le nombre de fichiers de contexte chargés, vous donnant ainsi un indicateur visuel rapide sur le contexte d'instructions actif.
- **Importation de contenu :** Vous pouvez modulariser vos fichiers de contexte en important d'autres fichiers Markdown à l'aide de la syntaxe `@chemin/vers/fichier.md`. Pour plus de détails, consultez la [documentation du processeur d'importation de mémoire](../configuration/memory).
- **Commandes pour la gestion de la mémoire :**
  - Utilisez `/memory refresh` pour forcer un nouveau scan et recharger tous les fichiers de contexte depuis tous les emplacements configurés. Cela met à jour le contexte d'instructions de l'IA.
  - Utilisez `/memory show` pour afficher le contexte d'instructions combiné actuellement chargé, vous permettant de vérifier la hiérarchie et le contenu utilisé par l'IA.
  - Consultez la [documentation des commandes](../features/commands) pour plus de 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 les commandes shell et les modifications de fichiers) au sein d'un environnement isolé (sandbox) pour protéger votre système.

Le [Sandbox](../features/sandbox) est désactivé par défaut, mais vous pouvez l'activer de plusieurs façons :

- En utilisant l'option `--sandbox` ou `-s`.
- En définissant la variable d'environnement `GEMINI_SANDBOX`.
- Le mode sandbox est activé par défaut lorsque vous utilisez `--yolo` ou `--approval-mode=yolo`.

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

Pour répondre à des besoins spécifiques liés au projet, vous pouvez créer un fichier Docker personnalisé à l'emplacement `.qwen/sandbox.Dockerfile` à la racine de votre projet. Ce fichier Docker peut être basé sur l'image de base du sandbox :

FROM qwen-code-sandbox

Ajoutez vos dépendances ou configurations personnalisées ici

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 personnalisée du sandbox :

BUILD_SANDBOX=1 qwen -s

Statistiques d’utilisation

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

Ce que nous recueillons :

• Appels aux outils : Nous enregistrons les noms des outils appelés, s’ils réussissent ou échouent, ainsi que leur durée d’exécution. Nous ne recueillons 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 celle-ci et si elle a réussi. Nous ne recueillons pas le contenu des invites ou des réponses.
• Informations sur la session : Nous recueillons des informations concernant la configuration de la CLI, telles que les outils activés et le mode d’approbation.

Ce que nous NE recueillons PAS :

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

Comment se désinscrire :

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

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