Flagi diagnostyczne

Flagi diagnostyczne pozwalają włączać ukierunkowane logi debugowania bez włączania szczegółowego logowania wszędzie. Flagi są opcjonalne i nie mają wpływu, chyba że dany podsystem je sprawdza.

# Jak to działa

• Flagi to ciągi znaków (bez rozróżniania wielkości liter).
• Flagi można włączyć w konfiguracji lub przez nadpisanie zmienną środowiskową.
• Obsługiwane są symbole wieloznaczne:
  • telegram.* pasuje do telegram.http
  • * włącza wszystkie flagi

# Włączanie przez konfigurację

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

Wiele flag:

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

Uruchom ponownie Gateway po zmianie flag.

# Nadpisanie zmienną środowiskową (jednorazowe)

OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload

Wyłączenie wszystkich flag:

OPENCLAW_DIAGNOSTICS=0

# Artefakty osi czasu

Flaga timeline zapisuje ustrukturyzowane zdarzenia czasowe uruchamiania i działania dla zewnętrznych narzędzi QA:

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

Możesz też włączyć ją w konfiguracji:

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

Ścieżka pliku osi czasu nadal pochodzi z OPENCLAW_DIAGNOSTICS_TIMELINE_PATH. Gdy timeline jest włączona tylko z konfiguracji, najwcześniejsze zakresy ładowania konfiguracji nie są emitowane, ponieważ OpenClaw nie odczytał jeszcze konfiguracji; kolejne zakresy uruchamiania używają flagi z konfiguracji.

OPENCLAW_DIAGNOSTICS=1, OPENCLAW_DIAGNOSTICS=all oraz OPENCLAW_DIAGNOSTICS=* również włączają oś czasu, ponieważ włączają każdą flagę diagnostyczną. Użyj timeline, gdy potrzebujesz tylko artefaktu czasowego JSONL.

Rekordy osi czasu używają koperty openclaw.diagnostics.v1. Zdarzenia mogą zawierać identyfikatory procesów, nazwy faz, nazwy zakresów, czasy trwania, identyfikatory pluginów, liczby zależności, próbki opóźnień pętli zdarzeń, nazwy operacji dostawców, stan zakończenia procesów potomnych oraz nazwy/komunikaty błędów uruchamiania. Traktuj pliki osi czasu jako lokalne artefakty diagnostyczne; przejrzyj je przed udostępnieniem poza swoją maszynę.

# Gdzie trafiają logi

Flagi emitują logi do standardowego pliku logu diagnostycznego. Domyślnie:

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

Jeśli ustawisz logging.file, użyj zamiast tego tej ścieżki. Logi są w formacie JSONL (jeden obiekt JSON na wiersz). Redakcja nadal obowiązuje zgodnie z logging.redactSensitive.

# Wyodrębnianie logów

Wybierz najnowszy plik logu:

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

Filtruj diagnostykę HTTP Telegram:

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

Filtruj diagnostykę HTTP Brave Search:

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

Albo śledź log podczas odtwarzania problemu:

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

W przypadku zdalnych Gateway możesz też użyć openclaw logs --follow (zobacz /cli/logs).

# Uwagi

• Jeśli logging.level jest ustawiony wyżej niż warn, te logi mogą zostać wyciszone. Domyślne info jest odpowiednie.
• brave.http loguje adresy URL/parametry zapytań żądań Brave Search, status/czas odpowiedzi oraz zdarzenia trafienia/pominięcia/zapisu w pamięci podręcznej. Nie loguje kluczy API ani treści odpowiedzi, ale zapytania wyszukiwania mogą być wrażliwe.
• Flagi można bezpiecznie pozostawić włączone; wpływają tylko na objętość logów konkretnego podsystemu.
• Użyj /logging, aby zmienić miejsca docelowe logów, poziomy i redakcję.

# Powiązane

• Diagnostyka Gateway
• Rozwiązywanie problemów z Gateway