Diagnostics Flags effektiv nutzen

Kennst du das? Du suchst einen Fehler in der Produktion, aber deine Logs sind entweder komplett leer oder überfluten dich mit so vielen Informationen, dass du die Übersicht verlierst. Den gesamten Service auf Debug-Level zu stellen, ist oft keine Option, weil die schiere Datenmenge die Analyse unmöglich macht.

Diagnostics Flags sind hier die beste Lösung. Sie erlauben dir, gezielt Logs für bestimmte Subsysteme zu aktivieren, ohne das gesamte System in den Verbose-Modus zu versetzen. Das spart Zeit bei der Fehlersuche und schont deine Festplatte.

Voraussetzungen

• Zugriff auf die Konfigurationsdatei oder die Umgebungsvariablen deiner Instanz
• Berechtigungen zum Lesen der Log-Dateien (standardmäßig unter /tmp/openclaw/)

Schnellstart

Du kannst Flags entweder dauerhaft in der Konfiguration oder kurzzeitig per Umgebungsvariable setzen. Flags sind Case-Insensitive und unterstützen Wildcards.

1. Aktivierung über die Config

Füge die Flags in deine Konfigurationsdatei ein. Das ist ideal für Subsysteme, die du dauerhaft im Blick behalten willst.

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

Wichtig: Starte das Gateway neu, nachdem du Änderungen an der Konfiguration vorgenommen hast.

2. Aktivierung per Env Override

Für schnelle Tests oder Einmal-Analysen kannst du die Flags direkt beim Start übergeben:

OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload

Um alle Flags sofort zu deaktivieren, setzt du den Wert auf 0:

OPENCLAW_DIAGNOSTICS=0

Logs auslesen und filtern

Alle Diagnostics Logs landen in der Standard-Log-Datei, normalerweise unter /tmp/openclaw/openclaw-YYYY-MM-DD.log. Wenn du logging.file angepasst hast, findest du sie dort. Die Logs werden im JSONL-Format gespeichert, und sensible Daten werden gemäß deiner logging.redactSensitive Einstellungen geschwärzt.

Um die aktuellste Datei zu finden, nutzt du diesen Befehl:

ls -t /tmp/openclaw/openclaw-*.log | head -n 1

Wenn du gezielt nach Telegram-Fehlern suchst, hilft rg (ripgrep):

rg "telegram http error" /tmp/openclaw/openclaw-*.log

Oder verfolge die Logs live, während du den Fehler reproduzierst:

tail -f /tmp/openclaw/openclaw-$(date +%F).log | rg "telegram http error"

Für Remote-Instanzen kannst du alternativ openclaw logs --follow über das CLI nutzen.

Fehlerbehebung

• Keine Logs sichtbar: Prüfe deinen logging.level. Wenn dieser höher als warn eingestellt ist, werden Diagnostics Logs unterdrückt. Mit dem Standardwert info funktioniert alles problemlos.
• Flags zeigen keine Wirkung: Stelle sicher, dass du das Gateway nach einer Änderung in der JSON-Konfiguration neu gestartet hast. Bei Umgebungsvariablen muss der Prozess mit der neuen Variable gestartet werden.

Es ist absolut sicher, Flags dauerhaft aktiviert zu lassen. Sie erhöhen lediglich das Log-Volumen für das spezifische Subsystem und beeinträchtigen die restliche Systemleistung nicht.

Du hast spezifische Fragen zu einem Flag? Frag den AI Setup Assistant.

Nächste Schritte

• /logging – Erfahre mehr über Log-Ziele und Redaction
• /cli/logs – Details zum Auslesen von Logs über das CLI