OpenClaw Logging: So behältst du den Durchblick

Irgendetwas funktioniert nicht und du weißt nicht, warum. Wir alle kennen diesen Moment, in dem man die Log-Datei beobachtet und plötzlich die eine Fehlermeldung sieht, die alles erklärt. Logs sind dein erster Anlaufpunkt, wenn es Probleme gibt.

OpenClaw schreibt Logs an zwei Stellen: in eine JSON-Datei für die automatisierte Auswertung und in die Console für dich. Hier erfährst du, wie du beide Quellen nutzt.

Voraussetzungen

• OpenClaw Gateway
• Zugriff auf dein Terminal
• Eine gültige Konfigurationsdatei
• Installiertes OpenClaw CLI

Schnellstart

Standardmäßig schreibt das Gateway eine rolling log file unter diesem Pfad:

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

Du kannst das in deiner Config anpassen:

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

Logs im Terminal lesen

Nutze den CLI-Befehl für einen Live-View:

openclaw logs --follow

Output modes:

• TTY: Formatiert, farbig und strukturiert
• Non-TTY: Plain text
• --json: Line-delimited JSON
• --plain: Erzwingt Plain text
• --no-color: Deaktiviert ANSI-Farben

Control UI und Channels

Der Logs Tab in der Control UI zeigt dir dieselben Daten. Starte sie mit openclaw control. Wenn du nur Logs für bestimmte Channels sehen willst, hilft dieser Befehl:

openclaw channels logs --channel whatsapp

Log Levels

Du kannst die Ausführlichkeit der Logs in der Config steuern:

{
  logging: {
    level: "info",           // Level für die Datei
    consoleLevel: "info",    // Level für die Console
    consoleStyle: "pretty"   // pretty | compact | json
  }
}

Verfügbare Levels sind: trace, debug, info, warn, error. Das --verbose Flag beeinflusst nur die Console, nicht die Log-Datei.

Redaction

Um sensible Daten in der Console zu schützen, kannst du Redaction aktivieren. Das betrifft nur die Console – in der Log-Datei bleiben die Daten ungeschwärzt.

{
  logging: {
    redactSensitive: "tools",        // off | tools
    redactPatterns: ["sk-.*"]        // Eigene Regex-Patterns
  }
}

Diagnostics & OpenTelemetry

Für das Monitoring in Production kannst du Metriken und Traces an deinen Observability-Stack senden.

Diagnostics aktivieren

{
  diagnostics: {
    enabled: true
  }
}

Export via OpenTelemetry

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

Exportierte Daten

Metrics:

• openclaw.tokens — Token-Verbrauch
• openclaw.cost.usd — Kosten-Tracking
• openclaw.run.duration_ms — Dauer der Ausführung
• openclaw.webhook.received — Webhook-Aktivität
• openclaw.message.processed — Nachrichtendurchsatz

Traces:

• openclaw.model.usage — Spans für Model Completions
• openclaw.webhook.processed — Webhook-Verarbeitung
• openclaw.message.processed — Nachrichten-Handling

Debug Flags

Wenn du gezielt Logs für bestimmte Bereiche brauchst, ohne das globale Level zu ändern, nutze Flags:

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

Oder via Environment Variable:

OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload

Wildcards wie telegram.* oder * funktionieren ebenfalls.

JSON Mode Details

Im --json Modus gibt die CLI typisierte Objekte aus:

Type	Beschreibung
meta	Stream-Metadaten (Datei, Cursor, Größe)
log	Parsed log entry
notice	Hinweise zu Rotation oder Kürzungen
raw	Ungefilterte Log-Zeile

Diagnostic Event Catalog

Model Usage Events

Event	Beschreibung
model.usage	Tokens, Kosten, Dauer, Kontext, Provider/Model/Channel, Session IDs

Message Flow Events

Event	Beschreibung
webhook.received	Webhook-Eingang pro Channel
webhook.processed	Webhook erfolgreich verarbeitet + Dauer
webhook.error	Fehler im Webhook-Handler
message.queued	Nachricht in Warteschlange eingereiht
message.processed	Ergebnis + Dauer + optionaler Fehler

Queue + Session Events

Event	Beschreibung
queue.lane.enqueue	Enqueue in Queue Lane + Tiefe
queue.lane.dequeue	Dequeue aus Queue Lane + Wartezeit
session.state	Session Status-Übergang + Grund
session.stuck	Warnung bei hängender Session + Alter
run.attempt	Metadaten zu Retries
diagnostic.heartbeat	Aggregierte Counter (Webhooks/Queue/Session)

Exportierte Metriken

Model Usage

Metric	Type	Attribute
openclaw.tokens	Counter	type, channel, provider, model
openclaw.cost.usd	Counter	channel, provider, model
openclaw.run.duration_ms	Histogram	channel, provider, model
openclaw.context.tokens	Histogram	context, channel, provider, model

Message Flow

Metric	Type	Attribute
openclaw.webhook.received	Counter	channel, webhook
openclaw.webhook.error	Counter	channel, webhook
openclaw.webhook.duration_ms	Histogram	channel, webhook
openclaw.message.queued	Counter	channel, source
openclaw.message.processed	Counter	channel, outcome
openclaw.message.duration_ms	Histogram	channel, outcome

Exportierte Spans

Span	Key Attribute
openclaw.model.usage	channel, provider, model, sessionKey, sessionId, tokens.*
openclaw.webhook.processed	channel, webhook, chatId
openclaw.webhook.error	channel, webhook, chatId, error
openclaw.message.processed	channel, outcome, chatId, messageId, sessionKey, sessionId, reason

Protocol Notes

• OTLP/HTTP Endpunkte via diagnostics.otel.endpoint oder OTEL_EXPORTER_OTLP_ENDPOINT
• Wenn der Endpunkt /v1/traces, /v1/metrics oder /v1/logs enthält, wird er direkt genutzt
• Aktuell wird nur http/protobuf unterstützt (grpc wird ignoriert)
• OTLP Logs nutzen dieselben strukturierten Daten wie logging.file
• Console Redaction gilt nicht für OTLP Logs

Fehlerbehebung

”Gateway not reachable”

Nutze diesen Befehl zur Diagnose:

openclaw doctor

Logs sind leer

Prüfe, ob das Gateway läuft und ob logging.file auf den korrekten Pfad zeigt.

Mehr Details benötigt

Setze das logging.level auf debug oder trace:

{
  logging: {
    level: "debug"
  }
}

Du kommst nicht weiter? Unser AI Setup Assistant hilft dir dabei, deine Logs zu interpretieren.

Nächste Schritte

• Debugging → — Watch mode und raw stream logging
• Testing → — Test suites und Live-Tests
• Gateway Configuration → — Vollständige Konfigurations-Referenz