Mise en place d’un forward TCP local (socat)

1. Contexte

Cette documentation est un complément à l’article principal :

Dans l’architecture décrite dans l’article principal, Ollama est installé sur Windows, tandis que Codex CLI est exécuté depuis WSL2.
Cette configuration fonctionne, mais peut entraîner des instabilités réseau, en particulier lors de l’utilisation du streaming (SSE).

Objectif de cette page : proposer une technique simple, reproductible et local-first pour :

  • supprimer les interruptions de génération,
  • stabiliser les flux de réponses,
  • éviter les problèmes liés à l’IP Windows,
  • rendre l’utilisation de Codex CLI fiable au quotidien.

2. Problèmes rencontrés sans correctif

Sans mécanisme supplémentaire, il est fréquent d’observer :

  • stream disconnected before completion
  • réponses interrompues en cours de génération
  • latences/coupures aléatoires
  • comportement variable selon les redémarrages réseau ou WSL2

Ces problèmes ne sont pas liés :

  • ni aux modèles Ollama,
  • ni à Codex CLI en tant qu’outil,
  • ni à la puissance de la machine.

Ils proviennent principalement de la gestion réseau de WSL2 et de la sensibilité du streaming (SSE).

3. Pourquoi WSL2 pose problème avec Ollama

Quelques points clés à connaître :

  • WSL2 fonctionne dans une VM avec un réseau isolé
  • localhost dans WSL2 n’est pas le localhost Windows
  • l’IP Windows vue depuis WSL (172.x.x.1) peut changer après un redémarrage
  • Codex CLI peut tenter d’utiliser localhost côté client
  • les flux de streaming (SSE) sont sensibles aux micro-coupures réseau

Résultat : même si l’API Ollama répond, le flux peut être interrompu en cours de génération.

4. Principe de la solution

On crée un forward TCP local dans WSL2 pour exposer Ollama via :

  • http://localhost:11434 côté WSL2
  • redirigé automatiquement vers Ollama sur Windows (IP passerelle WSL)

Schéma logique :

Codex CLI (WSL2)
   |
   | http://localhost:11434
   v
Forward TCP (socat)
   |
   | http://<IP Windows vue par WSL>:11434
   v
Ollama (Windows)

Ainsi, Codex parle toujours à localhost (stable), et le forward s’occupe du reste.

5. Prérequis

Avant de continuer :

  • Ollama est installé et fonctionnel sur Windows
  • Codex CLI est installé et configuré selon la documentation principale
  • WSL2 est opérationnel
  • vous disposez de sudo dans WSL2
  • le port 11434 est disponible dans WSL2 (aucun serveur local ne doit l’occuper)

6. Installation de la solution (WSL2)

6.1 Installation de socat

Dans WSL2 :

sudo apt update
sudo apt install -y socat

6.2 Vérifier que le port 11434 est libre côté WSL2

sudo ss -ltnp | grep ':11434' || echo "OK: 11434 libre côté WSL2"

Si quelque chose écoute déjà sur 11434, il faut stopper ce processus avant d’aller plus loin.

6.3 Création du script de forward

Créer un script dédié (une seule fois) :

mkdir -p ~/.local/bin

cat > ~/.local/bin/ollama-forward <<'EOF'
#!/usr/bin/env bash
set -euo pipefail

WIN_IP=$(ip route | awk '/default/ {print $3; exit}')
echo "[ollama-forward] localhost:11434 -> $WIN_IP:11434"

exec socat TCP-LISTEN:11434,fork,reuseaddr TCP:$WIN_IP:11434
EOF

chmod +x ~/.local/bin/ollama-forward

Ce script :

  • détecte automatiquement l’IP Windows vue par WSL2,
  • écoute sur localhost:11434 côté WSL2,
  • redirige le trafic vers Ollama sur Windows.

7. Utilisation au quotidien

À chaque session de travail :

Terminal 1 — Lancer le forward

ollama-forward

Laisser ce terminal ouvert (le forward doit rester actif).

Terminal 2 — Lancer Codex CLI

codex

Si vous utilisez un alias, vous pouvez continuer à l’utiliser, mais l’essentiel est : forward d’abord, Codex ensuite.

8. Tests de vérification

Ces tests valident que le forward fonctionne correctement.

8.1 Test API native Ollama via localhost

curl http://localhost:11434/api/tags | head

Résultat attendu : JSON valide + liste des modèles.

8.2 Test API OpenAI-compatible (pour Codex)

curl http://localhost:11434/v1/models | head

Résultat attendu : JSON valide + modèles accessibles.

8.3 Test Codex minimal

codex "Réponds uniquement: OK"

Résultat attendu : réponse complète, sans interruption.

8.4 Test de génération simple (SSE)

codex "Explique en 5 phrases ce que fait cette fonction PHP : function divide(\$a, \$b) { return \$a / \$b; }"

Résultat attendu : génération fluide (pas de stream disconnected).

9. Bonnes pratiques

  • Toujours lancer le forward avant Codex CLI.
  • Utiliser un modèle léger (ex. 3B) pour les tests rapides.
  • Réserver les modèles lourds (ex. 30B) aux tâches complexes.
  • Arrêter le forward en fin de session avec Ctrl+C.
  • Si WSL2 ou Windows redémarre, relancer le forward.

10. Limitations connues / état actuel de Codex CLI

Cette section décrit des limitations observées avec Codex CLI v0.98.x utilisé avec un provider local comme Ollama.

10.1 Lecture automatique des fichiers

À ce jour, Codex CLI ne lit pas automatiquement les fichiers du projet dans ce contexte.
Conséquences :

  • un prompt du type « lis calc.php » peut échouer ou produire une réponse inventée
  • il faut souvent fournir le contenu manuellement ou via un script qui injecte le texte

10.2 Mode agent et outils

Codex CLI est conçu pour un mode “outils/agent”. Avec Ollama :

  • les appels d’outils (exec_command, read_mcp_resource, etc.) peuvent ne pas être exécutés
  • Codex peut afficher du JSON d’outils sans résultat réel

Ce n’est pas un problème de réseau : c’est une limitation de compatibilité/outillage dans ce mode.

10.3 Providers non-OpenAI

L’usage de providers non-OpenAI est possible, mais certaines fonctionnalités avancées sont absentes ou incomplètes :

  • exécution d’outils
  • lecture/écriture de fichiers pilotée
  • workflows “agent autonome”

Dans ce contexte, il est recommandé d’utiliser Codex CLI comme :

  • un LLM de raisonnement et génération
  • plutôt qu’un agent filesystem autonome complet

10.4 Évolutions possibles

Les évolutions à surveiller :

  • ajout d’un mode “chat-only”
  • support des outils côté client
  • meilleure intégration filesystem avec providers locaux

11. FAQ — Questions fréquentes

Pourquoi ai-je des erreurs stream disconnected before completion sans le forward ?

Parce que WSL2 a un réseau isolé, localhost diffère de Windows, et le streaming (SSE) est sensible aux micro-coupures.

Pourquoi ne pas utiliser directement l’IP Windows (172.x.x.1) ?

Ça peut fonctionner, mais :

  • l’IP peut changer après un redémarrage
  • certaines sessions longues deviennent instables

Le forward supprime la dépendance à cette IP et stabilise le flux.

Pourquoi utiliser socat ?

socat est :

  • léger
  • présent sur Debian/Ubuntu
  • très fiable pour un forwarding TCP simple
  • adapté aux flux longs (streaming)

Puis-je automatiser le lancement du forward ?

Oui (tmux, script de session, systemd user), mais il est conseillé de commencer en manuel :

  • plus simple à diagnostiquer
  • plus simple à arrêter (Ctrl+C)
  • évite les ports bloqués en arrière-plan

Dois-je lancer le forward à chaque session ?

Oui. Le forward est un processus temporaire qui doit être actif pendant l’utilisation de Codex.

Cette solution fonctionne-t-elle avec tous les modèles Ollama ?

Oui. Le forward est purement réseau. Il fonctionne avec 3B, 30B, etc.

Le forward a-t-il un impact sur les performances ?

En pratique, l’impact est négligeable. La stabilité gagnée compense largement.

Cette solution règle-t-elle les limites de Codex CLI (outils, fichiers) ?

Non. Elle règle uniquement la partie réseau/streaming, pas les limitations d’agent/outils.

12. A retenir

Le forward TCP via socat :

  • supprime les interruptions de streaming,
  • stabilise l’accès à Ollama depuis WSL2,
  • évite les problèmes d’IP changeante,
  • rend l’usage quotidien de Codex CLI plus fiable.

C’est une technique pragmatique, simple à maintenir, alignée avec une approche local-first.

13. Références