Logging

OpenClaw protokolliert an zwei Stellen:

  • Datei-Logs (JSON-Zeilen), geschrieben vom Gateway.
  • Konsolenausgabe in Terminals und im Control UI.

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

Wo Logs liegen

Standardmäßig schreibt das Gateway eine rotierende Logdatei unter:

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

Das Datum verwendet die lokale Zeitzone des Gateway-Hosts.

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

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

Logs lesen

CLI: Live-Tailing (empfohlen)

Verwende die CLI, um die Gateway-Logdatei per RPC zu tailen:

openclaw logs --follow

Ausgabemodi:

  • TTY-Sessions: hübsch, farbig, strukturierte Log-Zeilen.
  • Nicht-TTY-Sessions: Klartext.
  • --json: zeilenweises JSON (ein Log-Event pro Zeile).
  • --plain: Klartext in TTY-Sessions erzwingen.
  • --no-color: ANSI-Farben deaktivieren.

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

  • meta: Stream-Metadaten (Datei, Cursor, Größe)
  • log: geparster Log-Eintrag
  • notice: Trunkierungs-/Rotationshinweise
  • raw: ungeparste Log-Zeile

Wenn das Gateway nicht erreichbar ist, gibt die CLI einen kurzen Hinweis aus:

openclaw doctor

Control UI (Web)

Der Logs-Tab im Control UI tailt dieselbe Datei über logs.tail. Siehe /web/control-ui für die Anleitung zum Öffnen.

Channel-spezifische Logs

Um Channel-Aktivitäten (WhatsApp/Telegram/etc.) zu filtern:

openclaw channels logs --channel whatsapp

Log-Formate

Datei-Logs (JSONL)

Jede Zeile in der Logdatei ist ein JSON-Objekt. CLI und Control UI parsen diese Einträge, um strukturierte Ausgabe darzustellen (Zeit, Level, Subsystem, Nachricht).

Konsolenausgabe

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

  • Subsystem-Prefixe (z. B. gateway/channels/whatsapp)
  • Level-Farbgebung (info/warn/error)
  • Optionaler kompakter oder JSON-Modus

Die Konsolenformatierung wird über 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: Datei-Log-Level (JSONL).
  • logging.consoleLevel: Konsolen-Verbositätslevel.

Beide lassen sich über die Umgebungsvariable OPENCLAW_LOG_LEVEL überschreiben (z. B. OPENCLAW_LOG_LEVEL=debug). Die Umgebungsvariable hat Vorrang vor der Konfigurationsdatei, sodass du die Verbosität für einen einzelnen Lauf erhöhen kannst, ohne openclaw.json zu bearbeiten. Du kannst auch die globale CLI-Option --log-level <level> verwenden (z. B. openclaw --log-level debug gateway run), die wiederum die Umgebungsvariable für diesen Befehl überschreibt.

--verbose beeinflusst nur die Konsolenausgabe; es ändert nicht die Datei-Log-Level.

Konsolen-Stile

logging.consoleStyle:

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

Schwärzung

Tool-Zusammenfassungen können sensible Tokens schwärzen, bevor sie in der Konsole angezeigt werden:

  • logging.redactSensitive: off | tools (Standard: tools)
  • logging.redactPatterns: Liste von Regex-Strings, die den Standardsatz überschreiben

Die Schwärzung betrifft nur die Konsolenausgabe und verändert keine Datei-Logs.

Diagnostics + OpenTelemetry

Diagnostics sind strukturierte, maschinenlesbare Events für Modellläufe und Nachrichtenfluss-Telemetrie (Webhooks, Queuing, Session-Status). Sie ersetzen nicht die Logs; sie dienen dazu, Metriken, Traces und andere Exporter zu speisen.

Diagnostics-Events werden im Prozess emittiert, aber Exporter werden nur angehängt, wenn Diagnostics und das Exporter-Plugin aktiviert sind.

OpenTelemetry vs. OTLP

  • OpenTelemetry (OTel): das Datenmodell + SDKs für Traces, Metriken und Logs.
  • OTLP: das Übertragungsprotokoll zum Export von OTel-Daten an einen Collector/Backend.
  • OpenClaw exportiert derzeit via OTLP/HTTP (protobuf).

Exportierte Signale

  • Metriken: Counter + Histogramme (Token-Nutzung, Nachrichtenfluss, Queuing).
  • Traces: Spans für Modellnutzung + Webhook-/Nachrichtenverarbeitung.
  • Logs: über OTLP exportiert, wenn diagnostics.otel.logs aktiviert ist. Das Log-Volumen kann hoch sein; beachte logging.level und Exporter-Filter.

Diagnostics-Event-Katalog

Modellnutzung:

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

Nachrichtenfluss:

  • 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-Einreihung + Tiefe.
  • queue.lane.dequeue: Command-Queue-Lane-Entnahme + Wartezeit.
  • session.state: Session-Statusübergang + Grund.
  • session.stuck: Session-Stuck-Warnung + Alter.
  • run.attempt: Run-Retry/Attempt-Metadaten.
  • diagnostic.heartbeat: aggregierte Zähler (Webhooks/Queue/Session).

Diagnostics aktivieren (ohne Exporter)

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

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

Diagnostics-Flags (gezielte Logs)

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

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

Umgebungsvariablen-Override (einmalig):

OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload

Hinweise:

  • Flag-Logs gehen in die Standard-Logdatei (wie logging.file).
  • Die Ausgabe wird gemäß logging.redactSensitive geschwärzt.
  • Vollständige Anleitung: /diagnostics/flags.

Export nach OpenTelemetry

Diagnostics können über das diagnostics-otel-Plugin (OTLP/HTTP) exportiert werden. Das funktioniert mit jedem OpenTelemetry-Collector/Backend, der 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 derzeit nur http/protobuf. grpc wird ignoriert.
  • Metriken umfassen Token-Nutzung, Kosten, Kontextgröße, Run-Dauer und Nachrichtenfluss-Counter/Histogramme (Webhooks, Queuing, Session-Status, Queue-Tiefe/-Wartezeit).
  • Traces/Metriken können mit traces / metrics umgeschaltet werden (Standard: an). Traces umfassen Modellnutzungs-Spans plus Webhook-/Nachrichtenverarbeitungs-Spans, wenn aktiviert.
  • Setze headers, wenn dein Collector Authentifizierung verlangt.
  • Unterstützte Umgebungsvariablen: OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_SERVICE_NAME, OTEL_EXPORTER_OTLP_PROTOCOL.

Exportierte Metriken (Namen + Typen)

Modellnutzung:

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

Nachrichtenfluss:

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

Queues + Sessions:

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

Exportierte Spans (Namen + Schlüsselattribute)

  • 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-Endpunkte können über diagnostics.otel.endpoint oder OTEL_EXPORTER_OTLP_ENDPOINT gesetzt werden.
  • Wenn der Endpunkt bereits /v1/traces oder /v1/metrics enthält, wird er unverändert verwendet.
  • Wenn der Endpunkt bereits /v1/logs enthält, wird er unverändert für Logs verwendet.
  • diagnostics.otel.logs aktiviert den OTLP-Log-Export für die Hauptlogger-Ausgabe.

Log-Export-Verhalten

  • OTLP-Logs verwenden dieselben strukturierten Datensätze, die in logging.file geschrieben werden.
  • Sie respektieren logging.level (Datei-Log-Level). Die Konsolen-Schwärzung gilt nicht für OTLP-Logs.
  • Installationen mit hohem Volumen sollten Sampling/Filtering im OTLP-Collector bevorzugen.

Tipps zur Fehlerbehebung

  • 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 versuche es erneut.
Weiter
Overview
arrow_forward