Logging

OpenClaw loggt an zwei Stellen:

• Datei-Logs (JSON-Zeilen), die vom Gateway geschrieben werden.
• Konsolen-Ausgabe, die in Terminals und der Control UI angezeigt wird.

Diese Seite erklärt, wo Logs gespeichert werden, wie du sie liest und wie du Log-Level und Formate konfigurierst.

Wo Logs gespeichert werden

Standardmäßig schreibt das Gateway eine rollende Log-Datei unter:

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

Das Datum verwendet die lokale Zeitzone des Gateway-Hosts.

Du kannst das in ~/.openclaw/openclaw.json überschreiben:

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

Logs lesen

CLI: Live-Tail (empfohlen)

Nutze die CLI, um die Gateway-Log-Datei per RPC zu verfolgen:

openclaw logs --follow

Ausgabe-Modi:

• TTY-Sessions: hübsch formatiert, farbig, strukturierte Log-Zeilen.
• Nicht-TTY-Sessions: Plain Text.
• --json: zeilenweise JSON (ein Log-Event pro Zeile).
• --plain: erzwingt Plain Text in TTY-Sessions.
• --no-color: deaktiviert ANSI-Farben.

Im JSON-Modus gibt die CLI type-getaggte Objekte aus:

• meta: Stream-Metadaten (Datei, Cursor, Größe)
• log: geparster Log-Eintrag
• notice: Hinweise zu Kürzung/Rotation
• raw: ungeparste Log-Zeile

Falls das Gateway nicht erreichbar ist, zeigt die CLI einen kurzen Hinweis, dass du Folgendes ausführen sollst:

openclaw doctor

Control UI (Web)

Der Logs-Tab der Control UI verfolgt dieselbe Datei mit logs.tail. Siehe /web/control-ui, wie du sie öffnest.

Nur Channel-Logs

Um Channel-Aktivität zu filtern (WhatsApp/Telegram/etc.), nutze:

openclaw channels logs --channel whatsapp

Log-Formate

Datei-Logs (JSONL)

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

Konsolen-Ausgabe

Konsolen-Logs sind TTY-aware und für Lesbarkeit formatiert:

• Subsystem-Präfixe (z. B. gateway/channels/whatsapp)
• Level-Färbung (info/warn/error)
• Optional kompakter oder JSON-Modus

Die Konsolen-Formatierung wird durch logging.consoleStyle gesteuert.

Logging konfigurieren

Die gesamte Logging-Konfiguration liegt unter logging in ~/.openclaw/openclaw.json.

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

Log-Level

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

--verbose betrifft nur die Konsolen-Ausgabe; es ändert nicht die Datei-Log-Level.

Konsolen-Styles

logging.consoleStyle:

• pretty: benutzerfreundlich, farbig, mit Zeitstempeln.
• compact: kompaktere Ausgabe (am besten für lange Sessions).
• json: JSON pro Zeile (für Log-Prozessoren).

Redaction

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

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

Redaction betrifft nur die Konsolen-Ausgabe und ändert keine Datei-Logs.

Diagnostics + OpenTelemetry

Diagnostics sind strukturierte, maschinenlesbare Events für Modell-Runs und Message-Flow-Telemetrie (Webhooks, Queueing, Session-State). Sie ersetzen nicht Logs; sie existieren, um Metriken, Traces und andere Exporter zu versorgen.

Diagnostics-Events werden in-process emittiert, aber Exporter werden nur angehängt, wenn Diagnostics + das Exporter-Plugin aktiviert sind.

OpenTelemetry vs OTLP

• OpenTelemetry (OTel): das Datenmodell + SDKs für Traces, Metriken und Logs.
• OTLP: das Wire-Protokoll, um OTel-Daten zu einem Collector/Backend zu exportieren.
• OpenClaw exportiert heute per OTLP/HTTP (protobuf).

Exportierte Signale

• Metriken: Counter + Histogramme (Token-Nutzung, Message-Flow, Queueing).
• Traces: Spans für Modell-Nutzung + Webhook/Message-Processing.
• Logs: über OTLP exportiert, wenn diagnostics.otel.logs aktiviert ist. Log-Volumen kann hoch sein; behalte logging.level und Exporter-Filter im Blick.

Diagnostic-Event-Katalog

Modell-Nutzung:

• model.usage: Tokens, Kosten, Dauer, Context, Provider/Modell/Channel, Session-IDs.

Message-Flow:

• webhook.received: Webhook-Eingang pro Channel.
• webhook.processed: Webhook verarbeitet + Dauer.
• webhook.error: Webhook-Handler-Fehler.
• message.queued: Nachricht zur Verarbeitung eingereiht.
• message.processed: Ergebnis + Dauer + optionaler Fehler.

Queue + Session:

• queue.lane.enqueue: Command-Queue-Lane-Enqueue + Tiefe.
• queue.lane.dequeue: Command-Queue-Lane-Dequeue + Wartezeit.
• session.state: Session-State-Übergang + Grund.
• session.stuck: Session-Stuck-Warnung + Alter.
• run.attempt: Run-Retry/Attempt-Metadaten.
• diagnostic.heartbeat: aggregierte Counter (Webhooks/Queue/Session).

Diagnostics aktivieren (ohne Exporter)

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

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

Diagnostics-Flags (gezielte Logs)

Nutze Flags, um zusätzliche, gezielte Debug-Logs einzuschalten, ohne logging.level zu erhöhen. Flags sind case-insensitive und unterstützen Wildcards (z. B. telegram.* oder *).

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

Env-Override (einmalig):

OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload

Hinweise:

• Flag-Logs gehen in die Standard-Log-Datei (dieselbe wie logging.file).
• Die Ausgabe wird weiterhin gemäß logging.redactSensitive redaktiert.
• Vollständige Anleitung: /diagnostics/flags.

Export zu OpenTelemetry

Diagnostics können per diagnostics-otel-Plugin (OTLP/HTTP) exportiert werden. Das funktioniert mit jedem OpenTelemetry-Collector/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
    }
  }
}

Hinweise:

• Du kannst das Plugin auch mit openclaw plugins enable diagnostics-otel aktivieren.
• protocol unterstützt aktuell nur http/protobuf. grpc wird ignoriert.
• Metriken umfassen Token-Nutzung, Kosten, Context-Größe, Run-Dauer und Message-Flow-Counter/Histogramme (Webhooks, Queueing, Session-State, Queue-Tiefe/Wartezeit).
• Traces/Metriken können mit traces / metrics umgeschaltet werden (Standard: an). Traces umfassen Modell-Nutzungs-Spans plus Webhook/Message-Processing-Spans, wenn aktiviert.
• Setze headers, wenn dein Collector Auth benötigt.
• Unterstützte Umgebungsvariablen: OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_SERVICE_NAME, OTEL_EXPORTER_OTLP_PROTOCOL.

Exportierte Metriken (Namen + Typen)

Modell-Nutzung:

• openclaw.tokens (Counter, Attrs: openclaw.token, openclaw.channel, openclaw.provider, openclaw.model)
• openclaw.cost.usd (Counter, Attrs: openclaw.channel, openclaw.provider, openclaw.model)
• openclaw.run.duration_ms (Histogram, Attrs: openclaw.channel, openclaw.provider, openclaw.model)
• openclaw.context.tokens (Histogram, Attrs: openclaw.context, openclaw.channel, openclaw.provider, openclaw.model)

Message-Flow:

• openclaw.webhook.received (Counter, Attrs: openclaw.channel, openclaw.webhook)
• openclaw.webhook.error (Counter, Attrs: openclaw.channel, openclaw.webhook)
• openclaw.webhook.duration_ms (Histogram, Attrs: openclaw.channel, openclaw.webhook)
• openclaw.message.queued (Counter, Attrs: openclaw.channel, openclaw.source)
• openclaw.message.processed (Counter, Attrs: openclaw.channel, openclaw.outcome)
• openclaw.message.duration_ms (Histogram, Attrs: openclaw.channel, openclaw.outcome)

Queues + Sessions:

• openclaw.queue.lane.enqueue (Counter, Attrs: openclaw.lane)
• openclaw.queue.lane.dequeue (Counter, Attrs: openclaw.lane)
• openclaw.queue.depth (Histogram, Attrs: openclaw.lane oder openclaw.channel=heartbeat)
• openclaw.queue.wait_ms (Histogram, Attrs: openclaw.lane)
• openclaw.session.state (Counter, Attrs: openclaw.state, openclaw.reason)
• openclaw.session.stuck (Counter, Attrs: openclaw.state)
• openclaw.session.stuck_age_ms (Histogram, Attrs: openclaw.state)
• openclaw.run.attempt (Counter, Attrs: openclaw.attempt)

Exportierte Spans (Namen + wichtige Attribute)

• openclaw.model.usage
  • openclaw.channel, openclaw.provider, openclaw.model
  • openclaw.sessionKey, openclaw.sessionId
  • openclaw.tokens.* (input/output/cache_read/cache_write/total)
• openclaw.webhook.processed
  • openclaw.channel, openclaw.webhook, openclaw.chatId
• openclaw.webhook.error
  • openclaw.channel, openclaw.webhook, openclaw.chatId, openclaw.error
• openclaw.message.processed
  • openclaw.channel, openclaw.outcome, openclaw.chatId, openclaw.messageId, openclaw.sessionKey, openclaw.sessionId, openclaw.reason
• openclaw.session.stuck
  • openclaw.state, openclaw.ageMs, openclaw.queueDepth, openclaw.sessionKey, openclaw.sessionId

Sampling + Flushing

• Trace-Sampling: diagnostics.otel.sampleRate (0.0–1.0, nur Root-Spans).
• Metrik-Export-Intervall: diagnostics.otel.flushIntervalMs (min. 1000ms).

Protokoll-Hinweise

• OTLP/HTTP-Endpoints können per diagnostics.otel.endpoint oder OTEL_EXPORTER_OTLP_ENDPOINT gesetzt werden.
• Falls der Endpoint bereits /v1/traces oder /v1/metrics enthält, wird er unverändert verwendet.
• Falls der Endpoint bereits /v1/logs enthält, wird er unverändert für Logs verwendet.
• diagnostics.otel.logs aktiviert OTLP-Log-Export für die Haupt-Logger-Ausgabe.

Log-Export-Verhalten

• OTLP-Logs verwenden dieselben strukturierten Records, die in logging.file geschrieben werden.
• Respektiert logging.level (Datei-Log-Level). Konsolen-Redaction gilt nicht für OTLP-Logs.
• High-Volume-Installationen sollten OTLP-Collector-Sampling/Filtering bevorzugen.

Troubleshooting-Tipps

• Gateway nicht erreichbar? Führe zuerst openclaw doctor aus.
• Logs leer? Prüfe, ob das Gateway läuft und in den Dateipfad unter logging.file schreibt.
• Mehr Details nötig? Setze logging.level auf debug oder trace und versuch es erneut.