OpenClaw Logs analysieren: Fehler finden & konfigurieren

Kennst du das? Irgendetwas in deinem Stack verhält sich seltsam, aber du siehst einfach nicht, was im Hintergrund passiert. Ohne ordentliches Logging stocherst du im Dunkeln, was besonders bei komplexen Message-Flows oder API-Integrationen extrem nervig ist.

Gutes Logging ist der Unterschied zwischen einer schnellen Lösung und stundenlanger Fehlersuche. OpenClaw schreibt Logs an zwei Stellen: In Log-Dateien (JSONL) durch das Gateway und als Console-Output in deinem Terminal oder im Control UI. Hier erfährst du, wie du alles konfigurierst und auswertest.

Wo die Logs liegen

Standardmäßig schreibt das Gateway eine rollierende Log-Datei unter diesem Pfad:

/tmp/openclaw/openclaw-YYYY-MM-DD.log

Das Datum verwendet die lokale Zeitzone des Gateway-Hosts.

Du kannst diesen Pfad in der ~/.openclaw/openclaw.json überschreiben:

{
  "logging": {
    "file": "/path/to/openclaw.log"
  }
}

Wie du Logs liest

CLI: Live-Tail (empfohlen)

Nutze die CLI, um die Gateway-Logdatei via RPC in Echtzeit zu verfolgen:

openclaw logs --follow

Es gibt verschiedene Output-Modi:

TTY-Sessions: Schöne, farbige und strukturierte Log-Zeilen.
Non-TTY-Sessions: Reintext.
--json: Zeilenweise unterteiltes JSON (ein Log-Event pro Zeile).
--plain: Erzwingt Reintext in TTY-Sessions.
--no-color: Deaktiviert ANSI-Farben.

Im JSON-Modus gibt die CLI Objekte mit einem type-Tag aus:

meta: Stream-Metadaten (Datei, Cursor, Größe).
log: Parsed Log-Eintrag.
notice: Hinweise zu Kürzungen oder Log-Rotation.
raw: Unverarbeitete Log-Zeile.

Falls das Gateway nicht erreichbar ist, gibt die CLI einen kurzen Hinweis aus, diesen Befehl zu nutzen:

openclaw doctor

Control UI (Web)

Der Tab Logs im Control UI verfolgt dieselbe Datei mittels logs.tail. Schau unter /web/control-ui nach, wie du es öffnest.

Channel-only Logs

Um nur die Aktivitäten bestimmter Channels (WhatsApp, Telegram etc.) zu filtern, nutzt du:

openclaw channels logs --channel whatsapp

Log-Formate

Datei-Logs (JSONL)

Jede Zeile in der Log-Datei ist ein JSON-Objekt. Die CLI und das Control UI parsen diese Einträge, um eine strukturierte Ausgabe (Zeit, Level, Subsystem, Nachricht) zu rendern.

Console-Output

Console-Logs erkennen TTY-Umgebungen und sind für bessere Lesbarkeit formatiert:

Subsystem-Präfixe (z. B. gateway/channels/whatsapp).
Level-Farben (Info, Warn, Error).
Optionaler Compact- oder JSON-Modus.
Zeitstempel für die Nachverfolgung.

Die Formatierung der Konsole wird über logging.consoleStyle gesteuert.

Logging konfigurieren

Die gesamte Konfiguration für das Logging findest du unter logging in der ~/.openclaw/openclaw.json.

{
  "logging": {
    "level": "info",
    "file": "/tmp/openclaw/openclaw-YYYY-MM-DD.log",
    "consoleLevel": "info",
    "consoleStyle": "pretty",
    "redactSensitive": "tools",
    "redactPatterns": ["sk-.*"]
  }
}

Log-Levels

logging.level: Level für die Datei-Logs (JSONL).
logging.consoleLevel: Detailgrad für die Konsole.

Du kannst beide über die Umgebungsvariable OPENCLAW_LOG_LEVEL überschreiben (z. B. OPENCLAW_LOG_LEVEL=debug). Die Umgebungsvariable hat Vorrang vor der Konfigurationsdatei. So kannst du die Detailtiefe für einen einzelnen Durchlauf erhöhen, ohne die openclaw.json zu bearbeiten. Alternativ kannst du die globale CLI-Option --log-level <level> nutzen (zum Beispiel openclaw --log-level debug gateway run), was wiederum die Umgebungsvariable für diesen Befehl überschreibt.

Der Flag --verbose beeinflusst nur den Console-Output, nicht aber die Log-Levels der Dateien.

Console-Styles

logging.consoleStyle bietet folgende Optionen:

pretty: Benutzerfreundlich, farbig und mit Zeitstempeln.
compact: Kompakterer Output (ideal für lange Sessions).
json: JSON pro Zeile (für Log-Prozessoren).
plain: Einfacher Text ohne Formatierung.

Redaction

Tool-Zusammenfassungen können sensible Tokens unkenntlich machen, bevor sie in der Konsole erscheinen:

logging.redactSensitive: off | tools (Standard: tools).
logging.redactPatterns: Eine Liste von Regex-Strings, um das Standard-Set zu überschreiben.

Die Zensierung betrifft nur den Console-Output und ändert nichts an den Datei-Logs.

Diagnostics + OpenTelemetry

Diagnostics sind strukturierte, maschinenlesbare Events für Model-Runs sowie Telemetrie für den Message-Flow (Webhooks, Queueing, Session-Status). Sie ersetzen die Logs nicht, sondern dienen dazu, Metriken, Traces und andere Exporter zu füttern.

Diagnostics-Events werden prozessintern ausgegeben. Exporter hängen sich jedoch nur an, wenn sowohl Diagnostics als auch das entsprechende Exporter-Plugin aktiviert sind.

OpenTelemetry vs OTLP

OpenTelemetry (OTel): Das Datenmodell und die SDKs für Traces, Metriken und Logs.
OTLP: Das Protokoll, um OTel-Daten an einen Collector oder ein Backend zu senden.
OpenClaw exportiert aktuell via OTLP/HTTP (protobuf).
Die Kompatibilität mit gängigen Collectoren ist dadurch sichergestellt.

Exportierte Signale

Metrics: Counter und Histogramme (Token-Verbrauch, Message-Flow, Queueing).
Traces: Spans für Model-Nutzung sowie Webhook- und Message-Verarbeitung.
Logs: Export via OTLP, wenn diagnostics.otel.logs aktiv ist.
Events: Strukturierte Diagnose-Ereignisse für Systemanalysen.

Diagnostic-Event-Katalog

Model-Nutzung:

model.usage: Tokens, Kosten, Dauer, Kontext, Provider/Model/Channel, Session-IDs.

Message-Flow:

webhook.received: Webhook-Eingang pro Channel.
webhook.processed: Webhook verarbeitet inklusive Dauer.
webhook.error: Fehler im Webhook-Handler.
message.queued: Nachricht für die Verarbeitung eingereiht.
message.processed: Ergebnis, Dauer und optionaler Fehler.

Queue + Session:

queue.lane.enqueue: Command-Queue-Lane Enqueue und Tiefe.
queue.lane.dequeue: Command-Queue-Lane Dequeue und Wartezeit.
session.state: Session-Statusübergang und Grund.
session.stuck: Warnung bei hängender Session inklusive Alter.
run.attempt: Metadaten zu Run-Retries/Versuchen.
diagnostic.heartbeat: Aggregierte Counter (Webhooks/Queue/Session).

Diagnostics aktivieren (ohne Exporter)

Nutze dies, wenn du Diagnostics-Events für Plugins oder eigene Sinks verfügbar machen willst:

{
  "diagnostics": {
    "enabled": true
  }
}

Diagnostics-Flags (gezielte Logs)

Nutze Flags, um zusätzliche, gezielte Debug-Logs einzuschalten, ohne das allgemeine logging.level anzuheben. Flags ignorieren Groß-/Kleinschreibung und unterstützen Wildcards (z. B. telegram.* oder *).

{
  "diagnostics": {
    "flags": ["telegram.http"]
  }
}

Umgebungsvariable für den Einmalgebrauch:

OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload

Hinweise:

Flag-Logs landen in der Standard-Logdatei (identisch mit logging.file).
Der Output wird weiterhin gemäß logging.redactSensitive zensiert.
Den vollständigen Guide findest du unter: /diagnostics/flags.

Export nach OpenTelemetry

Diagnostics können über das diagnostics-otel Plugin (OTLP/HTTP) exportiert werden. Das funktioniert mit jedem OpenTelemetry-Collector oder Backend, das OTLP/HTTP akzeptiert.

{
  "plugins": {
    "allow": ["diagnostics-otel"],
    "entries": {
      "diagnostics-otel": {
        "enabled": true
      }
    }
  },
  "diagnostics": {
    "enabled": true,
    "otel": {
      "enabled": true,
      "endpoint": "http://otel-collector:4318",
      "protocol": "http/protobuf",
      "serviceName": "openclaw-gateway",
      "traces": true,
      "metrics": true,
      "logs": true,
      "sampleRate": 0.2,
      "flushIntervalMs": 60000
    }
  }
}