Logging in OpenClaw meistern
Kennst du das? Du suchst nach einem Fehler, aber deine Logs sind entweder ein unleserlicher Textwust oder genau die entscheidende Information fehlt. Nichts bremst deinen Workflow mehr aus als ein intransparentes System, bei dem du raten musst, was im Hintergrund passiert. Wenn du nicht genau siehst, welche Daten durch deine API fließen, wird Debugging zur Glückssache.
Ein gutes Logging-Setup sollte dir die Arbeit abnehmen, nicht neue verursachen. Es geht darum, im richtigen Moment die richtige Detailtiefe zu haben – egal ob du gerade live in der Console zuschaust oder später eine JSON-Logdatei analysieren musst.
Voraussetzungen
Abschnitt betitelt „Voraussetzungen“- Eine laufende OpenClaw-Instanz.
- Zugriff auf die Konfigurationsdatei unter
~/.openclaw/openclaw.json. - Grundkenntnisse im Umgang mit der CLI.
Schnellstart
Abschnitt betitelt „Schnellstart“In fünf Minuten hast du die volle Kontrolle über deine Logs. Hier ist der schnellste Weg:
-
Logs in Echtzeit verfolgen: Nutze die CLI, um den aktuellen Stream zu sehen:
Terminal-Fenster openclaw logs --follow -
Log-Level anpassen: Öffne deine
~/.openclaw/openclaw.jsonund setze das gewünschte Level für die Datei-Logs:{"logging": {"level": "debug","file": "/tmp/openclaw/openclaw-custom.log"}} -
Gateway-Traffic analysieren: Starte das Gateway im Verbose-Modus mit kompaktem Stil, um alle WebSocket-Events zu sehen:
Terminal-Fenster openclaw gateway --verbose --ws-log compact -
Sensible Daten schützen: Stelle sicher, dass Tokens in der Console maskiert werden:
{"logging": {"redactSensitive": "tools"}}
File-based Logger
Abschnitt betitelt „File-based Logger“OpenClaw schreibt standardmäßig rotierende Log-Dateien in das Verzeichnis /tmp/openclaw/. Pro Tag wird eine Datei nach dem Schema openclaw-YYYY-MM-DD.log erstellt. Dabei wird die lokale Zeitzone des Gateway-Hosts verwendet.
Das Format ist JSON Lines (ein JSON-Objekt pro Zeile), was die automatisierte Auswertung extrem einfach macht. Wenn du die Logs lieber über die Control UI siehst, nutzt diese im Hintergrund logs.tail über das Gateway, um genau diese Dateien auszulesen.
Wichtig: Der Parameter --verbose beeinflusst nur die Ausgabe in der Console. Wenn du mehr Details in deinen Log-Dateien brauchst, musst du zwingend logging.level auf debug oder trace setzen.
Console & WebSocket-Debugging
Abschnitt betitelt „Console & WebSocket-Debugging“Die CLI fängt alle console.log Aufrufe ab und leitet sie in die Datei-Logs weiter, während sie trotzdem sauber auf stdout/stderr ausgegeben werden. Die Console ist TTY-aware, was bedeutet, dass du Farben und strukturierte Präfixe (wie [gateway] oder [whatsapp/outbound]) bekommst, sofern dein Terminal das unterstützt.
WebSocket-Modi im Gateway
Abschnitt betitelt „WebSocket-Modi im Gateway“Beim openclaw gateway kannst du zwischen verschiedenen Detailstufen für den WebSocket-Traffic wählen:
- Normaler Modus (ohne
--verbose): Nur Fehler, langsame Calls (>= 50ms) und Parse-Fehler werden angezeigt. Das ist die beste Wahl für den produktiven Betrieb. - Verbose Modus (
--verbose): Zeigt den kompletten Request/Response-Traffic.
Für die Darstellung empfehle ich den --ws-log compact Stil. Er fasst Requests und Responses zusammen, was die Lesbarkeit gegenüber dem full Modus (der jeden Frame einzeln loggt) deutlich erhöht.
Sensible Daten ausblenden
Abschnitt betitelt „Sensible Daten ausblenden“Damit keine API-Keys oder Tokens versehentlich in deinen Console-Logs oder Screencasts landen, bietet OpenClaw eine automatische Redaction. Mit logging.redactSensitive: "tools" werden bekannte Muster (Bearer-Header, PEM-Blöcke, gängige Key-Formate) maskiert.
Falls du eigene Muster hast, kannst du diese über logging.redactPatterns als Array von Regex-Strings hinzufügen. Diese Maskierung betrifft nur den Console-Stream, damit deine File-Logs für das Debugging vollständig bleiben.
Fehlerbehebung
Abschnitt betitelt „Fehlerbehebung“- Problem: Die Log-Datei enthält keine Debug-Informationen, obwohl
--verboseaktiv ist.- Lösung: Setze
logging.levelin deropenclaw.jsonexplizit aufdebug.--verbosesteuert nur die Console.
- Lösung: Setze
- Problem: Die Console-Ausgabe ist zu unruhig durch zu viele Subsystem-Präfixe.
- Lösung: OpenClaw verkürzt Präfixe automatisch. Du kannst zudem
logging.consoleStyleaufcompactoderjsonumstellen, um das Format zu ändern.
- Lösung: OpenClaw verkürzt Präfixe automatisch. Du kannst zudem
Du brauchst Hilfe bei der Einrichtung? Frag den AI Setup Assistant.
Nächste Schritte
Abschnitt betitelt „Nächste Schritte“- /logging – Detaillierte Übersicht über die Konfigurationsoptionen.
- Gateway-Dokumentation für fortgeschrittene RPC-Setups.
OpenClaw Expert
Noch festgefahren?
Wenn diese Seite nicht hilft, frage OpenClaw Expert nach Schritt-fuer-Schritt-Loesungen.