Zum Inhalt springen

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.

  • Eine laufende OpenClaw-Instanz.
  • Zugriff auf die Konfigurationsdatei unter ~/.openclaw/openclaw.json.
  • Grundkenntnisse im Umgang mit der CLI.

In fünf Minuten hast du die volle Kontrolle über deine Logs. Hier ist der schnellste Weg:

  1. Logs in Echtzeit verfolgen: Nutze die CLI, um den aktuellen Stream zu sehen:

    Terminal-Fenster
    openclaw logs --follow
  2. Log-Level anpassen: Öffne deine ~/.openclaw/openclaw.json und setze das gewünschte Level für die Datei-Logs:

    {
    "logging": {
    "level": "debug",
    "file": "/tmp/openclaw/openclaw-custom.log"
    }
    }
  3. 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
  4. Sensible Daten schützen: Stelle sicher, dass Tokens in der Console maskiert werden:

    {
    "logging": {
    "redactSensitive": "tools"
    }
    }

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.

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.

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.

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.

  • Problem: Die Log-Datei enthält keine Debug-Informationen, obwohl --verbose aktiv ist.
    • Lösung: Setze logging.level in der openclaw.json explizit auf debug. --verbose steuert nur die Console.
  • 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.consoleStyle auf compact oder json umstellen, um das Format zu ändern.

Du brauchst Hilfe bei der Einrichtung? Frag den AI Setup Assistant.

  • /logging – Detaillierte Übersicht über die Konfigurationsoptionen.
  • Gateway-Dokumentation für fortgeschrittene RPC-Setups.
OpenClaw

OpenClaw Expert

Noch festgefahren?

Wenn diese Seite nicht hilft, frage OpenClaw Expert nach Schritt-fuer-Schritt-Loesungen.