Codex-Agenten überwachen: Die vier Signale, die wirklich etwas aussagen

„Der Prozess läuft" ist keine nützliche Antwort

Ein Codex-Agent, der seit zwei Stunden läuft, kann in drei sehr unterschiedlichen Zuständen sein. Er kann Fortschritte machen, sich durch ein Refactoring arbeiten und alle paar Minuten eine Datei ändern. Er kann in einer Schleife hängen — dieselben Dateien immer wieder lesen, dieselben Fragen immer wieder stellen, Tokens verbrennen ohne voranzukommen. Oder er kann auf ein Rate-Limit warten, technisch lebendig, aber ohne Output.

Jedes normale Monitoring-Tool — htop, systemctl status, Uptime-Pings — wird für alle drei Fälle dasselbe sagen: der Prozess ist oben. Diese Antwort ist schlechter als nutzlos, denn sie lässt Sie glauben, dass alles in Ordnung ist, während zwei von drei Ausgängen bedeuten, dass Sie für nichts bezahlen.

Das Monitoring eines Coding-Agents ist ein anderes Problem als das Monitoring eines Webservers. Hier sind die Signale, die wir bei Office Claws beobachten, warum sie wichtig sind, und was jedes einzelne aussagt, das ps aux nicht aussagt.

Signal 1: Aktivität — was der Agent gerade jetzt tut

Das Nützlichste an einem laufenden Agent zu wissen ist, ob er aktuell denkt, tippt oder untätig ist. Nicht „hat er in den letzten fünf Minuten eine Zeile geloggt" — das ist ein nachlaufender Indikator. Gemeint ist der Live-Zustand: fließt der Token-Stream, liest er eine Datei, wartet er auf einen Shell-Befehl.

Bei Office Claws hat jeder Agent einen Schreibtisch im Pixel-Office, und der Charakter an diesem Schreibtisch ist in einem von drei animierten Zuständen: laufend, tippend oder untätig. Diese Animation ist keine Spielerei — sie ist eine Live-Projektion des tatsächlichen Agent-Zustands, angetrieben vom selben RPC-Stream, der auch den Activity-Feed speist. Sie werfen einen Blick auf das Büro und wissen ohne Log-Lesen, welche Agenten gerade aktiv arbeiten und welche parken.

Textbasierte Äquivalente funktionieren ebenfalls. Die Codex CLI emittiert beim Laufen Events — Tool-Aufrufe, File-Reads, Modell-Turns. Diesen Event-Stream zu tailen sagt Ihnen dasselbe wie ein Spinner, nur im Terminal. Wichtig ist, „Prozess lebt" von „Prozess tut etwas" zu unterscheiden.

Signal 2: Output — ändern sich tatsächlich Dateien

Ein Agent, der im Terminal „tippt", aber seit dreißig Minuten keine Datei geändert hat, arbeitet nicht. Er unterhält sich mit sich selbst. Das ist der häufigste Failure-Mode, den wir bei langlaufenden Aufgaben sehen — das Modell gerät in eine Diskussion mit dem eigenen Scratchpad, produziert keine Diffs und verbrennt eine Stunde, bevor es jemand bemerkt.

Der billige Weg, das zu erwischen: ein Watch auf den Working Tree.

# 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

Wenn diese Zahl bei einer Aufgabe, die Diffs produzieren sollte, drei Fenster in Folge null ist, hängt der Agent. Unterbrechen Sie ihn, fassen Sie zusammen, was er bisher gelernt hat, und starten Sie mit einem engeren Prompt neu. Ihn weiterlaufen zu lassen, ist fast immer Verschwendung.

Ein verwandtes Signal: Commit-Kadenz. Wir weisen unsere Builder-Agenten an, nach jeder logischen Änderung zu committen. Ein Agent, der bei einer Aufgabe, die mit „refactor diese 20 Dateien" begonnen hat, seit einer Stunde nicht committet hat, sagt Ihnen etwas — meistens, dass die Aufgabe unterspezifiziert war.

Signal 3: Kosten — Tokens, Messages und die Rate-Limit-Klippe

Subscription-Codex (ChatGPT Plus oder Pro) rechnet nicht pro Token ab, setzt aber eine Obergrenze auf Messages pro Rolling-Window. Codex im API-Modus rechnet pro Token ab, ohne Obergrenze. Beide kümmern sich um Volumen, aus unterschiedlichen Gründen.

Der Subscription-Fall ist der gefährliche für Monitoring, denn ein rate-limitierter Agent sieht aus, als liefe er. Der Prozess ist oben, das Terminal ist offen, die CLI wartet. Aber jede neue Anfrage wird gedrosselt, und nichts kommt zurück. Ohne Rate-Limit-Indikator merken Sie nichts, bis Sie den Output prüfen und sechs Stunden Nichts sehen.

Wir zeigen die verbleibenden Messages direkt im Office-Claws-Activity-Feed — sobald der Zählerstand unter 10% fällt, wird das Badge des Agents bernsteinfarben. Dasselbe lässt sich in jedem Setup verdrahten: die Codex CLI legt die Limit-Header offen, und ein kleines jq-Skript kann eine Benachrichtigung auslösen, wenn der Rest-Counter eine Schwelle kreuzt.

Signal 4: Stuck-State — der stille Fehler

Die am schwersten zu fangende Fehlerklasse ist der Agent, der technisch Output produziert, aber keinen Fortschritt macht. Wir sehen drei Ausprägungen davon regelmäßig:

• Read-Loop. Der Agent liest dieselben fünf Dateien immer wieder, fasst jedes Mal leicht anders zusammen, schreibt nie etwas. Token-Verbrauch ist real, Fortschritt ist null
• Test-Fix-Test-Spirale. Der Agent führt Tests aus, sieht einen Fehler, „behebt" ihn so, dass ein neuer Fehler entsteht, führt die Tests erneut aus, ewig. Jeder Zyklus produziert einen Diff, also fängt naives Output-Monitoring das nicht
• Rate-Limit-Retry-Storm. Der Agent erreicht das Cap, versucht es alle paar Sekunden erneut, loggt unbegrenzt „retrying...". CPU niedrig, Speicher niedrig, Logs scrollen, nichts passiert

Das Tell für alle drei ist Wiederholung. Das Log eines gesunden Agents ist eine Sequenz unterschiedlicher Aktionen — lies diese Datei, dann jene, dann schreibe jenes, dann führe diesen Befehl aus. Das Log eines festgefahrenen Agents sind dieselben drei Zeilen, eine Stunde lang ineinander verschachtelt. Die einfachste Alarm-Metrik, die das zuverlässig fängt, ist „einzigartige Tool-Aufrufe in den letzten 20 Minuten". Ist die Antwort zwei oder drei, steckt der Agent in einer Schleife.

Wie Office Claws diese Signale sichtbar macht

Jedes der obigen ist in der Desktop-App ab diesem Monat implementiert:

• Activity-Feed — Live-Stream jedes Tool-Calls, File-Reads, Befehls und Modell-Turns von jedem Agenten, gebündelt in einem Panel
• Pixel-Office-Zustände — laufen / tippen / untätig, angetrieben vom RPC-Stream aus dem VPS des Agents
• Log-Stream — vollständiges stdout/stderr pro Agent, inklusive Scrollback, pro Agent filterbar
• Rate-Limit-Badges — farbiger Indikator pro Agent, wenn die verbleibenden Messages unter die Warnschwelle fallen
• Idle-Erkennung — Agenten, die in einem konfigurierbaren Fenster keinen Output produziert haben, werden im Büro markiert; die Charakter-Animation wechselt zu idle, und das Schreibtisch-Badge wird gelb

Der Punkt ist nicht, dass Sie Office Claws nutzen müssen, um das zu bekommen. Der Punkt ist, dass diese vier Signale sind, was ein Coding-Agent-Dashboard zeigen muss, und jedes selbstgebaute Setup, das eines weglässt, den passenden Failure-Mode durchlässt.

Was nicht zu überwachen ist

Drei Dinge, die wichtig wirken und es meistens nicht sind:

1. CPU und Speicher auf dem VPS. Eine Codex-CLI-Session nutzt ~200MB RAM und fast keine CPU — die Arbeit passiert im Modell, nicht auf dem Droplet. Wenn Ihr Agent CPU-gepeggt ist, stimmt etwas mit Ihrem Code nicht, nicht mit dem Agenten
2. Netzwerk-Uptime. Tailscale übernimmt Reconnects automatisch. Ein 30-Sekunden-Drop beeinflusst keine laufende Agent-Session. Darauf zu alarmieren erzeugt nur Lärm
3. „Läuft immer noch nach N Stunden" als Erfolgssignal. Laufzeit allein ist eine Falle — ein festgefahrener Agent läuft glücklich 24 Stunden. Koppeln Sie Laufzeit mit Output, um etwas Aussagekräftiges zu bekommen

Ein minimales Eigenbau-Setup

Wenn Sie Office Claws nicht nutzen und das Äquivalent wollen, hier der kürzeste Pfad:

# /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

In check.sh:

1. Parsen Sie die letzten 20 Minuten des Codex-Event-Logs, zählen Sie einzigartige Tool-Invokationen
2. Zählen Sie Dateien, die unter /repo in den letzten 20 Minuten geändert wurden
3. Lesen Sie den Rate-Limit-Header der jüngsten API-Antwort
4. Wenn unique-tools ≤ 2 und files-changed = 0 für zwei Fenster in Folge, feuern Sie einen Webhook

Das ist das Ganze. Vierzig Zeilen Shell, ein Cron, ein Webhook dorthin, wo Sie Benachrichtigungen lesen. Grob, aber fängt die drei Failure-Modes, die zählen. Das Pixel-Office sieht hübscher aus, löst aber dasselbe Problem.

Die Einzeiler-Version

Das Monitoring eines Coding-Agents geht nicht darum, ob der Prozess lebt — es geht darum, ob die Arbeit sich bewegt. Aktivität sagt etwas tut sich, Output sagt etwas wird produziert, Kosten sagen kann er weiterlaufen, Stuck-State sagt macht er tatsächlich Fortschritte. Beobachten Sie alle vier. Vertrauen Sie keinem einzeln.

Weiterführende Lektüre

• How to Run Multiple Codex Agents at Once — Monitoring wird schwerer im Verhältnis zur Agent-Zahl
• Long-Running Codex Tasks — warum Overnight-Aufgaben alle vier Signale brauchen, nicht nur Uptime
• Cutting AI Agent Costs — das Kosten-Signal im Detail, inklusive wann von Plus auf Pro zu wechseln ist