Diagnose- & Debug-Flags

Die meisten OpenClaw-Debugging-Runden entgleisen aus einem simplen Grund: Leute ändern drei Dinge, bevor sie das erste verstanden haben.

Ein besseres Bild ist das Armaturenbrett im Auto. Wenn eine Warnlampe angeht, reißt du nicht das Radio raus, tauschst die Batterie und trittst noch gegen den Reifen, einfach damit sich etwas nach Aktivität anfühlt. Du prüfst, welches System meckert, wie ernst das ist und welche Belege du einsammeln kannst, bevor du den nächsten Schritt machst.

Die offizielle Diagnose-Flags-Doku und die Doctor-Referenz sind hier die zwei besten Startpunkte. Zusammen erklären sie, wie du gezielte Belege bekommst, statt dein ganzes Gateway in eine Nebelmaschine zu verwandeln.

Starte mit den ersten Debug-Schritten, nicht mit den dramatischen

Wenn OpenClaw seltsam reagiert, ist der klügste erste Schritt oft langweilig. Gut so. Langweilig ist meistens der Weg raus aus dem Raten.

1. Symptom sauber reproduzieren: wissen, was kaputtging, wo es passierte und ob es wieder passiert
2. Doctor im Prüfmodus laufen lassen: strukturierte Health Checks vor irgendwelchen Änderungen
3. Aktuelle Logs lesen: prüfen, ob es um Start, Auth, Kanal-Transport, Plugin-Load oder Laufzeitverhalten geht
4. Nur die nötigen Diagnosen aktivieren: gezielte Flags für das Subsystem setzen, das wahrscheinlich schuldig ist
5. Immer nur eine Sache ändern: sonst wird deine Beweislage zu Suppe

Diese Reihenfolge ist nicht zufällig. Diagnose-Flags sind stark, aber sie sind nicht für jedes Problem Schritt eins. Manchmal sagt dir doctor schon, dass die Config schief ist. Manchmal zeigen die Logs bereits, dass die Verbindung wegbricht. Kein Grund, sofort so zu tun, als würdest du einen Kernreaktor kalibrieren.

Was Diagnose-Flags eigentlich tun

Diagnose-Flags schalten gezielte Sicht auf einen engen Systembereich frei, ohne das gesamte Logging überall hochzufahren. OpenClaw behandelt sie als schmale opt-in Debug-Spuren.

Dadurch kannst du einen fehlerhaften Bereich, etwa Telegram-HTTP-Verhalten, Gateway-Timing oder Profiling-Spans, genauer beobachten, ohne jedes andere Subsystem im Rauschen zu ertränken. Laut offizieller Doku sind Flags nicht case-sensitiv und unterstützen Wildcards. Du kannst also auch gateway.* oder im Ernstfall * einsetzen, wenn du die Sicht bewusst verbreitern willst.

In der Praxis gewinnt fokussiert fast immer. Ein schmaler Logstrom ist leichter zu lesen, leichter mit Support zu teilen und seltener voller irrelevanter sensibler Details.

# gezielte Diagnosen für einen Lauf
OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload openclaw gateway run

# Profiling für genau einen Lauf
OPENCLAW_DIAGNOSTICS=reply.profiler openclaw gateway run

# alle Diagnose-Flags für diesen Prozess deaktivieren
OPENCLAW_DIAGNOSTICS=0 openclaw gateway run

Wisse, wo die Logs liegen, bevor du in Panik gerätst

OpenClaw schreibt Diagnose-Ausgaben standardmäßig in die normale Diagnose-Logdatei, meist unter /tmp/openclaw/openclaw-YYYY-MM-DD.log. Falls dein Setup logging.file gesetzt hat, gilt natürlich dieser Pfad.

Genau deshalb ist openclaw logs so wichtig. Damit kannst du Gateway-Dateilogs sauber einsehen, auch im Remote-Modus, ohne so zu tun, als wäre SSH die einzige anerkannte Religion für Fehlersuche. Dazu kommen Follow-Modus, JSON-Ausgabe und lokale oder UTC-Zeitanzeige.

Die nützliche Gewohnheit ist simpel: Problem reproduzieren, relevante Logs verfolgen und erst dann gezielte Flags ergänzen, wenn die vorhandenen Zeilen nicht präzise genug sind. Viele drehen das um. So wird aus einem kleinen Rätsel schnell ein 500-Zeilen-Verhör.

Doctor ist für Health und geführte Findings da, nicht nur für Notfälle

Viele Betreiber behandeln openclaw doctor wie einen Krankenwagen für den allerschlimmsten Fall. Die Doku legt eine bessere Haltung nahe. Doctor ist die zentrale Health-Oberfläche für Gateway, Channels, Plugins, Skills, Model Routing, lokalen State und Config-Migrationen.

Hilfreich ist dieses Dreierbild:

• inspect: menschenlesbare Checks und geführte Hinweise
• repair: unterstützte Reparaturen, wenn doctor bewusst Änderungen machen soll
• lint: Read-only Findings für CI, Preflight oder diszipliniertes Debugging

Für seltsames Verhalten ist openclaw doctor --lint oft der beste erste Zug, weil es read-only bleibt und dich zurück zur Beweislage zwingt.

# read-only Health Checks
openclaw doctor --lint

# Logs beim Reproduzieren verfolgen
openclaw logs --follow

# doctor auf einen Check eingrenzen
openclaw doctor --lint --only core/doctor/gateway-config --json

Typische Laufzeit-Bruchstellen, die du zuerst trennen solltest

Nicht jeder OpenClaw-Fehler sitzt in derselben Schicht. Genau deshalb fühlt sich wildes Wiederholen meist so unerquicklich an.

Diese Bruchstellen solltest du früh voneinander unterscheiden:

• Gateway-Start: Config-Probleme, Service-State, Token-Fehler oder Plugin-Load-Ausfälle
• Kanal-Schicht: Auth, Berechtigungen, Transport oder Formatierungsprobleme auf Telegram, Discord und ähnlichen Flächen
• Tool- und Runtime-Schicht: exec-Policy, Sandbox-Grenzen, Node-Pairing, Browser-State oder Provider-Auth
• Inhalts- oder Codepfad-Bugs: ein bestimmter Befehlspfad oder Dev-Script crasht, obwohl das Gateway insgesamt gesund wirkt

Die OpenClaw-Doku enthält sogar enge Debug-Notizen für Fälle wie den Node-plus-tsx-Crash. Das ist eine gute Erinnerung daran, dass manche Bugs keine "das ganze System ist kaputt"-Bugs sind. Es sind "dieser eine Laufzeitpfad hat eine bekannte scharfe Kante"-Bugs. Anderes Problem, andere Lösung.

Wann du den Blick weiten solltest und wann Schluss mit Raten ist

Manchmal reicht der erste Durchgang. Manchmal musst du den Blick bewusst verbreitern. Der Trick ist, das absichtlich zu tun.

• Diagnostik verbreitern, wenn ein enges Flag Symptome zeigt, aber die Ursache nicht
• Profiler-Flags nutzen, wenn Timing oder Start-Reihenfolge das eigentliche Rätsel sind
• Zu doctor-Findings wechseln, wenn Config oder State-Integrität beteiligt sein könnten
• Auf einen Minimal-Repro eskalieren, wenn es eher nach Codepfad-Bug als nach Bedienfehler aussieht

Eine gute Debug-Regel lautet: Wenn die nächste Änderung eher aus Genervtheit als aus Belegen entsteht, stopp. Genau dann brauchst du eine bessere Logzeile, einen saubereren Repro oder eine engere Hypothese.

Ein praktischer Workflow, der halbwegs vernünftig bleibt

Wenn du eine wiederholbare Betreiber-Gewohnheit willst, nutze diese Reihenfolge:

1. das exakte Symptom und die Uhrzeit notieren
2. openclaw doctor --lint ausführen
3. aktuelle Zeilen mit openclaw logs prüfen
4. das kleinste sinnvolle Diagnose-Flag-Set aktivieren
5. genau einmal reproduzieren
6. entscheiden, ob es Config, Transport, Runtime oder ein codepfad-spezifischer Fehler ist

Was auf dieser Liste fehlt, ist kein Versehen: Panik-Edits, Zufalls-Neuinstallationen und sechs spekulative Config-Änderungen. Tapfer vielleicht. Hilfreich selten.

Die Kurzfassung

Diagnose-Flags sind für gezielte Belege gedacht, nicht für großes Theater. Logs zeigen dir, was passiert ist. Doctor zeigt dir, was die bestehenden Health Checks schon wissen. Zusammen helfen sie dir, eine schlechte Config, eine wacklige Integration und einen echten Runtime-Bug auseinanderzuhalten, ohne das ganze System abzufackeln.

Der schnellste Weg, OpenClaw zu debuggen, ist meistens nicht mehr Raten. Es ist weniger Raten, nur in besserer Reihenfolge.