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 paramètres

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

Le répertoire .qwen dans votre projet

En plus d’un fichier de 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 (expérimental) dans .qwen/skills/ (chaque compétence est un répertoire contenant un fichier SKILL.md).

Paramètres disponibles dans settings.json

Les paramètres sont organisés en catégories. Tous les paramètres doivent être placés dans l’objet de catégorie de premier niveau correspondant dans votre fichier settings.json.

général

output

ui

ide

confidentialité

modèle

Exemple model.generationConfig :

{
  "model": {
    "generationConfig": {
      "timeout": 60000,
      "disableCacheControl": false,
      "customHeaders": {
        "X-Request-ID": "req-123",
        "X-User-ID": "user-456"
      },
      "samplingParams": {
        "temperature": 0.2,
        "top_p": 0.8,
        "max_tokens": 1024
      }
    }
  }
}

Le champ customHeaders vous permet d’ajouter des en-têtes HTTP personnalisés à toutes les requêtes API. Cela est utile pour le suivi des requêtes, la surveillance, le routage via une passerelle API ou lorsque différents modèles nécessitent des en-têtes distincts. 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’est effectuée entre les deux niveaux.

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"
          },
          "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 précédence 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 exposés sans configuration supplémentaire.

Les valeurs provenant du fournisseur de modèles 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’ensemble de modelProviders 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

Ordre de priorité 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 et customHeaders sont tous deux 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 ne se produit entre les niveaux de configuration du fournisseur et globale. 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 persister les substitutions d’identifiants dans n’importe quel autre périmètre. Conserver le catalogue de fournisseurs dans les paramètres utilisateur empêche les conflits de fusion/remplacement entre les périmètres projet et utilisateur, et garantit que les mises à jour /auth et /model s’écrivent toujours dans un périmètre cohérent.

• /model et /auth persistent model.name (lorsque applicable) et security.auth.selectedType dans le périmètre modifiable le plus proche qui définit déjà modelProviders ; sinon, ils se rabattent sur le périmètre utilisateur. Cela maintient la synchronisation des fichiers 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 à leur source 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 disableFuzzySearch à true 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

sécurité

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é 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 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 v0.3.0 :

{
  "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",
    "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 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 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 à l’IA, 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 un 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 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 superbe 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 cela 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 et une journalisation robustes des erreurs.
- 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. La création de fichiers de contexte spécifiques au projet est vivement encouragée 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 :** 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 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 du 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 balayage 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 obtenir tous les détails sur la commande `/memory` et ses sous-commandes (`show` et `refresh`).

En comprenant et en utilisant ces couches de configuration ainsi que la nature hiérarchique des fichiers de contexte, vous pouvez efficacement gérer 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) afin de 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 Dockerfile 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 collectons 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 collectons :**

- **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 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 celle-ci et si elle a abouti. Nous ne collectons 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 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 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 à tout moment vous désinscrire de la collecte 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 } }

> [!note]
>
> Lorsque les statistiques d'utilisation sont activées, les événements sont envoyés à un point de collecte Alibaba Cloud RUM.