Logging

Eine benutzerfreundliche Übersicht (CLI + Control UI + Konfiguration) findest du unter /logging.

OpenClaw hat zwei Log-Oberflächen:

  • Konsolenausgabe (was du im Terminal / Debug UI siehst).
  • Datei-Logs (JSON-Zeilen), die vom Gateway-Logger geschrieben werden.

Dateibasierter Logger

  • Die Standard-Logdatei liegt unter /tmp/openclaw/ (eine Datei pro Tag): openclaw-YYYY-MM-DD.log
    • Das Datum verwendet die lokale Zeitzone des Gateway-Hosts.
  • Pfad und Level der Logdatei kannst du in ~/.openclaw/openclaw.json konfigurieren:
    • logging.file
    • logging.level

Das Dateiformat ist ein JSON-Objekt pro Zeile.

Der Logs-Tab in der Control UI zeigt diese Datei live an (via Gateway logs.tail). Das CLI kann das auch:

openclaw logs --follow

Verbose vs. Log-Level

  • Datei-Logs werden ausschließlich durch logging.level gesteuert.
  • --verbose beeinflusst nur die Konsolen-Ausführlichkeit (und den WS-Log-Stil); es erhöht nicht das Datei-Log-Level.
  • Um verbose-Details auch in Datei-Logs zu erfassen, setze logging.level auf debug oder trace.

Konsolen-Erfassung

Das CLI erfasst console.log/info/warn/error/debug/trace und schreibt sie in die Datei-Logs, während sie weiterhin auf stdout/stderr ausgegeben werden.

Du kannst die Konsolen-Ausführlichkeit unabhängig einstellen:

  • logging.consoleLevel (Standard: info)
  • logging.consoleStyle (pretty | compact | json)

Tool-Zusammenfassungen maskieren

Ausführliche Tool-Zusammenfassungen (z.B. 🛠️ Exec: ...) können sensible Tokens maskieren, bevor sie in der Konsole erscheinen. Das gilt nur für Tools und ändert nichts an den Datei-Logs.

  • logging.redactSensitive: off | tools (Standard: tools)
  • logging.redactPatterns: Array von Regex-Strings (überschreibt die Standardwerte)
    • Verwende rohe Regex-Strings (automatisch gi), oder /pattern/flags für eigene Flags.
    • Treffer werden maskiert: die ersten 6 + letzten 4 Zeichen bleiben sichtbar (bei Länge >= 18), sonst ***.
    • Die Standardmuster decken gängige Key-Zuweisungen, CLI-Flags, JSON-Felder, Bearer-Header, PEM-Blöcke und beliebte Token-Präfixe ab.

Gateway WebSocket-Logs

Das Gateway gibt WebSocket-Protokoll-Logs in zwei Modi aus:

  • Normaler Modus (ohne --verbose): nur „interessante” RPC-Ergebnisse werden ausgegeben:
    • Fehler (ok=false)
    • Langsame Aufrufe (Standard-Schwellenwert: >= 50ms)
    • Parse-Fehler
  • Verbose-Modus (--verbose): gibt den gesamten WS-Request/Response-Traffic aus.

WS-Log-Stil

openclaw gateway unterstützt einen Stil-Schalter pro Gateway:

  • --ws-log auto (Standard): normaler Modus ist optimiert; verbose-Modus verwendet kompakte Ausgabe
  • --ws-log compact: kompakte Ausgabe (gepaarte Request/Response) im verbose-Modus
  • --ws-log full: vollständige Frame-Ausgabe im verbose-Modus
  • --compact: Alias für --ws-log compact

Beispiele:

# optimiert (nur Fehler/langsame Aufrufe)
openclaw gateway

# zeigt gesamten WS-Traffic (gepaart)
openclaw gateway --verbose --ws-log compact

# zeigt gesamten WS-Traffic (vollständige Meta-Daten)
openclaw gateway --verbose --ws-log full

Konsolenformatierung (Subsystem-Logging)

Der Konsolen-Formatter ist TTY-aware und gibt konsistente, präfixierte Zeilen aus. Subsystem-Logger halten die Ausgabe gruppiert und übersichtlich.

Verhalten:

  • Subsystem-Präfixe in jeder Zeile (z.B. [gateway], [canvas], [tailscale])
  • Subsystem-Farben (stabil pro Subsystem) plus Level-Färbung
  • Farbe wenn die Ausgabe ein TTY ist oder die Umgebung wie ein Rich-Terminal aussieht (TERM/COLORTERM/TERM_PROGRAM), respektiert NO_COLOR
  • Gekürzte Subsystem-Präfixe: entfernt führendes gateway/ + channels/, behält die letzten 2 Segmente (z.B. whatsapp/outbound)
  • Sub-Logger pro Subsystem (automatisches Präfix + strukturiertes Feld { subsystem })
  • logRaw() für QR/UX-Ausgabe (kein Präfix, keine Formatierung)
  • Konsolen-Stile (z.B. pretty | compact | json)
  • Konsolen-Log-Level getrennt vom Datei-Log-Level (Datei behält volle Details wenn logging.level auf debug/trace gesetzt ist)
  • WhatsApp-Nachrichteninhalte werden auf debug-Level geloggt (nutze --verbose um sie zu sehen)

So bleiben die bestehenden Datei-Logs stabil, während die interaktive Ausgabe übersichtlich bleibt.