Hermes Agent debuggen: Logs, Traces, Lücken

Ihr Agent hat etwas Seltsames gemacht. Wo schauen Sie hin?

Hermes Agent kennt zwei Fehlermodi, die auf unterschiedliche Weise weh tun. Der erste ist laut: eine Exception mit Stack Trace oder ein Startup-Crash. Der zweite ist leise: der Agent erzeugt eine kohärente, aber falsche Antwort, ruft das falsche Tool auf oder verstummt nach einem Tool-Ergebnis. Der laute Fall landet in errors.log. Der leise ist das schwierige Debug und steckt im Audit-Log genau der Session, die entgleist ist.

Dies ist eine praktische Karte, wo die Logs liegen, welche Datei zu welchem Symptom passt und welche kleinen Werkzeuge drumherum aus 800 Zeilen JSONL etwas machen, das Sie tatsächlich lesen können. Sie benennt auch die offenen Lücken, damit Sie wissen, was Hermes Ihnen heute nicht verrät.

Wo die Logs liegen

Alles, was Hermes schreibt, landet in Ihrem Hermes-Home-Verzeichnis, standardmäßig ~/.hermes/logs/ (bzw. <profile>/logs/ bei nicht-Default-Profilen). Vier Dateien sind wichtig:

Datei	Level	Inhalt
`agent.log`	INFO+	Haupt-Agent-, Tool- und Session-Aktivität. Standard-Einstieg.
`errors.log`	WARNING+	Nur Warnungen und Fehler. Schnelles Triage für „etwas ist abgestürzt".
`gateway.log`	INFO+	Nur Gateway-Events, Session-Lebenszyklus pro Nutzer in Telegram/Discord/Slack.
`gui.log`	INFO+	Dashboard, Websocket und TUI-Gateway-Events.

Alle vier werden vom RotatingFileHandler in Python geschrieben. Wenn eine Datei ihre Größengrenze erreicht, rollt sie zu agent.log.1, agent.log.2 usw. bis zum konfigurierten backup_count. Die aktive Datei ist immer die ohne Suffix. Das ist wichtig, wenn Sie einem Bug von gestern hinterherjagen, denn „gestern" ist eventuell schon rotiert. Nehmen Sie die nummerierten Dateien mit, nicht nur die aktuelle.

Der Setup-Pfad für all das ist hermes_logging.setup_logging(). Das Gateway ruft ihn beim Start mit mode="gateway" auf und hängt ausschließlich Datei-Handler an, nie einen Konsolen-Handler. hermes gateway start ist also per Design still. Wenn Ihr Gateway tot wirkt, ist es das nicht. Machen Sie ein tail auf gateway.log.

Welchen Log zuerst öffnen

Das Symptom bestimmt die Datei, nicht umgekehrt. Ein grober Entscheidungsbaum:

Der Agent ist beim Start abgestürzt oder ein Request liefert 500. Öffnen Sie errors.log mit hermes logs errors --since 30m -f. Stack Traces landen hier zuerst.
Der Agent hat geantwortet, aber die Antwort ist falsch. Überspringen Sie errors.log. Die Tool-Calls, die die schlechte Antwort erzeugt haben, stehen im JSONL-Session-Transkript dieser Session (siehe nächster Abschnitt zu trace-tree).
Ein Telegram- oder Discord-Nutzer sagt „es ist verstummt". Öffnen Sie gateway.log und filtern Sie auf dessen Session. hermes logs gateway --session abc123 grenzt ein.
Das Dashboard aktualisiert nicht. gui.log. Websocket-Abbrüche und TUI-Gateway-Sync-Fehler tauchen hier zuerst auf.
Sie wissen gar nicht, was los ist. hermes logs -f auf agent.log mit einem zweiten Panel auf errors.log. Die überwältigende Mehrheit der Antworten auf „was macht mein Agent gerade" ist einen tail -f entfernt.

Die CLI hermes logs ist Ihre Verbündete. Ein paar Flags verdienen ihren Platz in einer Live-Debug-Session:

hermes logs                              # letzte 50 Zeilen von agent.log
hermes logs -f                           # folgt agent.log in Echtzeit
hermes logs gateway -n 100               # letzte 100 Zeilen von gateway.log
hermes logs --level WARNING --since 1h   # letzte Stunde, Warnungen und Fehler
hermes logs --session abc123             # grenzt auf eine Session-ID ein
hermes logs errors --since 30m -f        # folgt Fehlern seit 30 Minuten
hermes logs list                         # Inventar der Dateien und Größen

Eine Session als Baum lesen, nicht als JSONL-Wand

Wenn eine Session endet, wird ihre komplette Trajektorie als zeilenweises JSON in die Transkriptdatei geschrieben. Das ist das nützlichste Artefakt zum Debuggen der Klasse „kohärent, aber falsch", weil jeder Modellaufruf, jeder Tool-Call und jedes Tool-Ergebnis in Reihenfolge mit seinen Argumenten erfasst wird. Roh ist es allerdings unlesbar. 800 Zeilen Audit-Log für eine mittelkomplexe Session sind normal.

Das Community-Tool trace-tree (siehe Mukunda Kattas Artikel auf dev.to) liest dieses JSONL und druckt einen Baum ins Terminal. Eine Session wird zur Wurzel, jeder Tool-Call zum Kind, verweigerte Aufrufe erscheinen als Kinder mit angehängtem Fehler. Sie öffnen es, lesen den Baum, schließen es. Kein Login, kein Upload, kein Vendor-Lock-in. Zeigen Sie darauf:

trace-tree ~/.hermes/logs/sessions/2026-07-21T09-42-11.jsonl

Für tiefere Diagnosen können Sie dasselbe JSONL auch nach jq pipen und nach Tool-Namen, Latenz oder Fehlerstatus filtern. Die Transkripte sind versionsstabil auf eine Weise, wie agent.log es nicht ist, also bauen Sie einmalige Queries gegen das Transkript, nicht gegen ein grep auf den Human-readable Log.

Für die verwandte Untersuchung „der Agent ist still, hängt er?" auf Messaging-Kanälen führt unser Leitfaden für Telegram-Troubleshooting zuerst durch die Symptome auf der Zustellseite (Bot-Token, Webhook, Gruppenrechte), die häufig die echte Ursache sind, bevor Sie überhaupt den Trace-Baum brauchen.

Log-Level anheben, ohne Geheimnisse zu leaken

Der Verbose-Modus ist eine Flag entfernt. hermes chat --verbose (oder -v) setzt verbose_logging=True am AIAgent, das ruft setup_verbose_logging() auf und hängt einen StreamHandler auf DEBUG-Level auf der Konsole zusätzlich zu den Datei-Handlern an. Sie sehen live alles, was der Agent sieht.

Der kritische Punkt ist, dass jeder Log-Record auf jedem Level durch den RedactingFormatter aus agent/redact.py läuft, bevor er geschrieben wird. Der Formatter erkennt bekannte Credential-Formen (sk-, sk-or-, sk-ant-, gängige OAuth-Patterns und Secrets im Stil von Umgebungsvariablen) und ersetzt den Wert inline. In der Praxis heißt das: Sie können den Log-Level in Produktion anheben oder einen redigierten agent.log in einen Bug-Report einfügen, ohne Ihren OpenRouter-Schlüssel zu leaken.

Ein Fallstrick sei genannt. Wenn Sie einen eigenen Logger oder ein eigenes Formatter schreiben und die Pipeline umgehen, greift die Redaction nicht. Der Gateway-Startup-Crash NameError: name 'RedactingFormatter' is not defined, gemeldet als Issue #8090, ist derselbe Fehlertyp in umgekehrter Richtung. Gehen Sie davon aus, dass der Formatter tragend ist, umgehen Sie ihn nicht, und wenn Sie eigenes Logging schreiben, hüllen Sie es über hermes_logging.setup_logging() ein, nicht daran vorbei.

Die offenen Observability-Lücken

Hermes ist ehrlich darüber, was er heute noch nicht kann. Zwei offene Feature Requests beschreiben die aktuelle Obergrenze:

Strukturierte Spans mit Start- und End-Timestamps. Aktuell tragen die meisten Log-Zeilen einen einzelnen Timestamp, und manche Tool-Ausgaben enthalten ein Ad-hoc-duration_seconds. Ein stabiles Schema für start_ts, end_ts, duration_ms und parent_id über die gesamte Trajektorie gibt es nicht. Das ist Issue #6741 und blockiert die sauberen Latenz-pro-Tool-Dashboards, die Sie wollen, wenn eine Session langsam wird.
Live-Attach an eine laufende Gateway-Session. In der aktuellen Release können Sie eine Gateway-Session, während sie läuft, nicht in Echtzeit von außen beobachten. agent.log holt auf, wenn die Session abgeschlossen ist, aber es gibt keinen Hook „beobachte diese Nutzer-Session, während sie stattfindet". Das ist Issue #18127 und die größte Lücke für alle, die Hermes als geteilten Dienst betreiben.

Zwei Workarounds schließen einen Teil der Lücke in der Zwischenzeit. Der erste ist OpenTelemetry-artiges Tracing zu einem Backend wie SigNoz, mit dem Sie Hermes-Aktivität nachgelagert in Spans übersetzen, auch ohne native Span-Emission. Der zweite ist Langfuse (Issue #1501), das manche Teams pro Turn als manuelle Instrumentierungsschicht verdrahten. Keiner ist offiziell first-class, aber beide laufen heute irgendwo in Produktion.

Wenn Sie die Log-Schicht lieber gar nicht selbst besitzen

All das oben nimmt an, dass Sie den Agenten selbst betreiben. Wenn genau das der Teil ist, den Sie lieber delegieren, betreibt Hermify einen verwalteten Hermes Agent für Sie auf Telegram, mit demselben Logging und Audit-Trail, die im darunterliegenden Container verfügbar sind. Sie bekommen den persistenten Speicher, die Session-Transkripte und die Möglichkeit, ein konkretes Problem zu uns zu eskalieren, ohne hermes logs -f auf Ihrem eigenen VPS offen halten zu müssen. Falls Sie zwischen Self-Hosting und einem verwalteten Setup schwanken und dabei auch die operative Last der Observability eine Rolle spielt, deckt unsere Analyse zu verwaltetes Hermes gegenüber Self-Hosting die Abwägungen komplett ab.

Legen Sie mit Hermify los und überspringen Sie Log-Rotation und Observability-Arbeit komplett. Oder behalten Sie die Logs lokal und nutzen Sie diesen Leitfaden beim nächsten Mal, wenn Ihr Agent verstummt. Beide Wege sind gültig, und derselbe Audit-Trail steht auf beiden zur Verfügung.