Codex CLI Integration

1. Quoi ? — Définition et contexte

La Codex CLI Integration est une famille de quatre workflows N8N qui industrialisent l’usage du CLI Codex d’OpenAI au sein de la stack ai-stack/cli-ollama. Codex est devenu le provider par défaut de CLI Ollama (commit 195d432) : sans automatisation autour de son authentification et de son streaming, le tooling AI casserait silencieusement à la première expiration de session OAuth.

Pourquoi une famille de workflows ?

Codex CLI s’authentifie via OAuth device-code. La session se rafraîchit en lisant ~/.codex/auth.json, mais expire après plusieurs jours d’inactivité. Une seule expiration silencieuse coupe tous les agents Telegram, l’IA Router, les sub-workflows d’approbation et la chaîne MCP. La famille existe pour détecter, relancer, confirmer et streamer Codex de bout en bout.

Périmètre

Workflow	ID	Nodes	Trigger	Rôle
Codex Auth Watchdog	PaBIkK76OPcHQr53	5	Schedule (6h)	Surveille la fraîcheur de auth.json et alerte via Notification Hub
Codex Reauth Flow	sLAIrqJDGRUE6Jmj	5	Execute Workflow	Démarre une session device-auth et envoie URL + code via Telegram
Codex Reauth Callback Actions	xpHr32uMtdEE0M3Q	8	Execute Workflow	Traite les boutons [Done] / [Cancel] après réauth
Codex Progress Handler	w8r9JcpArIElZxRe	11	Webhook /codex-progress	Buffer le streaming Codex et édite le message Telegram

Endpoints CLI Ollama consommés

Endpoint	Méthode	Consommé par
/api/codex/auth/status	GET	Auth Watchdog
/api/codex/reauth	POST	Reauth Flow
/api/codex/reauth/{id}/status	GET	Callback Actions ([Done])
/api/codex/reauth/{id}	DELETE	Callback Actions ([Cancel])
/webhook/codex-progress (N8N)	POST	Codex provider (streaming)

Architecture visuelle

---

2. Pourquoi ? — Enjeux et motivations

Problèmes résolus

Problème	Sans la famille	Avec la famille
Expiration silencieuse	Toutes les requêtes AI échouent sans signal	Watchdog alerte à J-2 et J-0 de l’expiration
Réauth manuelle SSH	Connexion VPS + docker exec + copier-coller du code	Bouton Telegram + device-code envoyé en push
Spawn hors conteneur	Codex CLI lancé sur l’hôte écrit dans le mauvais ~/.codex	Spawn in-container, écrit dans /home/cli/.codex/auth.json
Erreurs typées floues	« subprocess failed » non actionnable	Erreur auth_expired détectée côté CLI Ollama
Streaming Codex perdu	Long run = silence radio Telegram pendant 30s+	Edit-in-place du message via buffer DT
Annulation impossible	Session device-auth zombie en cas d’abandon	[Cancel] tue le subprocess via DELETE /reauth/{id}

Pourquoi un Watchdog et pas une alerte à la première erreur ?

Découvrir l’expiration au moment d’un appel utilisateur dégrade l’UX : le message Telegram retourne une erreur cryptique et l’utilisateur doit ouvrir la documentation. Le Watchdog tourne toutes les 6 heures et anticipe :

Seuil	Sévérité	Action
auth.json absent	critical	Alerte immédiate avec commande codex login --device-auth
age > 8 jours	critical	Re-auth fortement recommandée
age > 6 jours	warning	Surveillance, re-auth proche
last_refresh illisible	warning	Fichier corrompu à inspecter

Les seuils 6/8 jours offrent une fenêtre confortable (~48h) entre la première alerte et la vraie panne.

Pourquoi extraire le Callback Handler du Reauth Flow ?

Le Reauth Flow envoie le message Telegram, mais le callback [Done] / [Cancel] est asynchrone : l’utilisateur peut cliquer 10 minutes plus tard. Le séparer en sub-workflow dédié (8 nodes) suit la même logique que NH Callback Handler (#276) : routage précoce via le Telegram Orchestrator, bypass de la dedup, pas d’état partagé.

Évolutions récentes

Commit	Apport
edfcf79	Erreur typée auth_expired côté CLI Ollama (détection au lieu de subprocess error)
9771a97	Spawn device-auth in-container + détection auth missing
ba0f7ae	Bump n8n-exports avec corrections de reauth
32c3282	Webhook streaming /webhook/codex-progress côté provider
7ee7dbd	Chat Codex edit-in-place + streaming temps réel Telegram

---

3. Comment ? — Mise en œuvre technique

Composants

Workflow	ID	Nodes	Rôle
Codex Auth Watchdog	PaBIkK76OPcHQr53	5	Cron 6h, check /api/codex/auth/status, alerte Hub
Codex Reauth Flow	sLAIrqJDGRUE6Jmj	5	Spawn device-auth, push Telegram avec URL + code
Codex Reauth Callback Actions	xpHr32uMtdEE0M3Q	8	Switch sur callback, confirme ou annule la session
Codex Progress Handler	w8r9JcpArIElZxRe	11	Buffer DT + edit-in-place du message Telegram

Codex Auth Watchdog (5 nodes)

Chaîne linéaire : Schedule 6h → Get Codex Auth Status (HTTP GET) → Evaluate Auth Health (Code) → IF Should Alert → Call Notification Hub (Execute Workflow).

Le node Evaluate Auth Health applique deux seuils :

var WARNING_AGE = 6 * 86400;   // 6 jours
var CRITICAL_AGE = 8 * 86400;  // 8 jours

if (!s.exists) {
  severity = 'critical';
  title = 'Codex auth manquante';
} else if (age > CRITICAL_AGE) {
  severity = 'critical';
} else if (age > WARNING_AGE) {
  severity = 'warning';
}

L’appel au Notification Hub délègue ensuite la dédup, les quiet hours et le routage Telegram. Le watchdog ne se préoccupe que de l’évaluation, jamais du transport.

Schedule trigger à 6 heures

Un cron toutes les 6h offre 4 contrôles par jour. Cumulé avec le seuil à 6 jours, l’utilisateur reçoit au moins 8 alertes warning avant que auth.json n’atteigne 8 jours et bascule en critical — laissant ~48h de marge pour ouvrir un terminal.

Codex Reauth Flow (5 nodes)

Déclenché par Execute Workflow (depuis un agent conversationnel ou un alias /codex-reauth). Le node Start Reauth Session fait un POST http://cli-ollama:11434/api/codex/reauth :

{
  "reauth_id": "rau_xxx",
  "device_url": "https://auth.openai.com/device",
  "user_code": "ABCD-EFGH",
  "host_command": "docker exec -it cli-ollama codex login --device-auth",
  "ttl_seconds": 600
}

Le node Format Reauth Message construit un message Telegram avec inline keyboard [Ouvrir l'URL] [Done] [Cancel]. Send Reauth Prompt envoie le message, Return Reauth Started retourne le reauth_id au workflow appelant pour qu’il puisse corréler le callback ultérieur.

Codex Reauth Callback Actions (8 nodes)

Routé depuis le Telegram Orchestrator quand callback_data commence par codex_reauth_. Chaîne :

1. Execute Workflow Trigger — reçoit chatId, messageId, callbackData, reauthId.
2. Answer Callback — ferme le spinner Telegram immédiatement.
3. Switch Action — done vs cancel.
4. Branche done → Check Reauth Status (GET /api/codex/reauth/{id}/status) → Format Done Result.
5. Branche cancel → Cancel Reauth Session (DELETE /api/codex/reauth/{id}) → Format Cancel Result.
6. Convergence sur Edit Original Message (Telegram edit) qui remplace le prompt par le résultat.

Idempotence du Cancel

Le DELETE /api/codex/reauth/{id} tue le subprocess Codex CLI. Si l’utilisateur clique [Done] après avoir cliqué [Cancel], le GET /status retournera 404 reauth_session_not_found. Le node Format Done Result doit gérer ce cas pour ne pas re-throw.

Codex Progress Handler (11 nodes)

Quand le provider Codex (cli-ollama/app/services/providers/codex.py) émet un événement de progression, il fait un POST vers http://n8n:5678/webhook/codex-progress avec :

{
  "chatId": "5883063462",
  "messageId": 12345,
  "sessionId": "tg_xxx",
  "progressText": "Reading 3 files...",
  "isFinal": false
}

Chaîne du handler :

1. Webhook Trigger (path codex-progress).
2. Parse Body — extrait chatId, messageId, progressText.
3. DT Get Buffer — Data Table indexée par messageId (état de l’édition).
4. IF Buffer Exists — première progression ou suite ?
5. Code Decide — décide entre edit (append au buffer), split (nouveau message si > limite Telegram) ou skip.
6. IF Should Edit / IF Need Split — routage selon la décision.
7. Edit Message (Telegram) ou Send New Message.
8. Prep DT Update + DT Update Buffer — persiste le nouvel état pour la prochaine progression.

Le buffer évite l’enchaînement d’éditions Telegram bloquant (rate-limit) et permet l’effet « live » sans saturer l’API.

Sécurité

Surface	Protection
/api/codex/*	Endpoint interne du réseau ai-internal, non exposé via Caddy
/webhook/codex-progress	Webhook N8N interne, bloqué par Caddy depuis l’extérieur
Spawn codex login --device-auth	Exécuté dans le conteneur cli-ollama avec ~/.codex isolé du host
Session reauth TTL	600 secondes — au-delà le subprocess est tué automatiquement

---

4. Et si ? — Perspectives et limites

Limites actuelles

Limite	Impact	Mitigation
Watchdog mono-instance	Une seule installation Codex surveillée	Suffisant pour un usage solo VPS
Pas de re-auth automatique	L’utilisateur doit toujours cliquer	Sécurité OAuth : le device-code exige une interaction humaine
Buffer DT non sharded	Une seule conversation Codex active recommandée	Pour multi-utilisateur, partitionner par chatId + messageId
Pas de métrique Prometheus	Pas de dashboard Grafana sur la santé Codex	TODO : exporter codex_auth_age_seconds depuis CLI Ollama
Cancel best-effort	Si le subprocess est déjà bloqué sur stdin, le SIGTERM peut prendre quelques secondes	TTL 600s garantit la libération

Scénarios d’évolution

Si plusieurs providers à surveiller :

• Généraliser le Watchdog en AI Auth Watchdog paramétré (provider=codex|gemini|claude)
• Endpoints unifiés /api/auth/status?provider=...
• Un cron unique pour tous les providers

Si besoin de pré-auth proactif :

• Tâche cron à J-1 qui démarre déjà la session device-auth et envoie le code en avance
• L’utilisateur prépare la re-auth sans urgence

Si volume de progressions explose :

• Throttle côté provider (1 update toutes les 2s minimum)
• Aggrégation Redis (clé progress:{messageId}) puis flush périodique
• Sortie alternative ntfy pour les longs runs en arrière-plan

Si multi-utilisateur :

• Data Table codex_sessions indexée par chatId
• Chaque utilisateur a son propre auth.json (impossible avec le CLI actuel)
• Workaround : un compte Codex partagé + traçabilité par session_id Redis

---

Pages liées

Infrastructure

• N8N en mode Queue — Backend qui exécute la famille
• Notify Stack — DIUN et ntfy en aval du Watchdog

Workflows

• Notification Hub — Cible des alertes du Watchdog
• Telegram Orchestrator — Route les callbacks codex_reauth_*
• Système conversationnel — Consommateur principal du provider Codex
• Question Hub — Modèle d’interaction Telegram asynchrone

Référence

• Glossaire — Device-code, Webhook, Buffer