Protokollierung

• Datei-Logs (JSON-Zeilen), die vom Gateway geschrieben werden.
• Konsolenausgabe im Terminal, in dem das Gateway ausgeführt wird.

​

Speicherort der Logs

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

​

Logs lesen

​

CLI: Live-Verfolgung (empfohlen)

openclaw logs --follow
openclaw --dev logs --follow
openclaw --profile work logs --follow

• TTY-Sitzungen: ansprechend formatierte, farbige und strukturierte Log-Zeilen.
• Nicht-TTY-Sitzungen: Klartext.

• meta: Stream-Metadaten (Datei, Quelle, Quelltyp, Dienst, Cursor, Größe)
• log: analysierter Log-Eintrag
• notice: Hinweise auf Kürzung/Rotation
• raw: nicht analysierte Log-Zeile
• error: Gateway-Verbindungsfehler (werden nach stderr geschrieben)

openclaw doctor

​

Control UI (Web)

​

Nur Kanal-Logs

openclaw channels logs --channel whatsapp

​

Log-Formate

​

Datei-Logs (JSONL)

• hostname: Hostname des Gateways.
• message: vereinfachter Log-Nachrichtentext für die Volltextsuche.
• agent_id: aktive Agent-ID, wenn der Log-Aufruf Agent-Kontext enthält.
• session_id: aktive Sitzungs-ID bzw. aktiver Sitzungsschlüssel, wenn der Log-Aufruf Sitzungskontext enthält.
• channel: aktiver Kanal, wenn der Log-Aufruf Kanalkontext enthält.

​

Konsolenausgabe

• Subsystempräfixe (z. B. gateway/channels/whatsapp)
• Level-Farben (Info/Warnung/Fehler)
• Optionaler kompakter oder JSON-Modus

​

Gateway-WebSocket-Logs

• Normalmodus: nur relevante Ergebnisse (Fehler, Analysefehler, langsame Aufrufe)
• --verbose: gesamter Anfrage-/Antwortdatenverkehr
• --ws-log auto|compact|full: ausführlichen Darstellungsstil auswählen
• --compact: Alias für --ws-log compact

openclaw gateway
openclaw gateway --verbose --ws-log compact
openclaw gateway --verbose --ws-log full

​

Logging konfigurieren

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

​

Log-Level

• logging.level: Level der Datei-Logs (JSONL) (Standard: info).
• logging.consoleLevel: Ausführlichkeitslevel der Konsole.

​

Gezielte Modelltransportdiagnose

OPENCLAW_DEBUG_MODEL_TRANSPORT=1 openclaw gateway
OPENCLAW_DEBUG_MODEL_PAYLOAD=tools OPENCLAW_DEBUG_SSE=events openclaw gateway

• OPENCLAW_DEBUG_MODEL_TRANSPORT=1: gibt Anfragestart, Fetch-Antwort, SDK- Header, erstes Streaming-Ereignis, Stream-Abschluss und Transportfehler auf dem Level info aus.
• OPENCLAW_DEBUG_MODEL_PAYLOAD=summary: nimmt eine begrenzte Zusammenfassung der Anfrage-Nutzdaten in Modellanfrage-Logs auf.
• OPENCLAW_DEBUG_MODEL_PAYLOAD=tools: nimmt alle Namen modellseitiger Tools in die Nutzdatenzusammenfassung auf.
• OPENCLAW_DEBUG_MODEL_PAYLOAD=full-redacted: nimmt einen redigierten, größenbegrenzten JSON- Snapshot der Nutzdaten auf. Nur beim Debuggen verwenden; Geheimnisse werden redigiert, aber Prompts und Nachrichtentext können weiterhin enthalten sein.
• OPENCLAW_DEBUG_SSE=events: gibt die Zeitmessung des ersten Ereignisses und des Stream-Abschlusses aus.
• OPENCLAW_DEBUG_SSE=peek: gibt außerdem die ersten fünf redigierten SSE-Ereignis- Nutzdaten aus, jeweils größenbegrenzt.
• OPENCLAW_DEBUG_CODE_MODE=1: gibt Diagnoseinformationen zur Modelloberfläche im Code-Modus aus, einschließlich der Fälle, in denen native Provider-Tools ausgeblendet werden, weil der Code-Modus die Tool-Oberfläche verwaltet.

​

Trace-Korrelation

​

Größe und Zeitmessung von Modellaufrufen

• requestPayloadBytes: UTF-8-Byte-Größe der endgültigen Modellanfrage-Nutzlast
• responseStreamBytes: UTF-8-Byte-Größe des gestreamten Modellantwort-Fragments der Nutzlasten. Hochfrequente Text-, Denk- und Tool-Aufruf-Delta-Ereignisse zählen nur die inkrementellen delta-Bytes anstelle vollständiger partial-Momentaufnahmen.
• timeToFirstByteMs: verstrichene Zeit bis zum ersten gestreamten Antwortereignis
• durationMs: Gesamtdauer des Modellaufrufs

​

Konsolenstile

• pretty: benutzerfreundlich, farbig und mit Zeitstempeln.
• compact: kompaktere Ausgabe (am besten für lange Sitzungen).
• json: eine JSON-Struktur pro Zeile (für Log-Verarbeitungsprogramme).

​

Schwärzung

• Die Schwärzung sensibler Werte ist immer aktiviert.
• logging.redactPatterns: Liste von Regex-Zeichenfolgen, welche die Standardmenge für die Log-/Transkriptausgabe ersetzt. Bei Tool-Nutzlasten der Control UI werden benutzerdefinierte Muster zusätzlich zu den integrierten Standardmustern angewendet. Das Hinzufügen eines Musters schwächt daher niemals die Schwärzung von Werten ab, die bereits von den Standardmustern erfasst werden.

​

Diagnose und OpenTelemetry

• OpenTelemetry-Export – sendet Metriken, Traces und Logs über OTLP/HTTP an beliebige OpenTelemetry-kompatible Collectors oder Backends (Datadog, Grafana, Honeycomb, New Relic, Tempo usw.). Die vollständige Konfiguration, der Signalkatalog, Metrik-/Span-Namen, Umgebungsvariablen und das 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. Bei Flags wird nicht zwischen Groß- und Kleinschreibung unterschieden, und sie unterstützen Platzhalter (telegram.*, *). Konfigurieren Sie sie unter diagnostics.flags oder über die Umgebungsvariablen-Überschreibung OPENCLAW_DIAGNOSTICS=.... Vollständige Anleitung: Diagnose-Flags.

​

Tipps zur Fehlerbehebung

• Gateway nicht erreichbar? Führen Sie zuerst openclaw doctor aus.
• Logs leer? Prüfen Sie, ob der Gateway ausgeführt wird und in den Dateipfad unter logging.file schreibt.
• Benötigen Sie mehr Details? Setzen Sie logging.level auf debug oder trace und versuchen Sie es erneut.

​

Verwandte Themen

• OpenTelemetry-Export – OTLP/HTTP-Export, Metrik-/Span-Katalog, Datenschutzmodell
• Diagnose-Flags – gezielte Debug-Log-Flags
• Interna der Gateway-Protokollierung – WS-Log-Stile, Subsystempräfixe und Konsolenerfassung
• Konfigurationsreferenz – vollständige Referenz zum Feld diagnostics.*