Qwen Code : l'agent de code en terminal avec Ollama

#Ce qu'est Qwen Code, et pourquoi le faire tourner en local

Qwen Code est un fork de Gemini CLI, l'agent terminal open source de Google, que l'équipe Qwen a adapté à ses modèles Qwen3-Coder. Le projet est publié sous licence Apache 2.0 sur GitHub (QwenLM/qwen-code), s'installe via npm et s'utilise avec la commande qwen. Il reprend la mécanique des agents de code modernes : un modèle reçoit votre demande, dispose d'outils (lecture et écriture de fichiers, recherche dans le dépôt, exécution shell, requêtes web, serveurs MCP) et boucle sur ces outils jusqu'à produire un résultat vérifiable.

Par défaut, Qwen Code pousse vers une connexion « Qwen OAuth » : vous vous identifiez avec un compte Qwen et les requêtes partent vers les serveurs d'Alibaba Cloud. Une offre gratuite existe sur ce chemin, mais ses quotas peuvent changer et dépendent de la région. Nous ne donnons donc pas de chiffre ici : la page d'authentification de la documentation officielle est la seule source à jour. Ce qui ne change pas, c'est l'autre mode, dit « OpenAI-compatible » : Qwen Code accepte n'importe quel serveur qui expose l'API OpenAI, dont Ollama et LM Studio sur votre machine.

Confidentialité

En mode local, le code source, les commandes exécutées et leurs sorties ne quittent jamais le poste. C'est l'argument décisif pour du code client ou sous accord de confidentialité.

Coût

Aucun quota, aucune facture au token. Le seul coût est l'électricité et le matériel déjà acheté.

Disponibilité

Pas de panne de service, pas de file d'attente aux heures de pointe. L'agent répond tant que le GPU tourne.

Contrepartie

Un modèle de 7 à 30 milliards de paramètres en quantification Q4 n'a pas le niveau d'un modèle cloud de plusieurs centaines de milliards. Il faut découper les tâches plus finement et relire davantage.

#Prérequis

Node.js 20 ou plus récent

Qwen Code est un paquet npm. Vérifiez avec node --version. Sur Linux et macOS, nvm ou fnm évitent les problèmes de droits lors de l'installation globale.

Ollama installé et fonctionnel

Le daemon écoute sur http://localhost:11434. Un ollama list doit répondre sans erreur. Si ce n'est pas le cas, commencez par le guide d'installation d'Ollama.

Un modèle qui gère l'appel d'outils

C'est non négociable : un agent de code enchaîne des appels d'outils structurés. Les modèles de la famille Qwen3-Coder et Qwen2.5-Coder, ainsi que Devstral, les prennent en charge sous Ollama. Un modèle sans support des tools produira du texte à la place des actions et l'agent restera bloqué.

Mémoire GPU

Repères en Q4_K_M : un 7B occupe environ 5 Go de VRAM, un 14B environ 9 Go, un 32B environ 19 Go, hors contexte. Le contexte long que réclame un agent ajoute plusieurs gigaoctets : comptez large.

Un dépôt Git

Pas obligatoire, mais fortement conseillé. L'agent modifie des fichiers ; git diff et git checkout sont votre filet de sécurité.

#1. Installer Qwen Code

L'installation recommandée par le dépôt passe par npm en global. Sur macOS, un paquet Homebrew est également publié. Le binaire s'appelle qwen.

npm install -g @qwen-code/qwen-code@latest
qwen --version

brew install qwen-code
qwen --version

Au premier lancement de qwen sans configuration, l'outil propose de choisir une méthode d'authentification. Ne choisissez pas Qwen OAuth si votre objectif est le local : sélectionnez l'option OpenAI, ou mieux, quittez et préparez d'abord la configuration décrite à l'étape suivante. Vous pourrez toujours changer de méthode plus tard avec la commande /auth dans une session.

#2. Brancher Qwen Code sur Ollama

Ollama expose une API compatible OpenAI sur le chemin /v1 du port 11434. Qwen Code lit trois variables d'environnement pour ce mode : l'URL de base, une clé API et le nom du modèle. Ollama n'exige pas de clé, mais Qwen Code refuse une valeur vide, donc on met une chaîne quelconque.

1. 01
   Télécharger un modèle de code compatible tools

   Exemple avec Qwen3-Coder 30B-A3B, un modèle à experts (MoE) de 30 milliards de paramètres dont 3 milliards sont actifs à chaque token, ce qui le rend rapide pour sa taille. Il pèse autour de 19 Go en Q4 : il faut 24 Go de VRAM, ou une machine Apple Silicon avec au moins 32 Go unifiés, pour le garder entièrement sur GPU. Sur une carte de 12 Go, prenez plutôt qwen2.5-coder:7b ou un modèle de 14B.
2. 02
   Vérifier que l'API OpenAI d'Ollama répond

   Une requête sur /v1/models doit lister vos modèles. Si elle échoue, Ollama n'est pas lancé ou écoute sur une autre adresse.
3. 03
   Créer le fichier .env à la racine du projet

   Qwen Code charge automatiquement un fichier .env présent dans le dossier courant, dans un sous-dossier .qwen du projet, ou dans ~/.qwen pour une configuration globale. Le fichier le plus proche du dossier de travail l'emporte.
4. 04
   Lancer qwen dans le projet

   Le pied de la fenêtre affiche le modèle actif. Si vous voyez le nom de votre modèle Ollama, le branchement est fait. Tapez une première demande simple, par exemple résumer la structure du dépôt, pour vérifier que les outils de lecture fonctionnent.

ollama pull qwen3-coder:30b
curl http://localhost:11434/v1/models

OPENAI_API_KEY=ollama
OPENAI_BASE_URL=http://localhost:11434/v1
OPENAI_MODEL=qwen3-coder:30b

cd mon-projet
qwen

Les mêmes paramètres peuvent être passés en options de ligne de commande pour une session ponctuelle, sans toucher au fichier .env. C'est pratique pour tester un second modèle sans casser la configuration qui marche.

qwen --openai-api-key ollama \
  --openai-base-url http://localhost:11434/v1 \
  --model qwen2.5-coder:14b

#3. Variante : LM Studio comme serveur

Si vous préférez LM Studio, le principe est identique. Chargez un modèle de code dans l'application, ouvrez l'onglet Developer et démarrez le serveur local : il écoute par défaut sur le port 1234 et expose la même API compatible OpenAI. Pensez à activer la prise en charge des appels d'outils dans les options du serveur si elle n'est pas déjà cochée, et à régler la longueur de contexte du modèle dans l'interface (voir l'étape suivante).

OPENAI_API_KEY=lm-studio
OPENAI_BASE_URL=http://localhost:1234/v1
OPENAI_MODEL=qwen2.5-coder-14b-instruct

Le nom du modèle à indiquer est l'identifiant affiché par LM Studio dans la liste des modèles chargés, ou renvoyé par une requête sur http://localhost:1234/v1/models. Il diffère des noms Ollama.

#4. Régler la fenêtre de contexte : l'étape que tout le monde saute

C'est la cause numéro un des échecs de Qwen Code en local. Un agent de code envoie à chaque tour un prompt système long (description des outils, règles de comportement, contenu du fichier QWEN.md), puis l'historique de la session, puis les fichiers lus. Dès les premiers échanges, on dépasse 10 000 tokens. Or Ollama ouvre par défaut une fenêtre courte (4 096 tokens dans les versions récentes) : tout ce qui dépasse est tronqué silencieusement, le modèle « oublie » les instructions d'outils et se met à répondre en prose au lieu d'agir, ou boucle sur la même action.

Il faut donc imposer un contexte d'au moins 32 000 tokens. Deux méthodes sous Ollama : une variable d'environnement globale sur le daemon, ou un Modelfile qui fixe num_ctx pour un modèle précis.

sudo systemctl edit ollama
# Ajouter dans le bloc [Service] :
# Environment="OLLAMA_CONTEXT_LENGTH=32768"
sudo systemctl restart ollama

launchctl setenv OLLAMA_CONTEXT_LENGTH 32768
# puis relancer l'application Ollama

cat > Modelfile.qwen-code <<'EOF'
FROM qwen3-coder:30b
PARAMETER num_ctx 32768
EOF
ollama create qwen3-coder-32k -f Modelfile.qwen-code
# puis OPENAI_MODEL=qwen3-coder-32k dans le .env

La seconde méthode est plus propre : elle ne touche pas aux autres modèles et le nom du modèle dérivé rappelle son réglage. Le coût est mémoire : le cache clé-valeur grandit avec le contexte. Pour un modèle 7B en Q4, 32 000 tokens de contexte ajoutent grossièrement 2 à 4 Go selon l'architecture et la quantification du cache. Si le modèle ne tient plus sur le GPU, Ollama décharge une partie des couches vers le CPU et la vitesse s'effondre : surveillez la colonne PROCESSOR de ollama ps, qui doit afficher 100 % GPU.

Côté Qwen Code, une limite de session existe aussi. Le réglage sessionTokenLimit dans le fichier de réglages plafonne le nombre de tokens cumulés d'une conversation ; une fois atteint, l'outil vous invite à compresser l'historique avec /compress ou à repartir de zéro avec /clear. Alignez cette valeur sur ce que votre modèle supporte réellement : un plafond de 32 000 pour un modèle servi avec num_ctx 32768 évite les troncatures silencieuses côté Ollama.

#5. Fichier de réglages et QWEN.md

Qwen Code lit un fichier settings.json à deux niveaux : ~/.qwen/settings.json pour l'utilisateur, et .qwen/settings.json dans le projet, qui prend le dessus. Les clés les plus utiles pour un usage local sont le plafond de session, le mode d'approbation des actions et les serveurs MCP. Les noms exacts ont bougé entre versions ; l'exemple ci-dessous suit la documentation publique et doit être confronté à la page Settings de votre version.

{
  "sessionTokenLimit": 32000,
  "contextFileName": "QWEN.md",
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/moi/mon-projet"]
    }
  }
}

Le fichier QWEN.md joue le même rôle que CLAUDE.md pour Claude Code ou AGENTS.md pour d'autres agents : c'est le mémo permanent injecté dans chaque session. Décrivez-y la stack, les commandes de build et de test, les conventions de nommage et ce que l'agent ne doit jamais toucher. La commande /init en génère une première version à partir du dépôt ; /memory show affiche ce que l'agent a réellement chargé.

# Projet API Facturation

- Python 3.12, FastAPI, tests avec pytest (`make test`).
- Ne jamais modifier les migrations existantes dans alembic/versions/.
- Toute nouvelle route doit avoir un test dans tests/api/.
- Style : ruff, lignes de 100 caractères max.

Le mode d'approbation contrôle ce que l'agent peut faire sans vous demander. Par défaut, chaque écriture de fichier et chaque commande shell attend votre validation. L'option --approval-mode auto-edit laisse passer les modifications de fichiers mais pas les commandes ; --yolo supprime toute confirmation. Avec un modèle local qui se trompe plus souvent qu'un modèle cloud, gardez le mode par défaut tant que vous n'avez pas confiance, et réservez --yolo à un dépôt propre et commité.

#6. Première session de travail

Une session Qwen Code se pilote en langage naturel, avec quelques raccourcis. Le préfixe @ insère un fichier ou un dossier dans la demande (@src/api/routes.py), le préfixe ! exécute une commande shell sans passer par le modèle, et les commandes commençant par / pilotent l'outil lui-même.

/help

Liste des commandes disponibles dans votre version.

/auth

Change la méthode d'authentification, utile pour basculer entre local et cloud.

/model

Affiche ou change le modèle en cours de session.

/stats

Tokens consommés et durée de la session : le premier réflexe quand les réponses se dégradent.

/compress

Résume l'historique pour libérer du contexte sans perdre le fil.

/clear

Repart d'une conversation vide ; le QWEN.md reste chargé.

/init et /memory

Génère puis inspecte le fichier de contexte du projet.

/mcp

État des serveurs MCP configurés et outils qu'ils exposent.

/quit

Quitte la session.

Un déroulé qui fonctionne bien avec un modèle local : demander d'abord une lecture (« explique comment l'authentification est gérée dans @src/auth/ »), puis une modification bornée (« ajoute une vérification d'expiration du jeton dans verify_token et un test correspondant »), puis la vérification (« lance make test et corrige ce qui casse »). Chaque étape tient dans quelques milliers de tokens et le modèle garde le fil. Les demandes du type « refactorise tout le module » dépassent ce que les modèles de 7 à 30B tiennent de façon fiable.

Pour l'automatisation, le mode non interactif accepte une demande en argument et rend la main une fois terminé. Il s'intègre dans un script ou un hook Git.

qwen -p "Relis le diff de git diff --cached et liste les problèmes potentiels, sans modifier de fichier"

#Limites de Qwen Code en local

Qwen Code est conçu autour des modèles Qwen3-Coder servis par Alibaba Cloud, et cela se sent dès qu'on le fait tourner sur un modèle local plus petit. Voici ce qu'il faut accepter.

Prompt système lourd

L'outil envoie une longue description d'outils à chaque tour. Sur un modèle 7B, cette seule consigne occupe une part du contexte et de l'attention du modèle, qui respecte moins bien le format d'appel d'outils que les modèles plus grands. Les boucles et les réponses en prose au lieu d'actions sont plus fréquentes qu'avec OpenCode ou Aider, qui ont des prompts plus compacts.

Vision réservée au cloud

La prise en charge des images (captures d'écran, maquettes) repose sur des modèles de vision servis en ligne. En local, elle ne fonctionne que si votre serveur expose un modèle multimodal compatible, ce qui n'est pas le cas de la plupart des modèles de code.

Pas de gestion native des modèles locaux

Contrairement à OpenCode, qui liste les modèles Ollama dans un menu, Qwen Code demande de saisir le nom du modèle et l'URL dans un fichier ou en option. Changer de modèle implique de modifier le .env ou de relancer avec --model.

Format de configuration mouvant

Le projet est jeune et son fichier settings.json a changé de structure au fil des versions. Un exemple trouvé sur un forum peut ne plus être valide. La documentation officielle, à la date de lecture, fait foi.

Édition par réécriture

Comme Gemini CLI dont il dérive, Qwen Code modifie les fichiers par remplacement de blocs. Aider, lui, applique des diffs unifiés et commite automatiquement chaque changement, ce qui rend l'historique plus lisible. Si vous voulez un commit par modification, Aider reste plus adapté.

En contrepartie, Qwen Code apporte un support MCP complet, des commandes de gestion de session matures héritées de Gemini CLI, un mode non interactif propre et une intégration qui s'étend aux IDE via extension. Il est pertinent si vous utilisez déjà les modèles Qwen et voulez un seul outil pour basculer entre le cloud Alibaba et votre GPU. Si l'objectif est uniquement le local, OpenCode ou Aider demandent moins de réglages pour arriver au même résultat. Nous ne publions pas de comparaison chiffrée : la qualité dépend d'abord du modèle choisi, pas de l'agent.

#Dépannage

L'agent répond en texte au lieu d'exécuter des actions

Soit le modèle ne gère pas l'appel d'outils (vérifiez sa fiche Ollama), soit le contexte est trop court et la description des outils a été tronquée. Appliquez l'étape 4 et vérifiez avec ollama ps que le modèle est bien chargé avec le bon num_ctx.

Erreur 404 ou « model not found »

Le nom dans OPENAI_MODEL ne correspond pas exactement à ollama list. Copiez-collez le nom avec son tag.

Erreur de connexion sur localhost:11434

Ollama n'est pas lancé, ou écoute sur une autre interface (OLLAMA_HOST). Testez avec curl http://localhost:11434/v1/models.

Réponses très lentes après quelques échanges

Le contexte a grossi et le modèle déborde du GPU. ollama ps affiche une part CPU. Réduisez num_ctx, passez à un modèle plus petit, ou lancez /compress plus tôt dans la session.

Qwen Code redemande une authentification OAuth

Les variables d'environnement ne sont pas lues : le .env n'est pas dans le dossier courant ou dans ~/.qwen. Lancez /auth dans la session et choisissez l'option OpenAI, ou passez les paramètres en ligne de commande pour isoler le problème.

Le modèle ignore le QWEN.md

Vérifiez avec /memory show que le fichier est chargé. Si contextFileName a été modifié dans settings.json, le nom doit correspondre.

Installation npm qui échoue avec EACCES

Droits insuffisants sur le dossier global de npm. Installez Node via nvm ou fnm plutôt que via le paquet système, puis relancez l'installation.

#Pour aller plus loin

Qwen Code n'est qu'un des agents terminal qui acceptent un serveur local. Les guides suivants couvrent les alternatives et le choix du modèle, ce que cet article laisse volontairement de côté.

• OpenCode + Ollama : un agent de code dans votre terminal
• Aider + Ollama : coder dans le terminal avec un agent 100 % local
• Goose (Block) : l'agent IA local dans votre terminal
• Meilleur LLM local pour coder : Devstral, Qwen3-Coder

Guide rédigé le 11 octobre 2026 ; les références sont le dépôt GitHub et la documentation de Qwen Code, ainsi que la documentation Ollama. Aucune mesure de vitesse ni de qualité n'a été réalisée pour cet article ; les repères de mémoire sont des ordres de grandeur. Les commandes et noms de clés évoluent avec les versions : vérifiez-les sur les pages ci-dessous avant de les copier.

• Dépôt GitHub QwenLM/qwen-code (README, installation, licence)
• Documentation officielle Qwen Code (authentification, settings, commandes)
• Documentation Ollama (API compatible OpenAI, variables d'environnement)