Superviser les agents Codex : les quatre signaux qui disent vraiment quelque chose

« Le processus tourne » n'est pas une réponse utile

Un agent Codex qui tourne depuis deux heures peut être dans trois états très différents. Il peut progresser, avaler un refactor et toucher un fichier toutes les quelques minutes. Il peut être bloqué dans une boucle — relire les mêmes fichiers, reposer les mêmes questions, brûler des tokens sans avancer. Ou il peut attendre un rate limit, techniquement vivant mais sans rien produire.

N'importe quel outil de supervision classique — htop, systemctl status, pings d'uptime — répondra la même chose pour les trois cas : le processus est up. Cette réponse est pire qu'inutile, parce qu'elle vous fait croire que tout va bien alors que deux des trois issues signifient que vous payez pour rien.

Superviser un agent de code n'est pas le même problème que superviser un serveur web. Voici les signaux que nous surveillons chez Office Claws, pourquoi ils comptent, et ce que chacun dit que ps aux ne dit pas.

Signal 1 : activité — ce que l'agent fait à l'instant

Le plus utile à savoir sur un agent qui tourne, c'est s'il est en train de réfléchir, de taper ou à l'arrêt. Pas « a-t-il loggé une ligne dans les cinq dernières minutes » — c'est un indicateur retardé. On parle de l'état en direct : le flux de tokens passe-t-il, lit-il un fichier, attend-il une commande shell.

Sur Office Claws chaque agent a un bureau dans le pixel office, et le personnage assis à ce bureau est dans l'un des trois états animés : marchant, tapant ou inactif. Cette animation n'est pas un gadget — c'est une projection en direct de l'état réel de l'agent, alimentée par le même flux RPC qui fait tourner le fil d'activité. Vous jetez un œil au bureau et vous savez sans lire un log quels agents travaillent et lesquels sont au parking.

Les équivalents textuels fonctionnent aussi. La Codex CLI émet des événements au fil de son exécution — appels d'outils, lectures de fichiers, tours de modèle. Faire un tail sur ce flux d'événements vous apprend la même chose qu'un spinner, en terminal. L'important est de distinguer « processus vivant » de « processus qui fait quelque chose ».

Signal 2 : output — les fichiers changent-ils vraiment

Un agent qui « tape » dans son terminal mais n'a modifié aucun fichier depuis trente minutes ne travaille pas. Il converse avec lui-même. C'est le mode de défaillance le plus fréquent qu'on voit sur les tâches longues — le modèle entre en discussion avec son propre bloc-notes, ne produit pas de diff, et brûle une heure avant que quiconque ne le remarque.

La façon peu coûteuse de l'attraper : surveiller l'arbre de travail.

# On the VPS, log file changes every minute
while true; do
  find /repo -type f -newer /tmp/last-check 2>/dev/null | wc -l
  touch /tmp/last-check
  sleep 60
done

Si ce nombre reste à zéro sur trois fenêtres consécutives pour une tâche censée produire des diffs, l'agent est bloqué. Interrompez-le, résumez ce qu'il a appris, et redémarrez avec un prompt plus serré. Le laisser continuer est presque toujours un gaspillage.

Un signal apparenté : la cadence des commits. On demande à nos builder agents de committer après chaque changement logique. Un agent qui n'a pas committé depuis une heure sur une tâche commencée par « refactore ces 20 fichiers » vous dit quelque chose — le plus souvent que la tâche était sous-spécifiée.

Signal 3 : coût — tokens, messages et la falaise du rate limit

Le Codex par abonnement (ChatGPT Plus ou Pro) ne facture pas au token, mais plafonne le nombre de messages par fenêtre glissante. Le Codex en mode API facture au token sans plafond. Les deux se soucient du volume, pour des raisons différentes.

Le cas abonnement est le dangereux pour la supervision, parce qu'un agent rate-limité semble tourner. Le processus est up, le terminal ouvert, la CLI attend. Mais chaque nouvelle requête est throttlée et rien ne revient. Sans indicateur de rate limit vous ne saurez rien avant d'aller voir l'output et d'y trouver six heures de vide.

Nous affichons les messages restants directement dans le fil d'activité d'Office Claws — dès que le compteur tombe sous 10 %, le badge de l'agent passe à l'ambre. On peut câbler la même chose dans n'importe quel setup : la Codex CLI expose les headers de limite, et un petit script jq peut déclencher une notification lorsque le compteur franchit un seuil.

Signal 4 : état de blocage — l'échec silencieux

La classe d'échec la plus difficile à attraper est l'agent qui produit techniquement de l'output sans avancer. On voit trois formes de cela régulièrement :

• Boucle de lecture. L'agent relit les mêmes cinq fichiers, résume chaque fois un peu différemment, n'écrit jamais rien. La consommation de tokens est réelle, le progrès nul
• Spirale test-fix-test. L'agent lance les tests, voit un échec, « corrige » d'une façon qui crée un nouvel échec, relance les tests, à l'infini. Chaque cycle produit un diff, donc la supervision naïve de l'output ne l'attrape pas
• Tempête de retry sur rate limit. L'agent tape le plafond, réessaie toutes les quelques secondes, logge « retrying... » indéfiniment. CPU bas, mémoire basse, les logs défilent, rien ne se passe

L'indice commun aux trois : la répétition. Le log d'un agent sain est une suite d'actions différentes — lit ce fichier, puis celui-là, puis écrit celui-ci, puis lance cette commande. Le log d'un agent coincé, ce sont les mêmes trois lignes entrelacées pendant une heure. L'alarme la plus simple qui attrape ça de façon fiable est la métrique « appels d'outils uniques dans les 20 dernières minutes ». Si la réponse est deux ou trois, l'agent est en boucle.

Comment Office Claws fait remonter ces signaux

Chacun des points ci-dessus est implémenté dans l'application de bureau depuis ce mois-ci :

• Fil d'activité — flux en direct de chaque appel d'outil, lecture de fichier, commande et tour de modèle, pour tous les agents, unifié dans un panneau
• États du pixel office — marche / tape / inactif, alimentés par le flux RPC depuis le VPS de l'agent
• Stream de logs — stdout/stderr complet par agent, scrollback inclus, filtrable par agent
• Badges de rate limit — indicateur coloré par agent quand les messages restants tombent sous le seuil d'alerte
• Détection d'inactivité — les agents qui n'ont rien produit sur une fenêtre configurable sont signalés dans le bureau ; l'animation du personnage passe en idle et le badge du bureau devient jaune

Le point n'est pas qu'il faut utiliser Office Claws pour avoir ça. Le point est que ces quatre signaux sont ce qu'un dashboard d'agent de code doit afficher, et que tout setup maison qui en saute un laissera passer le mode de défaillance correspondant.

Ce qu'il ne faut pas superviser

Trois choses qui semblent devoir compter et qui en général ne comptent pas :

1. CPU et mémoire du VPS. Une session Codex CLI utilise ~200 Mo de RAM et quasi aucun CPU — le travail se passe dans le modèle, pas sur le droplet. Si votre agent plafonne en CPU c'est qu'il y a un souci dans votre code, pas avec l'agent
2. Uptime réseau. Tailscale gère les reconnexions tout seul. Une coupure de 30 secondes n'affecte pas une session d'agent en cours. Y poser une alerte ne génère que du bruit
3. « Toujours en marche après N heures » comme signal de succès. La durée d'exécution seule est un piège — un agent coincé tournera joyeusement 24 heures. Couplez la durée à l'output pour obtenir quelque chose de significatif

Un setup maison minimal

Si vous n'utilisez pas Office Claws et voulez l'équivalent, voici le chemin le plus court :

# /etc/systemd/system/codex-watch.service (simplified)
# Logs activity, tracks file changes, alerts on stuck state
 
*/5 * * * * /opt/codex-watch/check.sh >> /var/log/codex-watch.log

Dans check.sh :

1. Parsez les 20 dernières minutes du log d'événements Codex et comptez les invocations d'outils uniques
2. Comptez les fichiers modifiés sous /repo dans les 20 dernières minutes
3. Lisez le header de rate limit de la réponse API la plus récente
4. Si unique-tools ≤ 2 et files-changed = 0 sur deux fenêtres consécutives, déclenchez un webhook

Voilà tout. Quarante lignes de shell, un cron, un webhook vers l'endroit où vous lisez vos notifications. Grossier, mais ça attrape les trois modes de défaillance qui comptent. Le pixel office est plus joli à regarder, mais il résout le même problème.

La version en une phrase

Superviser un agent de code, ce n'est pas savoir si le processus est vivant — c'est savoir si le travail avance. L'activité dit il fait quelque chose, l'output dit il produit quelque chose, le coût dit il peut continuer, l'état de blocage dit il progresse vraiment. Regardez les quatre. N'en croyez aucun pris isolément.

Lectures liées

• How to Run Multiple Codex Agents at Once — la supervision se complique à mesure qu'on ajoute des agents
• Long-Running Codex Tasks — pourquoi les tâches nocturnes ont besoin des quatre signaux, pas seulement de l'uptime
• Cutting AI Agent Costs — le signal de coût en détail, y compris quand passer de Plus à Pro