Codex CLI + Ollama sous WSL2 (Windows 11)

Introduction

Cette documentation explique comment utiliser Codex CLI comme agent de développement en ligne de commande, connecté à Ollama pour exécuter un modèle local (ex. Qwen Coder), le tout dans un environnement WSL2 (Debian) sous Windows 11 Pro.

Le contexte de départ est le suivant :

• Windows 11 Pro déjà installé
• WSL2 (Debian) déjà opérationnel
• VS Code déjà installé et relié à WSL2
• Ollama déjà installé et lancé sur Windows

L’objectif n’est pas de remplacer l’usage quotidien dans VS Code, mais d’ajouter un agent autonome capable de traiter des tâches globales (audit, refactor massif, migration, génération de modules complets), en complément d’un assistant IDE.

Architecture globale

• Ollama : tourne sur Windows et héberge les modèles locaux
• WSL2 (Debian) : exécute Codex CLI
• Codex CLI : agent de mission (lecture du repo, planification, modifications multi-fichiers)
• VS Code + Continue : copilote IDE (déjà en place, inchangé)

Le modèle local (ex. qwen3-coder:30b) est exécuté exclusivement par Ollama. Codex agit comme orchestrateur et interface agent.

Installation

1. Préparer Node.js dans WSL2

Codex CLI nécessite une version moderne de Node.js. L’installation via les dépôts Linux est à éviter.

Installer NVM (Node Version Manager) :

curl -fsSL https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
exec bash

Installer une version LTS récente de Node.js :

nvm install 20
nvm use 20
nvm alias default 20

Vérification :

node -v
npm -v

2. Installer Codex CLI

Toujours dans WSL2 :

npm install -g @openai/codex

Vérifier l’installation :

codex --version

3. Rendre Ollama accessible depuis WSL2

Ollama tourne sur Windows. Il doit écouter sur toutes les interfaces pour être accessible depuis WSL2.

Dans PowerShell (Windows) :

setx OLLAMA_HOST "0.0.0.0:11434"

Quitter puis relancer Ollama.

Dans WSL2, identifier l’IP Windows côté WSL (exemple typique) :

ip route | awk '/default/ {print $3}'

Tester l’API Ollama :

curl http://<IP_WINDOWS>:11434/api/tags
curl http://<IP_WINDOWS>:11434/v1/models

Les modèles locaux doivent apparaître.

4. Configurer Codex pour utiliser Ollama par défaut

Créer le fichier de configuration Codex :

mkdir -p ~/.codex

Créer ~/.codex/config.toml :

# Forcer Codex à utiliser Ollama comme provider par défaut
model_provider = "ollama"
model = "qwen3-coder:30b"

[model_providers.ollama]
name = "Ollama (local)"
base_url = "http://<IP_WINDOWS>:11434/v1"
env_key = "OLLAMA_API_KEY"
wire_api = "responses"

Définir une clé factice (requise par Codex, non utilisée par Ollama) :

export OLLAMA_API_KEY="ollama"

Si l'IP WINDOWS change alors il faut rendre cela plus robuste :

WIN_IP=$(ip route | awk '/default/ {print $3; exit}')
export OPENAI_BASE_URL="http://$WIN_IP:11434/v1"
export OPENAI_API_KEY="ollama"

source ~/.bashrc
echo $OPENAI_BASE_URL

Pour vérifier si OLLAMA est ok avant la session de travail :

WIN_IP=$(ip route | awk '/default/ {print $3; exit}')
curl -sS "http://$WIN_IP:11434/api/tags" >/dev/null && echo "Ollama OK via $WIN_IP" || echo "Ollama unreachable"

5. (Optionnel) Alias pratique

Ajouter un alias pour lancer Codex rapidement :

cat >> ~/.bashrc <<'EOF'
codex-ollama() {
  export OLLAMA_HOST="http://<IP_WINDOWS>:11434"
  export OLLAMA_API_KEY="ollama"
  codex "$@"
}
EOF

source ~/.bashrc

Commandes pratiques (une fois tout installé)

Lancer Codex en local

codex

Ou avec l’alias :

codex-ollama

La bannière doit afficher le modèle local (ex. qwen3-coder:30b).

Commandes utiles dans Codex

• Changer de modèle :

  /model
  

• Analyser un projet sans modifier :

  Analyse ce projet et explique son architecture sans modifier de fichiers.
  

• Audit léger :

  Propose des améliorations sans appliquer de changements.
  

Sécurité et flux de données

• Le modèle, le raisonnement et le code sont exécutés localement via Ollama.
• Aucun fichier source ni prompt métier n’est envoyé à OpenAI.
• Codex CLI communique avec OpenAI uniquement pour :
  • l’authentification
  • l’orchestration de l’outil
  • des métadonnées techniques (version, état de session)

Ce setup est sûr pour le code, mais pas strictement air-gapped.

Différences avec Continue (agent IDE) dans VS Code

Continue (VS Code + Ollama)

• Agent centré IDE
• Travail sur le contexte ouvert
• Autocomplétion et refactor ciblé
• Très interactif
• Contrôle humain permanent
• 100 % local / open-source

Codex CLI (WSL2 + Ollama)

• Agent de mission
• Vision globale du dépôt
• Modifications multi-fichiers
• Planification autonome
• Très efficace pour :
  • refactor massif
  • migration
  • audit de code
  • génération de modules complets

Synthèse

Les deux outils sont complémentaires.

Cas d’usage concrets

Chaque cas suit la même logique : lecture seule → plan → exécution par étapes.

Exemple 1 — Refactor global (cohérence et lisibilité)

Contexte : un projet qui a grandi vite (noms incohérents, duplications, architecture qui dérive).

Objectif : améliorer la lisibilité et la maintenabilité sans changer le comportement.

Approche recommandée :

• commencer par une analyse lecture seule
• demander un plan en étapes
• appliquer une étape à la fois, avec validation

Prompt (lecture seule)

Analyse ce dépôt et propose un plan de refactor global (noms, structure, duplications).
N’applique aucun changement sans validation.

Prompt (itération 1)

Applique uniquement l’étape 1 du plan.
Montre les changements proposés (diff ou résumé) avant application.

Exemple 2 — Migration technique (montée de version)

Contexte : montée de version (langage, dépendances, framework) avec risques de régressions.

Objectif : identifier les points bloquants, puis migrer progressivement.

Approche recommandée :

• audit de compatibilité
• checklist d’actions
• migration incrémentale + tests

Prompt (audit, lecture seule)

Analyse ce projet et liste les étapes nécessaires pour une migration vers une version plus récente.
Ne modifie aucun fichier.

Prompt (exécution contrôlée)

Applique la première étape de la migration.
Montre les modifications proposées avant application.

Exemple 3 — Audit de code (qualité, sécurité, performance)

Contexte : on veut savoir « où ça fait mal » avant de toucher au code.

Objectif : repérer les risques et prioriser les actions.

Ce que l’audit peut couvrir :

• qualité (lisibilité, dette technique, complexité)
• sécurité (patterns risqués, entrées non filtrées, secrets en clair)
• performance (goulots d’étranglement évidents, accès IO inutiles)

Prompt (lecture seule)

Réalise un audit de ce dépôt et liste les risques techniques et axes d’amélioration.
Classe les points par priorité (critique / important / amélioration).
Ne modifie pas le code.

Exemple 4 — Ajout de fonctionnalité (module complet)

Contexte : ajout d’un module complet (routes, services, configuration, docs, tests).

Objectif : gagner du temps sur la structure et la création des fichiers, puis affiner ensuite dans l’IDE.

Approche recommandée :

• demander une proposition + plan (lecture seule)
• appliquer fichier par fichier / étape par étape
• terminer par des ajustements fins (IDE)

Prompt (proposition, lecture seule)

Propose une implémentation complète de la fonctionnalité (structure, fichiers, configuration).
Présente un plan avant toute modification.

Prompt (implémentation par étapes)

Implémente uniquement l’étape 1.
Présente les changements proposés avant application.

Prompt (documentation)

Ajoute ou mets à jour une documentation README expliquant l’architecture et le fonctionnement.
Propose les changements avant application.

Astuce pratique (valable pour tous les exemples)

Si la mission devient floue ou si le modèle semble « décrocher » :

Résume ce que tu as compris jusqu’ici et liste ce qu’il reste à faire.
Ne poursuis aucune action.

Bonnes pratiques

• Lancer Codex à la racine du projet
• Commencer par une analyse sans modification
• Valider explicitement chaque action proposée
• Utiliser Continue pour le quotidien, Codex pour les missions

Performances, limites et comparaison avec les modèles cloud

Le modèle local 30B est-il suffisant ?

Oui, un modèle de l’ordre de 30 milliards de paramètres (30B) constitue aujourd’hui le meilleur compromis en local pour un usage de développement avancé.

Il est particulièrement adapté pour :

• refactor sérieux et structuré
• audit de code (qualité, dette technique, architecture)
• migration technique (langage, framework, version)
• génération de modules complets
• documentation technique

En dessous de 13B, les modèles deviennent vite fragiles pour un usage « agent ». Au-dessus de 30–40B, les gains existent mais deviennent marginaux au regard des contraintes matérielles.

Lenteur : est-ce normal ?

Oui. Un agent local 30B peut paraître lent, surtout comparé à un service cloud.

Les facteurs principaux :

• puissance GPU / quantité de VRAM
• niveau de quantization (Q4, Q6, Q8…)
• taille du contexte fourni
• complexité de la tâche (raisonnement > simple génération)

Un agent qui réfléchit, planifie et produit du code structuré n’est pas censé être instantané. La priorité est la cohérence et la stabilité, pas la vitesse brute.

Risques d’échec ou de blocage

Oui, un modèle local peut ne pas aller au bout dans certains cas :

• prompt trop large ou trop vague
• dépôt très volumineux analysé en une seule fois
• contraintes mémoire trop fortes
• demande de sortie trop longue en un seul bloc

Bonnes pratiques pour éviter ces situations :

• toujours commencer par une analyse sans modification
• demander un plan d’action détaillé
• découper la mission en étapes
• appliquer une étape à la fois avec validation

Le comportement est proche de celui d’un développeur humain : plus la tâche est bien cadrée, plus le résultat est fiable.

Comparaison avec un modèle cloud (ex. Codex 5.x)

Puissance de raisonnement

• Les modèles cloud de dernière génération conservent un avantage en raisonnement abstrait, gestion des cas limites et maintien du contexte très long.
• Un 30B local reste néanmoins très performant sur du code réel et des problématiques concrètes.

Stabilité sur les longues missions

• Le cloud tolère mieux les prompts flous et les missions très longues sans découpage.
• En local, un bon pilotage est indispensable pour maintenir la qualité sur la durée.

Écart réel en pratique

L’écart de « confort » existe, mais l’écart de résultats est bien plus faible qu’on ne l’imagine, à condition d’adopter une méthode de travail adaptée au local.

Différence de philosophie : local vs cloud

• Local (30B) :

  • contrôle total
  • données conservées sur la machine
  • coût nul par requête
  • nécessite un pilotage rigoureux

• Cloud (Codex 5.x) :

  • puissance brute élevée
  • très grande robustesse
  • tolérance aux prompts imparfaits
  • dépendance réseau et service tiers

On peut résumer ainsi :

Le cloud est plus indulgent. Le local est plus exigeant, mais plus contrôlable.

Recommandation d’usage

• Utiliser le 30B local comme agent principal pour la majorité des tâches.
• Garder un modèle plus léger (3B / 7B) pour les interactions rapides.
• Découper systématiquement les missions longues.
• Réserver le cloud à des cas exceptionnels (urgence, refactor massif critique, contraintes fortes de délai).

Prompts optimisés pour un modèle local 30B

Principes généraux

• Toujours préciser le périmètre (lecture seule / modification)
• Préférer des objectifs clairs et bornés
• Éviter les demandes trop larges
• Forcer le raisonnement avant l’action

Analyse globale (lecture seule)

Analyse ce dépôt et explique son architecture et ses composants clés. Ne modifie aucun fichier.

Planification avant action

Propose un plan détaillé en étapes numérotées. Ne modifie aucun fichier.

Exécution contrôlée

Applique uniquement l’étape 1. Montre les changements avant application.

Audit de code

Réalise un audit et classe les problèmes par priorité. Ne modifie aucun fichier.

Recentrage

Résume ce que tu as compris et liste ce qu’il reste à faire. N’agis pas.

FAQ – Pilotage du modèle local (30B)

Le découpage des tâches est-il automatique ?

Non. Le modèle peut proposer un découpage, mais l’exécution doit être pilotée manuellement étape par étape.

Où Codex stocke-t-il ses données ?

Codex ne stocke aucune donnée dans le dossier de travail.

• Configuration uniquement dans ~/.codex/
• Mémoire de session volatile
• Aucune création de fichier sans validation explicite

Dépannage / erreurs courantes

Cette section recense les problèmes les plus fréquemment rencontrés avec Codex CLI + Ollama + WSL2, ainsi que leurs causes et solutions.

Codex démarre sur un modèle cloud au lieu du modèle local

Symptôme

• La bannière Codex affiche gpt-* ou codex-*
• Le menu de sélection propose uniquement des modèles cloud

Cause

• Le provider Ollama n’est pas défini par défaut
• Le fichier ~/.codex/config.toml est absent ou incorrect
• Une variable OPENAI_BASE_URL ou OPENAI_API_KEY est encore définie

Solution

unset OPENAI_BASE_URL OPENAI_API_KEY OPENAI_MODEL

Vérifier que model_provider = "ollama" est bien configuré.

Erreur : No running Ollama server detected

Cause

• Ollama n’est pas accessible depuis WSL2

Solution

• Vérifier que Ollama écoute sur 0.0.0.0:11434
• Tester depuis WSL2 :

curl http://<IP_WINDOWS>:11434/v1/models

Codex est très lent ou semble bloqué

Cause

• Tâche trop large pour un modèle 30B
• Contexte trop volumineux

Solution

• Découper la mission
• Demander un plan avant exécution

Réponse incomplète ou arrêt en cours de génération

Cause

• Surcharge du modèle
• Prompt trop dense

Solution

Résume ce que tu as compris jusqu’ici et liste ce qu’il reste à faire. N’agis pas.

Codex modifie trop de fichiers d’un coup

Cause

• Absence de découpage

Solution

Propose un plan détaillé. N’applique aucune modification.

Codex ne voit pas tous les fichiers du projet

Cause

• Codex lancé hors de la racine du projet

Solution

• Lancer Codex depuis le dossier racine (présence de .git)

Règle de dépannage à retenir

Si Codex se comporte mal, le problème vient presque toujours du périmètre ou du pilotage, pas du modèle.

Le mot de la fin

Codex CLI couplé à Ollama et à un modèle local 30B permet de disposer d’un agent de développement puissant, autonome et maîtrisé, complémentaire d’un agent IDE comme Continue.