Przejdź do głównej treści

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

OpenClaw ma dwie główne powierzchnie logów:
  • Logi plikowe (wiersze JSON) zapisywane przez Gateway.
  • Wyjście konsoli wyświetlane w terminalach i w interfejsie Gateway Debug UI.
Karta Logi w interfejsie Control UI śledzi plik logu gateway. Ta strona wyjaśnia, gdzie znajdują się logi, jak je czytać oraz jak konfigurować poziomy i formaty logowania.

​
Gdzie znajdują się logi

Domyślnie Gateway zapisuje rotowany plik logu pod ścieżką: /tmp/openclaw/openclaw-YYYY-MM-DD.log Data używa lokalnej strefy czasowej hosta gateway. Każdy plik jest rotowany po osiągnięciu logging.maxFileBytes (domyślnie: 100 MB). OpenClaw przechowuje obok aktywnego pliku do pięciu numerowanych archiwów, takich jak openclaw-YYYY-MM-DD.1.log, i zapisuje dalej do nowego aktywnego logu zamiast tłumić diagnostykę. Możesz to nadpisać w ~/.openclaw/openclaw.json: 
{
  "logging": {
    "file": "/path/to/openclaw.log"
  }
}

​
Jak czytać logi

​
CLI: śledzenie na żywo (zalecane)

Użyj CLI, aby śledzić plik logu gateway przez RPC: 
openclaw logs --follow
Przydatne bieżące opcje:
  • --local-time: renderuje znaczniki czasu w Twojej lokalnej strefie czasowej
  • --url <url> / --token <token> / --timeout <ms>: standardowe flagi RPC Gateway
  • --expect-final: flaga oczekiwania na końcową odpowiedź RPC obsługiwaną przez agenta (akceptowana tutaj przez współdzieloną warstwę klienta)
Tryby wyjścia:
  • Sesje TTY: estetyczne, kolorowe, ustrukturyzowane wiersze logu.
  • Sesje inne niż TTY: zwykły tekst.
  • --json: JSON rozdzielany wierszami (jedno zdarzenie logu na wiersz).
  • --plain: wymusza zwykły tekst w sesjach TTY.
  • --no-color: wyłącza kolory ANSI.
Gdy przekażesz jawne --url, CLI nie stosuje automatycznie konfiguracji ani poświadczeń ze środowiska; dodaj samodzielnie --token, jeśli docelowy Gateway wymaga uwierzytelniania. W trybie JSON CLI emituje obiekty oznaczone polem type:
  • meta: metadane strumienia (plik, kursor, rozmiar)
  • log: sparsowany wpis logu
  • notice: wskazówki dotyczące obcięcia / rotacji
  • raw: niesparsowany wiersz logu
Jeśli niejawny Gateway local loopback poprosi o parowanie, zamknie się podczas łączenia albo przekroczy limit czasu, zanim logs.tail odpowie, openclaw logs automatycznie przełączy się awaryjnie na skonfigurowany plik logu Gateway. Jawne cele --url nie używają tego mechanizmu awaryjnego. Jeśli Gateway jest nieosiągalny, CLI wypisze krótką wskazówkę, aby uruchomić: 
openclaw doctor

​
Control UI (web)

Karta Logi w interfejsie Control UI śledzi ten sam plik przy użyciu logs.tail. Zobacz Control UI, aby dowiedzieć się, jak go otworzyć.

​
Logi tylko kanału

Aby filtrować aktywność kanału (WhatsApp/Telegram/itd.), użyj: 
openclaw channels logs --channel whatsapp

​
Formaty logów

​
Logi plikowe (JSONL)

Każdy wiersz w pliku logu jest obiektem JSON. CLI i Control UI parsują te wpisy, aby renderować ustrukturyzowane wyjście (czas, poziom, podsystem, komunikat). Rekordy JSONL logów plikowych zawierają też pola najwyższego poziomu możliwe do filtrowania maszynowo, gdy są dostępne:
  • hostname: nazwa hosta gateway.
  • message: spłaszczony tekst komunikatu logu do wyszukiwania pełnotekstowego.
  • agent_id: identyfikator aktywnego agenta, gdy wywołanie logowania niesie kontekst agenta.
  • session_id: identyfikator/klucz aktywnej sesji, gdy wywołanie logowania niesie kontekst sesji.
  • channel: aktywny kanał, gdy wywołanie logowania niesie kontekst kanału.
OpenClaw zachowuje oryginalne ustrukturyzowane argumenty logu obok tych pól, dzięki czemu istniejące parsery czytające numerowane klucze argumentów tslog nadal działają. Aktywność rozmów, głosu w czasie rzeczywistym i zarządzanych pokojów emituje ograniczone rekordy logu cyklu życia przez ten sam potok logów plikowych. Rekordy te zawierają typ zdarzenia, tryb, transport, dostawcę oraz pomiary rozmiaru/czasu, gdy są dostępne, ale pomijają tekst transkrypcji, ładunki audio, identyfikatory tur, identyfikatory połączeń i identyfikatory elementów dostawcy.

​
Wyjście konsoli

Logi konsoli są świadome TTY i formatowane pod kątem czytelności:
  • Prefiksy podsystemów (np. gateway/channels/whatsapp)
  • Kolorowanie poziomów (info/warn/error)
  • Opcjonalny tryb kompaktowy lub JSON
Formatowanie konsoli jest kontrolowane przez logging.consoleStyle.

​
Logi WebSocket Gateway

openclaw gateway ma też logowanie protokołu WebSocket dla ruchu RPC:
  • tryb normalny: tylko interesujące wyniki (błędy, błędy parsowania, wolne wywołania)
  • --verbose: cały ruch żądanie/odpowiedź
  • --ws-log auto|compact|full: wybiera styl renderowania szczegółowego
  • --compact: alias dla --ws-log compact
Przykłady: 
openclaw gateway
openclaw gateway --verbose --ws-log compact
openclaw gateway --verbose --ws-log full

​
Konfigurowanie logowania

Cała konfiguracja logowania znajduje się pod logging w ~/.openclaw/openclaw.json. 
{
  "logging": {
    "level": "info",
    "file": "/tmp/openclaw/openclaw-YYYY-MM-DD.log",
    "consoleLevel": "info",
    "consoleStyle": "pretty",
    "redactSensitive": "tools",
    "redactPatterns": ["sk-.*"]
  }
}

​
Poziomy logowania

  • logging.level: poziom logów plikowych (JSONL).
  • logging.consoleLevel: poziom szczegółowości konsoli.
Możesz nadpisać oba za pomocą zmiennej środowiskowej OPENCLAW_LOG_LEVEL (np. OPENCLAW_LOG_LEVEL=debug). Zmienna środowiskowa ma pierwszeństwo przed plikiem konfiguracji, więc możesz zwiększyć szczegółowość dla pojedynczego uruchomienia bez edytowania openclaw.json. Możesz też przekazać globalną opcję CLI --log-level <level> (na przykład openclaw --log-level debug gateway run), która nadpisuje zmienną środowiskową dla tego polecenia. --verbose wpływa tylko na wyjście konsoli i szczegółowość logów WS; nie zmienia poziomów logów plikowych.

​
Ukierunkowana diagnostyka transportu modelu

Podczas debugowania wywołań dostawcy używaj ukierunkowanych flag środowiskowych zamiast zwiększać wszystkie logi do debug: 
OPENCLAW_DEBUG_MODEL_TRANSPORT=1 openclaw gateway
OPENCLAW_DEBUG_MODEL_PAYLOAD=tools OPENCLAW_DEBUG_SSE=events openclaw gateway
Dostępne flagi:
  • OPENCLAW_DEBUG_MODEL_TRANSPORT=1: emituje rozpoczęcie żądania, odpowiedź fetch, nagłówki SDK, pierwsze zdarzenie strumieniowania, zakończenie strumienia i błędy transportu na poziomie info.
  • OPENCLAW_DEBUG_MODEL_PAYLOAD=summary: dołącza ograniczone podsumowanie ładunku żądania do logów żądań modelu.
  • OPENCLAW_DEBUG_MODEL_PAYLOAD=tools: dołącza wszystkie nazwy narzędzi widoczne dla modelu do podsumowania ładunku.
  • OPENCLAW_DEBUG_MODEL_PAYLOAD=full-redacted: dołącza zredagowaną, ograniczoną migawkę ładunku JSON. Używaj tylko podczas debugowania; sekrety są redagowane, ale prompty i tekst wiadomości mogą nadal być obecne.
  • OPENCLAW_DEBUG_SSE=events: emituje czas do pierwszego zdarzenia i czas zakończenia strumienia.
  • OPENCLAW_DEBUG_SSE=peek: emituje także pierwsze pięć zredagowanych ładunków zdarzeń SSE, ograniczonych dla każdego zdarzenia.
  • OPENCLAW_DEBUG_CODE_MODE=1: emituje diagnostykę powierzchni modelu w trybie kodu, w tym sytuacje, gdy natywne narzędzia dostawcy są ukryte, ponieważ tryb kodu posiada powierzchnię narzędzi.
Te flagi logują przez normalne logowanie OpenClaw, więc openclaw logs --follow i karta Logi w Control UI je pokazują. Bez tych flag ta sama diagnostyka pozostaje dostępna na poziomie debug.

​
Korelacja śladów

Logi plikowe są w formacie JSONL. Gdy wywołanie logowania niesie prawidłowy kontekst śladu diagnostycznego, OpenClaw zapisuje pola śladu jako klucze JSON najwyższego poziomu (traceId, spanId, parentSpanId, traceFlags), aby zewnętrzne procesory logów mogły skorelować wiersz ze spanami OTEL i propagacją traceparent dostawcy. Żądania HTTP Gateway i ramki WebSocket Gateway ustanawiają wewnętrzny zakres śladu żądania. Logi i zdarzenia diagnostyczne emitowane wewnątrz tego zakresu asynchronicznego dziedziczą ślad żądania, gdy nie przekazują jawnego kontekstu śladu. Ślady uruchomień agentów i wywołań modelu stają się dziećmi aktywnego śladu żądania, więc lokalne logi, migawki diagnostyczne, spany OTEL i zaufane nagłówki traceparent dostawcy można łączyć przez traceId bez logowania surowej treści żądania lub modelu. Rekordy logu cyklu życia rozmów trafiają też do logów OTLP, gdy eksport logów OpenTelemetry jest włączony, używając tych samych ograniczonych atrybutów co logi plikowe.

​
Rozmiar i czas wywołań modelu

Diagnostyka wywołań modelu rejestruje ograniczone pomiary żądań/odpowiedzi bez przechwytywania surowej treści promptu lub odpowiedzi:
  • requestPayloadBytes: rozmiar w bajtach UTF-8 końcowego ładunku żądania modelu
  • responseStreamBytes: rozmiar w bajtach UTF-8 strumieniowanych zdarzeń odpowiedzi modelu
  • timeToFirstByteMs: czas, który upłynął przed pierwszym strumieniowanym zdarzeniem odpowiedzi
  • durationMs: całkowity czas trwania wywołania modelu
Te pola są dostępne dla migawek diagnostycznych, hooków Plugin wywołań modelu i spanów/metryk OTEL wywołań modelu, gdy eksport diagnostyki jest włączony.

​
Style konsoli

logging.consoleStyle:
  • pretty: przyjazny dla człowieka, kolorowy, ze znacznikami czasu.
  • compact: bardziej zwarte wyjście (najlepsze dla długich sesji).
  • json: JSON w każdym wierszu (dla procesorów logów).

​
Redagowanie

OpenClaw może redagować wrażliwe tokeny, zanim trafią do wyjścia konsoli, logów plikowych, rekordów logów OTLP, utrwalonego tekstu transkrypcji sesji lub ładunków zdarzeń narzędzi w Control UI (argumenty startu narzędzia, częściowe/końcowe ładunki wyników, pochodne wyjście exec i podsumowania poprawek):
  • logging.redactSensitive: off | tools (domyślnie: tools)
  • logging.redactPatterns: lista ciągów regex do nadpisania domyślnego zestawu. Niestandardowe wzorce są stosowane oprócz wbudowanych wartości domyślnych dla ładunków narzędzi Control UI, więc dodanie wzorca nigdy nie osłabia redagowania wartości już wychwytywanych przez wartości domyślne.
Logi plikowe i transkrypcje sesji pozostają JSONL, ale pasujące wartości sekretów są maskowane przed zapisaniem wiersza lub wiadomości na dysku. Redagowanie jest najlepszym możliwym wysiłkiem: stosuje się do treści wiadomości zawierającej tekst i ciągów logów, nie do każdego identyfikatora lub pola ładunku binarnego. Wbudowane wartości domyślne obejmują typowe poświadczenia API i nazwy pól poświadczeń płatniczych, takie jak numer karty, CVC/CVV, współdzielony token płatności i poświadczenie płatnicze, gdy pojawiają się jako pola JSON, parametry URL, flagi CLI lub przypisania. logging.redactSensitive: "off" wyłącza tylko tę ogólną politykę logów/transkrypcji. OpenClaw nadal redaguje ładunki granicy bezpieczeństwa, które mogą być pokazywane klientom UI, pakietom wsparcia, obserwatorom diagnostyki, promptom zatwierdzeń lub narzędziom agentów. Przykłady obejmują zdarzenia wywołań narzędzi Control UI, wyjście sessions_history, eksporty wsparcia diagnostycznego, obserwacje błędów dostawcy, wyświetlanie polecenia zatwierdzenia exec i logi protokołu WebSocket Gateway. Niestandardowe logging.redactPatterns mogą nadal dodawać wzorce specyficzne dla projektu na tych powierzchniach.

​
Diagnostyka i OpenTelemetry

Diagnostyka to ustrukturyzowane, czytelne maszynowo zdarzenia dla uruchomień modelu i telemetrii przepływu wiadomości (Webhook, kolejkowanie, stan sesji). Nie zastępują logów — zasilają metryki, ślady i eksportery. Zdarzenia są emitowane w procesie niezależnie od tego, czy je eksportujesz. Dwie sąsiednie powierzchnie:
  • Eksport OpenTelemetry — wysyła metryki, ślady i logi przez OTLP/HTTP do dowolnego kolektora lub backendu zgodnego z OpenTelemetry (Grafana, Datadog, Honeycomb, New Relic, Tempo itd.). Pełna konfiguracja, katalog sygnałów, nazwy metryk/spanów, zmienne środowiskowe i model prywatności znajdują się na dedykowanej stronie: Eksport OpenTelemetry.
  • Flagi diagnostyczne — ukierunkowane flagi logów debugowania, które kierują dodatkowe logi do logging.file bez zwiększania logging.level. Flagi nie rozróżniają wielkości liter i obsługują symbole wieloznaczne (telegram.*, *). Skonfiguruj w diagnostics.flags lub przez nadpisanie środowiskowe OPENCLAW_DIAGNOSTICS=.... Pełny przewodnik: Flagi diagnostyczne.
Aby włączyć zdarzenia diagnostyczne dla plugins lub niestandardowych odbiorników bez eksportu OTLP: 
{
  diagnostics: { enabled: true },
}
W przypadku eksportu OTLP do kolektora zobacz Eksport OpenTelemetry.

​
Wskazówki dotyczące rozwiązywania problemów

  • Gateway nieosiągalny? Najpierw uruchom openclaw doctor.
  • Logi puste? Sprawdź, czy Gateway działa i zapisuje do ścieżki pliku w logging.file.
  • Potrzebujesz więcej szczegółów? Ustaw logging.level na debug lub trace i spróbuj ponownie.

​
Powiązane