Utiliser Qwen Code : le guide pas à pas

Pour utiliser Qwen Code, installez la CLI qwen avec le script officiel, npm ou Homebrew, lancez qwen dans le dossier d’un projet, choisissez un fournisseur de modèles avec /auth et décrivez ce que vous voulez. Qwen Code lit votre code, modifie des fichiers et exécute des commandes, en demandant votre accord selon le mode d’approbation choisi. Comme l’offre gratuite Qwen OAuth a pris fin le 15 avril 2026, il vous faut une clé API ou un forfait chez un fournisseur, ou un modèle local.

Voilà la boucle de base. Ce guide couvre le reste : les options de connexion et ce qui a remplacé l’offre gratuite, les clés compatibles OpenAI et les modèles locaux, le choix du modèle, les modes d’approbation, QWEN.md, les serveurs MCP, le mode headless pour les scripts et l’utilisation de Qwen Code aux côtés d’autres agents. Tout suit le dépôt et la documentation officiels de Qwen Code en date d’octobre 2026.

Qu’est-ce que Qwen Code

Qwen Code est un agent de code pour le terminal, développé par l’équipe Qwen d’Alibaba et publié sous licence Apache-2.0. Il est né d’un fork de Gemini CLI, donc sa structure vous semblera familière si vous avez utilisé l’agent de Google, même s’il évolue depuis longtemps de son côté. Il est optimisé pour les modèles de code Qwen, sans en dépendre : il parle les formats d’API OpenAI, Anthropic et Gemini et fonctionne avec des modèles locaux.

En plus du terminal, le projet propose une application de bureau, des intégrations pour VS Code, Zed et JetBrains, et des SDK pour TypeScript, Python et Java. Ce guide se concentre sur la CLI.

Étape 1 : installer Qwen Code

Après une installation par script, redémarrez le terminal pour que la commande qwen soit dans votre PATH. Le paquet npm demande Node.js 22 ou plus récent. Pour mettre à jour, relancez la même commande npm ou Homebrew.

Étape 2 : se connecter avec /auth

Placez-vous dans un projet et lancez Qwen Code :

cd my-project
qwen

Au premier lancement, puis à tout moment avec /auth, Qwen Code propose quatre façons de brancher un modèle :

Exécutez /doctor dans une session pour voir quelle authentification est active. L’ancienne commande shell qwen auth a été supprimée : on change de fournisseur avec /auth.

Ce qu’est devenue l’offre gratuite Qwen OAuth

Longtemps, le plus simple était de se connecter avec un compte qwen.ai via Qwen OAuth et de recevoir un quota quotidien gratuit. La documentation indique désormais que l’offre gratuite Qwen OAuth a été retirée le 15 avril 2026. Elle n’apparaît plus dans /auth, et les nouvelles requêtes par ce biais sont refusées même s’il reste un ancien jeton en cache. Si vous avez suivi un vieux tutoriel et que l’agent a soudain cessé de répondre, voilà pourquoi. Choisissez l’une des options ci-dessus. Notre sélection des meilleurs outils de codage IA gratuits passe en revue ce qui reste gratuit en 2026.

Utiliser n’importe quelle clé compatible OpenAI

La configuration la plus rapide pour les scripts et les serveurs tient en trois variables d’environnement :

export OPENAI_API_KEY="sk-..."
export OPENAI_BASE_URL="https://openrouter.ai/api/v1"
export OPENAI_MODEL="your-model-id"
qwen

Ce sont les variables du protocole compatible OpenAI, qui couvre la plupart des fournisseurs. Les formats Anthropic et Gemini ont les leurs (ANTHROPIC_API_KEY, ANTHROPIC_BASE_URL, ANTHROPIC_MODEL et GEMINI_API_KEY, GEMINI_MODEL).

Plutôt que d’exporter les clés dans chaque shell, vous pouvez les placer dans un fichier .env. Qwen Code cherche .qwen/.env et .env dans le projet et ses dossiers parents, puis ~/.qwen/.env et ~/.env, et ne charge que le premier trouvé. Les flags de la ligne de commande priment sur les variables du shell, celles-ci sur .env, et .env sur le bloc env de settings.json.

Pour une configuration durable, déclarez le fournisseur dans ~/.qwen/settings.json. envKey désigne la variable qui contient la clé :

{
  "modelProviders": {
    "openai": [
      {
        "id": "qwen3-coder-plus",
        "name": "qwen3-coder-plus",
        "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",
        "description": "Qwen3-Coder via Dashscope",
        "envKey": "DASHSCOPE_API_KEY"
      }
    ]
  },
  "security": { "auth": { "selectedType": "openai" } },
  "model": { "name": "qwen3-coder-plus" }
}

Le fichier accepte aussi un bloc env contenant la clé elle-même, mais elle y est alors stockée en clair. La documentation recommande .qwen/.env pour les secrets du projet, hors de Git.

Modèles locaux avec Ollama

Ollama, vLLM et LM Studio exposent une API compatible OpenAI : un modèle local n’est donc qu’un fournisseur openai de plus, avec une baseUrl locale. Ollama n’a pas besoin d’une vraie clé, n’importe quelle valeur suffit :

{
  "env": { "OLLAMA_API_KEY": "ollama" },
  "modelProviders": {
    "openai": [
      {
        "id": "qwen2.5-7b",
        "name": "Qwen2.5 7B (Ollama)",
        "envKey": "OLLAMA_API_KEY",
        "baseUrl": "http://localhost:11434/v1",
        "generationConfig": { "contextWindowSize": 32768 }
      }
    ]
  }
}

L’id doit correspondre au nom du modèle dans Ollama. Un petit modèle local peine sur les longues sessions d’agent ; notre guide sur un agent de code avec un LLM local explique quels modèles et quelle quantité de mémoire le rendent viable.

Étape 3 : choisir un modèle

Dans une session, /model ouvre un sélecteur avec les modèles de vos fournisseurs et /model <model-id> bascule directement. Depuis le shell, qwen --model qwen3-coder-plus (ou -m) fixe le modèle pour une exécution. Pour les modèles à raisonnement, /effort règle le niveau de raisonnement si le fournisseur le permet.

Les modèles disponibles dépendent du fournisseur. En octobre 2026, le Coding Plan d’Alibaba comprend des modèles Qwen comme qwen3-coder-plus, qwen3-coder-next et qwen3.7-plus, ainsi que des modèles tiers comme GLM, Kimi et MiniMax. Une clé à l’usage vous donne ce que propose l’API de ce fournisseur.

Étape 4 : les bases d’une session

L’écran de Qwen Code est un chat avec votre projet. Quelques gestes que vous utiliserez sans cesse :

• @chemin ajoute un fichier à votre message, et @dossier/ lit les fichiers texte d’un dossier.
• !commande exécute une commande shell, par exemple !git status. Un ! seul bascule en mode shell jusqu’au prochain !.
• Shift+Tab (Tab sous Windows) fait défiler les modes d’approbation.

Depuis le shell, qwen --continue rouvre la dernière session du projet courant et qwen --resume <id> en ouvre une précise.

Étape 5 : les modes d’approbation

Qwen Code propose cinq modes d’approbation qui décident de ce qu’il peut faire sans demander :

Par défaut, Qwen Code démarre en Auto : un classifieur basé sur un modèle approuve les actions sûres et bloque les risquées. Changez avec /approval-mode plan ou Shift+Tab, ou démarrez avec qwen --approval-mode plan. Une bonne habitude pour tout ce qui n’est pas trivial : commencez en Plan, mettez-vous d’accord sur l’approche, puis passez en Auto-Edit ou Auto pour l’exécuter. Réservez YOLO aux conteneurs ou aux machines jetables, où une mauvaise commande ne peut pas causer de dégâts durables.

Étape 6 : QWEN.md et le contexte du projet

QWEN.md est le briefing que Qwen Code charge au début de chaque session : commandes de build et de test, conventions, dossiers à ne pas toucher. Il peut se trouver à trois endroits, tous chargés :

Lancez /init : Qwen Code analyse le projet et écrit un QWEN.md de départ ; s’il existe déjà, il propose des ajouts au lieu de l’écraser. Si le dépôt contient déjà un AGENTS.md pour d’autres outils, Qwen Code le lit aussi. Dans QWEN.md, @docs/git-workflow.md importe un autre fichier.

# Règles du projet

- Gestionnaire de paquets : pnpm. Lance `pnpm test` avant de terminer une tâche.
- TypeScript en mode strict ; pas de `any` dans le nouveau code.
- Ne modifie jamais les fichiers de src/generated/.
- Workflow Git : @docs/git-workflow.md

Gardez-le court ; la documentation prévient qu’un fichier long est suivi de façon moins fiable. Qwen Code tient aussi sa propre mémoire automatique dans ~/.qwen/projects/<projet>/memory/, des fichiers Markdown que vous pouvez modifier ou désactiver dans /memory. Pour des règles qui ne concernent que certains fichiers, .qwen/rules/ accepte des fichiers Markdown avec un champ paths:. Quoi mettre dans un tel fichier, c’est ce qu’explique CLAUDE.md et AGENTS.md, et cela vaut tout autant pour QWEN.md.

Étape 7 : les serveurs MCP

Les serveurs MCP donnent de nouveaux outils à Qwen Code : un navigateur, un gestionnaire de tickets ou une recherche dans la documentation. Le plus rapide pour en ajouter un est la commande qwen mcp :

# un serveur distant en HTTP
qwen mcp add --transport http my-server http://localhost:3000/mcp

# un serveur local lancé comme processus (stdio est le transport par défaut)
qwen mcp add pythonTools -e DATABASE_URL=$DB_CONNECTION_STRING python -m my_mcp_server

# le retirer
qwen mcp remove my-server

Les serveurs sont enregistrés dans le bloc mcpServers de ~/.qwen/settings.json (la portée utilisateur par défaut) ou, avec --scope project, dans .qwen/settings.json. Vous pouvez aussi éditer ce bloc à la main : command et args pour un processus local, httpUrl pour un serveur HTTP. --include-tools et --exclude-tools limitent les outils qu’un serveur expose. Si Qwen Code était déjà ouvert, redémarrez-le et tapez /mcp pour vérifier que le serveur est connecté et voir ses outils.

Étape 8 : le mode headless pour les scripts et la CI

-p (ou --prompt) exécute une seule tâche sans l’interface interactive, et stdin fonctionne aussi :

qwen -p "Summarize what changed in src/ since the last tag"
cat error.log | qwen -p "Explain this stack trace"
qwen -p "List the TODOs in this repo" --output-format json > todos.json

--output-format accepte text, json ou stream-json. qwen --continue -p "..." poursuit la dernière session, ce qui permet à un script de travailler en plusieurs étapes. Pour qu’une exécution headless puisse modifier des fichiers, fixez un mode d’approbation comme --approval-mode auto-edit, ou --yolo sur un runner isolé. La documentation est claire : --yolo n’active aucun sandbox et les commandes shell tournent avec les droits de votre utilisateur. Des limites empêchent une exécution sans surveillance de s’emballer :

qwen -p "Fix the failing unit tests" --yolo \
  --max-session-turns 30 --max-wall-time 10m --output-format json

Une exécution qui dépasse --max-wall-time ou --max-tool-calls se termine avec le code 55, et une qui dépasse --max-session-turns avec le code 53, ce qui permet à la CI de distinguer les cas. Pour une vraie isolation, qwen -s exécute les outils dans un sandbox (Seatbelt sous macOS, Docker ou Podman ailleurs).

Pièges courants

• L’agent ne fonctionne plus depuis avril 2026. Vous utilisiez l’offre gratuite Qwen OAuth, qui n’existe plus. Lancez /auth et choisissez un autre fournisseur.
• « qwen auth » affiche un avis de suppression. La commande n’existe plus ; utilisez /auth dans une session et /doctor pour vérifier.
• Une clé dans QWENCLOUD_API_KEY ou DASHSCOPE_API_KEY est ignorée. Les variables propres à un fournisseur ne fonctionnent que si un fournisseur de settings.json les désigne comme envKey. Sinon, utilisez OPENAI_API_KEY.
• Un nouveau serveur MCP n’apparaît pas. Il a été ajouté pendant que Qwen Code était ouvert. Redémarrez-le dans le même projet.
• Les longues sessions deviennent lentes et coûteuses. Utilisez /compress ou /clear, gardez QWEN.md court et désactivez les serveurs MCP inutiles.

Faire tourner Qwen Code à côté d’autres CLI

Qwen Code a ses propres sous-agents et une prise en charge des worktrees, mais ils restent à l’intérieur de Qwen Code. Si vous voulez Qwen Code sur une tâche, Claude Code sur une autre et Gemini CLI sur une troisième, vous voilà de nouveau à jongler avec les onglets du terminal. AgentVera est une application de bureau qui fait tourner ces CLI en parallèle dans de vrais terminaux, avec vos propres installations et connexions. Sa prise en charge de Qwen Code fonctionne ainsi :

• Votre connexion. Qwen Code garde sa propre connexion, que le terminal de l’agent demande au premier lancement. Si qwen n’est pas installé, AgentVera l’installe avec npm i -g @qwen-code/qwen-code.
• Une session par agent. Chaque agent démarre avec son propre identifiant de session (--session-id), et une session enregistrée se rouvre avec --resume.
• Rôle et modèle. Le rôle de l’agent est ajouté au prompt système de Qwen Code avec --append-system-prompt. Laissez le champ Model vide pour garder le modèle par défaut de Qwen Code, ou choisissez-en un et AgentVera le passe avec --model.
• MCP à chaque lancement. Les serveurs du gestionnaire MCP d’AgentVera et le navigateur d’AgentVera sont transmis avec --mcp-config, donc votre settings.json reste intact.
• Panneaux, revue et flows. Faites tourner Qwen Code à côté de Claude Code dans la grille du Workspace, chaque agent dans son propre worktree git, avec une code review automatique à la fin de chaque tour. Les agents Qwen Code fonctionnent aussi dans les diffusions, les tâches planifiées et les Flows (Pro et Team), où la réponse d’un agent passe au suivant.
• Plusieurs comptes. Dans Settings → Accounts → Accounts of other agents, vous pouvez ajouter des comptes Qwen supplémentaires, qui fonctionnent avec des clés API, et définir un ordre de repli (Pro et Team).

Pour être juste envers les alternatives : si vous voulez seulement un modèle hébergé gratuit, Qwen Code ne le propose plus, et les outils gratuits de la sélection citée plus haut sont un meilleur point de départ. Si vous cherchez un agent indépendant du fournisseur avec un autre flux de travail, opencode est l’alternative la plus proche. La grille, les worktrees, la code review et le MCP manager sont dans l’offre gratuite. Téléchargez AgentVera pour l’essayer.

En résumé

Pour utiliser Qwen Code, installez-le, lancez qwen dans un projet et choisissez un fournisseur avec /auth, puisque l’offre gratuite Qwen OAuth a disparu. Toute clé compatible OpenAI fonctionne via les variables OPENAI_* ou settings.json, modèles locaux compris. Commencez le travail risqué en mode Plan, mettez les règles du projet dans QWEN.md, ajoutez des outils avec qwen mcp add et utilisez qwen -p avec des limites quand un script ou un job de CI a besoin de l’agent. Ensuite, la vraie décision porte sur le fournisseur et le modèle qui collent à votre budget, et Qwen Code vous laisse changer les deux à tout moment.