Zum Hauptinhalt springen
OpenClaw hat zwei zentrale Log-Oberflächen:
  • Datei-Logs (JSON-Zeilen), die vom Gateway geschrieben werden.
  • Konsolenausgabe, die in Terminals und in der Gateway Debug UI angezeigt wird.
Der Tab Logs der Control UI verfolgt das Gateway-Datei-Log live. Diese Seite erklärt, wo Logs gespeichert werden, wie Sie sie lesen und wie Sie Log-Level und Formate konfigurieren.

​
Wo Logs gespeichert werden

Standardmäßig schreibt das Gateway eine rotierende Log-Datei unter: /tmp/openclaw/openclaw-YYYY-MM-DD.log Das Datum verwendet die lokale Zeitzone des Gateway-Hosts. Jede Datei rotiert, wenn sie logging.maxFileBytes erreicht (Standard: 100 MB). OpenClaw behält bis zu fünf nummerierte Archive neben der aktiven Datei, zum Beispiel openclaw-YYYY-MM-DD.1.log, und schreibt weiter in ein neues aktives Log, statt Diagnosedaten zu unterdrücken. Sie können dies in ~/.openclaw/openclaw.json überschreiben: 
{
  "logging": {
    "file": "/path/to/openclaw.log"
  }
}

​
Logs lesen

​
CLI: Live-Tail (empfohlen)

Verwenden Sie die CLI, um die Gateway-Log-Datei über RPC live zu verfolgen: 
openclaw logs --follow
Nützliche aktuelle Optionen:
  • --local-time: Zeitstempel in Ihrer lokalen Zeitzone ausgeben
  • --url <url> / --token <token> / --timeout <ms>: Standard-Gateway-RPC-Flags
  • --expect-final: Warte-Flag für agentengestützte finale RPC-Antwort (hier über die gemeinsame Client-Schicht akzeptiert)
Ausgabemodi:
  • TTY-Sitzungen: ansprechende, farbige, strukturierte Log-Zeilen.
  • Nicht-TTY-Sitzungen: Klartext.
  • --json: zeilenbegrenztes JSON (ein Log-Ereignis pro Zeile).
  • --plain: Klartext in TTY-Sitzungen erzwingen.
  • --no-color: ANSI-Farben deaktivieren.
Wenn Sie eine explizite --url übergeben, wendet die CLI keine Konfigurations- oder Umgebungs-Anmeldedaten automatisch an; geben Sie --token selbst an, wenn das Ziel-Gateway Authentifizierung erfordert. Im JSON-Modus gibt die CLI Objekte mit type-Tag aus:
  • meta: Stream-Metadaten (Datei, Cursor, Größe)
  • log: geparster Log-Eintrag
  • notice: Hinweise zu Kürzung / Rotation
  • raw: ungeparste Log-Zeile
Wenn das implizite local loopback-Gateway Pairing anfordert, während der Verbindung schließt oder vor einer Antwort von logs.tail eine Zeitüberschreitung erreicht, fällt openclaw logs automatisch auf das konfigurierte Gateway-Datei-Log zurück. Explizite --url-Ziele verwenden diesen Fallback nicht. openclaw logs --follow ist strenger: Unter Linux verwendet es das aktive User-systemd-Gateway-Journal nach PID, wenn verfügbar, und versucht andernfalls weiter, das Live-Gateway zu erreichen, statt einer potenziell veralteten Nebendatei zu folgen. Wenn das Gateway nicht erreichbar ist, gibt die CLI einen kurzen Hinweis aus: 
openclaw doctor

​
Control UI (Web)

Der Tab Logs der Control UI verfolgt dieselbe Datei mit logs.tail. Siehe Control UI, um zu erfahren, wie Sie sie öffnen.

​
Nur-Kanal-Logs

Um Kanalaktivität zu filtern (WhatsApp/Telegram/usw.), verwenden Sie: 
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 Ausgabe darzustellen (Zeit, Level, Subsystem, Nachricht). Datei-Log-JSONL-Datensätze enthalten außerdem maschinenfilterbare Top-Level-Felder, wenn verfügbar:
  • hostname: Hostname des Gateways.
  • message: abgeflachter Log-Nachrichtentext für Volltextsuche.
  • agent_id: aktive Agenten-ID, wenn der Log-Aufruf Agentenkontext enthält.
  • session_id: aktive Sitzungs-ID/Schlüssel, wenn der Log-Aufruf Sitzungskontext enthält.
  • channel: aktiver Kanal, wenn der Log-Aufruf Kanalkontext enthält.
OpenClaw bewahrt die ursprünglichen strukturierten Log-Argumente neben diesen Feldern auf, sodass bestehende Parser, die nummerierte tslog-Argumentschlüssel lesen, weiter funktionieren. Aktivitäten für Talk, Echtzeit-Sprache und verwaltete Räume geben begrenzte Lifecycle-Log- Datensätze über dieselbe Datei-Log-Pipeline aus. Diese Datensätze enthalten Ereignistyp, Modus, Transport, Provider und Größen-/Timing-Messwerte, wenn verfügbar, lassen aber Transkripttext, Audio-Payloads, Turn-IDs, Call-IDs und Provider-Item-IDs aus.

​
Konsolenausgabe

Konsolen-Logs sind TTY-bewusst und für Lesbarkeit formatiert:
  • Subsystem-Präfixe (z. B. gateway/channels/whatsapp)
  • Level-Färbung (info/warn/error)
  • Optionaler Kompakt- oder JSON-Modus
Die Konsolenformatierung wird durch logging.consoleStyle gesteuert.

​
Gateway-WebSocket-Logs

openclaw gateway verfügt außerdem über WebSocket-Protokoll-Logging für RPC-Verkehr:
  • normaler Modus: nur interessante Ergebnisse (Fehler, Parse-Fehler, langsame Aufrufe)
  • --verbose: sämtlicher Request-/Response-Verkehr
  • --ws-log auto|compact|full: ausführlichen Darstellungsstil auswählen
  • --compact: Alias für --ws-log compact
Beispiele: 
openclaw gateway
openclaw gateway --verbose --ws-log compact
openclaw gateway --verbose --ws-log full

​
Logging konfigurieren

Die gesamte Logging-Konfiguration befindet sich 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: Ausführlichkeitslevel für die Konsole.
Sie können beide über die Umgebungsvariable OPENCLAW_LOG_LEVEL überschreiben (z. B. OPENCLAW_LOG_LEVEL=debug). Die Umgebungsvariable hat Vorrang vor der Konfigurationsdatei, sodass Sie die Ausführlichkeit für einen einzelnen Lauf erhöhen können, ohne openclaw.json zu bearbeiten. Sie können außerdem die globale CLI-Option --log-level <level> übergeben (zum Beispiel openclaw --log-level debug gateway run), die die Umgebungsvariable für diesen Befehl überschreibt. --verbose wirkt sich nur auf Konsolenausgabe und WS-Log-Ausführlichkeit aus; es ändert die Datei-Log-Level nicht.

​
Gezielte Modelltransport-Diagnose

Verwenden Sie beim Debuggen von Provider-Aufrufen gezielte Umgebungs-Flags, statt alle Logs auf debug zu erhöhen: 
OPENCLAW_DEBUG_MODEL_TRANSPORT=1 openclaw gateway
OPENCLAW_DEBUG_MODEL_PAYLOAD=tools OPENCLAW_DEBUG_SSE=events openclaw gateway
Verfügbare Flags:
  • OPENCLAW_DEBUG_MODEL_TRANSPORT=1: Request-Start, Fetch-Response, SDK- Header, erstes Streaming-Ereignis, Stream-Abschluss und Transportfehler auf info-Level ausgeben.
  • OPENCLAW_DEBUG_MODEL_PAYLOAD=summary: eine begrenzte Zusammenfassung des Request-Payloads in Modell-Request-Logs aufnehmen.
  • OPENCLAW_DEBUG_MODEL_PAYLOAD=tools: alle modellseitigen Tool-Namen in die Payload-Zusammenfassung aufnehmen.
  • OPENCLAW_DEBUG_MODEL_PAYLOAD=full-redacted: einen redigierten, begrenzten JSON- Payload-Snapshot aufnehmen. Nur beim Debuggen verwenden; Geheimnisse werden redigiert, aber Prompts und Nachrichtentext können weiterhin vorhanden sein.
  • OPENCLAW_DEBUG_SSE=events: Timing für erstes Ereignis und Stream-Abschluss ausgeben.
  • OPENCLAW_DEBUG_SSE=peek: außerdem die ersten fünf redigierten SSE-Ereignis- Payloads ausgeben, pro Ereignis begrenzt.
  • OPENCLAW_DEBUG_CODE_MODE=1: Modelloberflächen-Diagnose für Code-Modus ausgeben, einschließlich Fällen, in denen native Provider-Tools ausgeblendet werden, weil der Code-Modus die Tool-Oberfläche besitzt.
Diese Flags loggen über das normale OpenClaw-Logging, sodass openclaw logs --follow und der Control-UI-Tab Logs sie anzeigen. Ohne die Flags bleiben dieselben Diagnosen auf debug-Level verfügbar. [model-fetch]-Start- und Response-Metadaten (Provider, API, Modell, Status, Latenz und Request-Felder wie Methode, URL, Timeout, Proxy und Policy) werden unabhängig von OPENCLAW_DEBUG_MODEL_TRANSPORT immer auf info-Level ausgegeben, sodass grundlegende Modelltransport-Hygiene ohne Debug-Flags sichtbar ist.

​
Trace-Korrelation

Datei-Logs sind JSONL. Wenn ein Log-Aufruf einen gültigen Diagnose-Trace-Kontext enthält, schreibt OpenClaw die Trace-Felder als Top-Level-JSON-Schlüssel (traceId, spanId, parentSpanId, traceFlags), sodass externe Log-Prozessoren die Zeile mit OTEL-Spans und Provider-traceparent-Weitergabe korrelieren können. Gateway-HTTP-Requests und Gateway-WebSocket-Frames richten einen internen Request- Trace-Scope ein. Logs und Diagnoseereignisse, die innerhalb dieses asynchronen Scopes ausgegeben werden, übernehmen den Request-Trace, wenn sie keinen expliziten Trace-Kontext übergeben. Agentenlauf- und Modellaufruf-Traces werden zu Kindern des aktiven Request-Traces, sodass lokale Logs, Diagnose-Snapshots, OTEL-Spans und vertrauenswürdige Provider-traceparent-Header über traceId zusammengeführt werden können, ohne rohe Request- oder Modellinhalte zu loggen. Talk-Lifecycle-Log-Datensätze fließen außerdem in den diagnostics-otel-Log-Export, wenn OpenTelemetry-Log-Export aktiviert ist, mit denselben begrenzten Attributen wie Datei- Logs. Konfigurieren Sie diagnostics.otel.logsExporter, um OTLP, stdout JSONL oder beide Senken auszuwählen.

​
Größe und Timing von Modellaufrufen

Modellaufruf-Diagnosen zeichnen begrenzte Request-/Response-Messwerte auf, ohne rohe Prompt- oder Response-Inhalte zu erfassen:
  • requestPayloadBytes: UTF-8-Byte-Größe des finalen Modell-Request-Payloads
  • responseStreamBytes: UTF-8-Byte-Größe gestreamter Modell-Response-Chunk- Payloads. Hochfrequente Text-, Thinking- und Tool-Call-Delta-Ereignisse zählen nur die inkrementellen delta-Bytes statt vollständiger partial-Snapshots.
  • timeToFirstByteMs: verstrichene Zeit bis zum ersten gestreamten Response-Ereignis
  • durationMs: Gesamtdauer des Modellaufrufs
Diese Felder stehen Diagnose-Snapshots, Modellaufruf-Plugin-Hooks und OTEL-Modellaufruf-Spans/-Metriken zur Verfügung, wenn Diagnoseexport aktiviert ist.

​
Konsolenstile

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

​
Redigierung

OpenClaw kann sensible Tokens redigieren, bevor sie in Konsolenausgabe, Datei-Logs, OTLP-Log-Datensätze, persistierten Sitzungstranskripttext oder Control-UI-Tool- Ereignis-Payloads gelangen (Tool-Start-Argumente, partielle/finale Ergebnis-Payloads, abgeleitete Exec-Ausgabe und Patch-Zusammenfassungen):
  • logging.redactSensitive: off | tools (Standard: tools)
  • logging.redactPatterns: Liste von Regex-Strings zum Überschreiben des Standardsatzes. Benutzerdefinierte Muster werden zusätzlich zu den eingebauten Standards für Control-UI-Tool-Payloads angewendet, sodass das Hinzufügen eines Musters die Redigierung von Werten, die bereits von den Standards erfasst werden, nie abschwächt.
Datei-Logs und Sitzungstranskripte bleiben JSONL, aber passende Geheimwerte werden maskiert, bevor die Zeile oder Nachricht auf die Festplatte geschrieben wird. Redigierung ist Best-Effort: Sie gilt für texttragende Nachrichteninhalte und Log-Strings, nicht für jedes Identifier- oder Binär-Payload-Feld. Die eingebauten Standards decken gängige API-Anmeldedaten und Feldnamen für Zahlungsdaten ab, wie Kartennummer, CVC/CVV, gemeinsames Zahlungstoken und Zahlungsanmeldedaten, wenn sie als JSON-Felder, URL-Parameter, CLI-Flags oder Zuweisungen erscheinen. logging.redactSensitive: "off" deaktiviert nur diese allgemeine Log-/Transkript- Policy. OpenClaw redigiert weiterhin Safety-Boundary-Payloads, die UI- Clients, Support-Bundles, Diagnosebeobachtern, Genehmigungs-Prompts oder Agenten- Tools angezeigt werden können. Beispiele sind Control-UI-Tool-Call-Ereignisse, sessions_history-Ausgabe, Diagnose-Support-Exporte, Provider-Fehlerbeobachtungen, Anzeige von Exec-Genehmigungsbefehlen und Gateway-WebSocket-Protokoll-Logs. Benutzerdefinierte logging.redactPatterns können auf diesen Oberflächen weiterhin projektspezifische Muster hinzufügen.

​
Diagnose und OpenTelemetry

Diagnosen sind strukturierte, maschinenlesbare Ereignisse für Modellläufe und Message-Flow-Telemetrie (Webhooks, Warteschlangen, Sitzungszustand). Sie ersetzen Logs nicht — sie speisen Metriken, Traces und Exporter. Ereignisse werden im Prozess ausgegeben, unabhängig davon, ob Sie sie exportieren. Zwei angrenzende Oberflächen:
  • OpenTelemetry-Export — Metriken, Traces und Logs über OTLP/HTTP an einen beliebigen OpenTelemetry-kompatiblen Collector oder ein Backend senden (Grafana, Datadog, Honeycomb, New Relic, Tempo usw.). Vollständige Konfiguration, Signalkatalog, Metrik-/Span-Namen, Umgebungsvariablen und Datenschutzmodell befinden sich auf einer eigenen Seite: OpenTelemetry-Export.
  • Diagnose-Flags — gezielte Debug-Log-Flags, die zusätzliche Logs an logging.file weiterleiten, ohne logging.level zu erhöhen. Flags sind nicht groß-/kleinschreibungssensitiv und unterstützen Wildcards (telegram.*, *). Konfigurieren Sie sie unter diagnostics.flags oder über das Env-Override OPENCLAW_DIAGNOSTICS=.... Vollständige Anleitung: Diagnose-Flags.
Um Diagnoseereignisse für Plugins oder benutzerdefinierte Senken ohne OTLP-Export zu aktivieren: 
{
  diagnostics: { enabled: true },
}
Für den OTLP-Export an einen Collector siehe OpenTelemetry-Export.

​
Tipps zur Fehlerbehebung

  • Gateway nicht erreichbar? Führen Sie zuerst openclaw doctor aus.
  • Logs leer? Prüfen Sie, ob der Gateway läuft und in den Dateipfad in logging.file schreibt.
  • Mehr Details erforderlich? Setzen Sie logging.level auf debug oder trace und versuchen Sie es erneut.

​
Verwandte Themen