Diagnose-Flags

Diagnose-Flags aktivieren zusätzliche Protokollierung für ein einzelnes Subsystem, ohne logging.level global anzuheben. Ein Flag hat keine Wirkung, sofern es nicht von einem Subsystem geprüft wird.

Funktionsweise

• Flags sind Zeichenfolgen, bei denen Groß-/Kleinschreibung nicht berücksichtigt wird. Sie werden aus diagnostics.flags in der Konfiguration sowie der Umgebungsvariablen-Überschreibung OPENCLAW_DIAGNOSTICS ermittelt, dedupliziert und in Kleinbuchstaben umgewandelt.
• name.* entspricht name selbst und allem unterhalb von name. (beispielsweise entspricht telegram.* auch telegram.http).
• * oder all aktiviert alle Flags.
• Starten Sie den Gateway neu, nachdem Sie diagnostics.flags in der Konfiguration geändert haben; die Einstellung wird nicht im laufenden Betrieb neu geladen.

Bekannte Flags

Über die Konfiguration aktivieren

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

Mehrere Flags:

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

Umgebungsvariablen-Überschreibung (einmalig)

OPENCLAW_DIAGNOSTICS=telegram.http,brave.http

Werte werden an Kommas oder Leerzeichen getrennt. Besondere Werte:

OPENCLAW_DIAGNOSTICS=0 deaktiviert für diesen Prozess sowohl Flags aus der Umgebung als auch aus der Konfiguration. Dies ist nützlich, um ein in der Konfiguration aktiviert gebliebenes Profiler-Flag vorübergehend stummzuschalten, ohne die Datei zu bearbeiten.

Profiler-Flags

Profiler-Flags steuern leichtgewichtige Zeitmessspannen; im deaktivierten Zustand verursachen sie keinen Mehraufwand.

Alle durch Profiler-Flags gesteuerten Spannen für einen einzelnen Gateway-Lauf aktivieren:

OPENCLAW_DIAGNOSTICS=profiler openclaw gateway run

Nur Profiler-Spannen für die Antwortweiterleitung aktivieren:

OPENCLAW_DIAGNOSTICS=reply.profiler openclaw gateway run

Nur Profiler-Spannen für Start, Tools und Threads des Codex-App-Servers aktivieren:

OPENCLAW_DIAGNOSTICS=codex.profiler openclaw gateway run

profiler aktiviert sowohl den Antwort-Profiler als auch den Codex-Profiler; verwenden Sie die bereichsspezifischen Flag-Namen, um nur einen davon zu aktivieren.

Alternativ können Sie die Einstellung in der Konfiguration festlegen:

{  "diagnostics": {    "flags": ["reply.profiler", "codex.profiler"]  }}

Starten Sie den Gateway nach dem Ändern der Konfigurations-Flags neu. Um ein Profiler-Flag zu deaktivieren, entfernen Sie es aus diagnostics.flags und starten Sie neu, oder starten Sie den Prozess mit OPENCLAW_DIAGNOSTICS=0, um alle Diagnose-Flags für diesen Lauf zu überschreiben.

Zeitleistenartefakte

Das Flag timeline (Alias: diagnostics.timeline) schreibt strukturierte Zeitmessereignisse für Start und Laufzeit als JSONL für externe QA-Testsysteme:

OPENCLAW_DIAGNOSTICS=timeline \OPENCLAW_DIAGNOSTICS_TIMELINE_PATH=/tmp/openclaw-timeline.jsonl \openclaw gateway run

Alternativ können Sie es in der Konfiguration aktivieren:

{  "diagnostics": {    "flags": ["timeline"]  }}

Der Ausgabepfad stammt immer aus OPENCLAW_DIAGNOSTICS_TIMELINE_PATH, auch wenn das Flag selbst in der Konfiguration gesetzt ist; für den Pfad gibt es keinen Konfigurationsschlüssel. Wenn timeline ausschließlich über die Konfiguration aktiviert wird, fehlen die frühesten Spannen beim Laden der Konfiguration, da OpenClaw die Konfiguration zu diesem Zeitpunkt noch nicht eingelesen hat; nachfolgende Startspannen werden normal erfasst.

OPENCLAW_DIAGNOSTICS=1, =all und =* aktivieren ebenfalls die Zeitleiste, da sie alle Flags aktivieren. Verwenden Sie vorzugsweise das bereichsspezifische Flag timeline, wenn Sie nur das JSONL-Artefakt und nicht alle anderen Diagnose-Flags benötigen.

Messwerte zur Verzögerung der Ereignisschleife in der Zeitleiste erfordern zusätzlich zu timeline eine weitere ausdrückliche Aktivierung: Setzen Sie zusätzlich zur Aktivierung der Zeitleiste OPENCLAW_DIAGNOSTICS_EVENT_LOOP=1 (oder on/true/yes).

Zeitleisteneinträge verwenden den Umschlag openclaw.diagnostics.v1 und können Prozess-IDs, Phasennamen, Spannennamen, Dauern, Plugin-IDs, Anzahlen von Abhängigkeiten, Messwerte zur Verzögerung der Ereignisschleife, Namen von Provider-Vorgängen, den Beendigungsstatus untergeordneter Prozesse sowie Namen und Meldungen von Startfehlern enthalten. Behandeln Sie Zeitleistendateien als lokale Diagnoseartefakte und prüfen Sie sie, bevor Sie sie außerhalb Ihres Rechners weitergeben.

Speicherort der Protokolle

Flags schreiben Protokolle in die standardmäßige Diagnoseprotokolldatei. Standardmäßig:

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

Wenn Sie logging.file festlegen, wird stattdessen dieser Pfad verwendet. Protokolle liegen als JSONL vor (ein JSON- Objekt pro Zeile). Die Schwärzung wird weiterhin gemäß logging.redactSensitive angewendet. Unter Protokollierung finden Sie das vollständige Modell zur Auflösung des Protokollpfads, zur Rotation und zur Schwärzung.

Protokolle extrahieren

Neueste Protokolldatei auswählen:

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

Nach Telegram-HTTP-Diagnosen filtern:

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

Nach HTTP-Diagnosen von Brave Search filtern:

rg "brave http" /tmp/openclaw/openclaw-*.log

Oder das Protokoll während der Reproduktion fortlaufend anzeigen:

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

Verwenden Sie für entfernte Gateways stattdessen openclaw logs --follow (siehe /cli/logs).

Hinweise

• Wenn logging.level höher als warn eingestellt ist, können durch Flags gesteuerte Protokolle unterdrückt werden. Der Standardwert info ist geeignet.
• brave.http protokolliert Anfrage-URLs und Abfrageparameter von Brave Search, den Antwortstatus und die Antwortzeit sowie Cache-Treffer-, Cache-Fehl- und Cache-Schreibereignisse. Es protokolliert weder den API-Schlüssel (der als Anfrage-Header gesendet wird) noch Antwortinhalte, Suchanfragen können jedoch vertraulich sein.
• Flags können bedenkenlos aktiviert bleiben; sie beeinflussen nur das Protokollvolumen des jeweiligen Subsystems.
• Verwenden Sie /logging, um Protokollziele, Protokollstufen und Schwärzung zu ändern.

Verwandte Themen

• Gateway-Diagnose
• Gateway-Fehlerbehebung