Diagnostyka OpenClaw: /health, logi i procedura, gdy agent milczy

Od czego zacząć, zanim otworzysz plik konfiguracyjny

Zacznij od czterech komend, nie od edytora. openclaw status daje przegląd całej instalacji, openclaw gateway status zawęża obraz do samego gatewaya, openclaw doctor wyłapuje i naprawia część problemów sam, a openclaw logs --follow pokazuje ruch na żywo. Zajmuje to minutę. W większości przypadków po tej minucie wiesz już, czy grzebiesz w konfiguracji, czy w uprawnieniach kanału.

Wiesz, że jest dobrze, gdy w wyjściu widzisz trzy rzeczy naraz: „Runtime: running”, „Connectivity probe: ok” oraz linię „Capability” z wartością read-only, write-capable albo admin-capable. Doctor nie zgłasza wtedy blokad, a openclaw channels status --probe pokazuje połączony transport i — tam, gdzie kanał to obsługuje — wpis „works” albo „audit ok”.

Jest jeszcze droga, o której mało kto wie. Wyślij /status jako samodzielną komendę w dowolnym kanale, w którym agent siedzi. Dostaniesz odpowiedź o stanie bez uruchamiania agenta, czyli bez zakładania sesji i bez wywołania modelu. Działa z telefonu, co ma znaczenie o dwudziestej drugiej, gdy nie masz przy sobie dostępu do serwera.

Jeśli zamierzasz komuś ten wynik pokazać, użyj openclaw status --all. Dokumentacja opisuje to jako pełną diagnozę tylko do odczytu, bezpieczną do wklejenia — tokeny są w niej zredagowane. Te cztery komendy plus /status wysłane z telefonu to cały zestaw startowy; reszta lekcji jest o tym, co robić z tym, co zobaczysz.

openclaw status
openclaw gateway status
openclaw doctor
openclaw logs --follow

GET /health — jedyny endpoint, który wolno pingować co minutę

Gateway wystawia osobny endpoint do monitoringu zewnętrznego: GET /health na porcie 18789. Odpowiada natychmiast, nie zakłada sesji, nie woła modelu i zwraca {"ok":true,"status":"live"}. To jest adres, który wpisujesz w UptimeRobota, BetterStacka albo własnego crona — dokumentacja podaje oba te serwisy z nazwy.

Czego nie wpisywać: /v1/chat/completions. Ten endpoint istnieje i odpowie, ale każde wywołanie zakłada pełną sesję agenta ze snapshotem skilli, składaniem kontekstu i wywołaniem modelu. Bez nagłówka x-openclaw-session-key albo pola user każdy ping tworzy nową losową sesję. Monitoring odpytujący co 15 minut robi około 96 sesji dziennie, po 4–22 KB każda. Po miesiącu masz spuchnięty magazyn sesji i ryzyko przepełnienia okna kontekstu — z powodu własnego uptime checka, nie z powodu pracy agenta.

Drobiazg, który kosztuje ludzi godzinę: udokumentowana ścieżka to /health. Odruch wyniesiony z Kubernetesa każe wpisać /healthz i to jest najczęstsza literówka w tym miejscu. W instrukcji ręcznej aktualizacji pojawia się jeszcze curl -fsS http://127.0.0.1:18789/readyz jako weryfikacja po podmianie pakietu. Zanim uznasz, że gateway padł, sprawdź, co dokładnie masz wpisane w monitoringu.

Od strony CLI odpowiednikiem jest openclaw health. Domyślnie oddaje snapshot z cache’u, świeży do 60 sekund, który gateway odświeża w tle; --verbose wymusza żywy probe i dokłada szczegóły połączenia. --json daje wyjście maszynowe, --timeout <ms> nadpisuje domyślne 10 sekund, a wynik w formacie JSON nadaje się wprost do skryptu.

curl -fsS http://127.0.0.1:18789/health
openclaw health --json
openclaw health --verbose

Gdzie leżą logi i dlaczego wczorajszych już nie ma

Domyślnie w /tmp/openclaw/, jeden plik na dobę, nazwa openclaw-YYYY-MM-DD.log. Data bierze się z lokalnej strefy hosta gatewaya. Przy nazwanym profilu nazwa dostaje segment profilu, więc skrót --dev zapisuje do openclaw-dev-YYYY-MM-DD.log. Na Windowsie zawsze, a na innych systemach wtedy, gdy /tmp/openclaw jest niebezpieczny albo niedostępny, OpenClaw przechodzi na katalog openclaw-<uid> w systemowym katalogu tymczasowym.

Teraz rzecz, o której dowiadujesz się zwykle przy pierwszej poważnej awarii: datowane pliki logów są usuwane po 24 godzinach. Zgłoszenie „agent zachował się dziwnie przedwczoraj” nie ma czego badać, jeśli nie ustawiłeś własnej ścieżki. Ustaw logging.file na katalog, który sam kontrolujesz, zanim będzie Ci potrzebny.

Aktywny plik rotuje się, gdy kolejny zapis przekroczyłby logging.maxFileBytes — domyślnie 100 MB. OpenClaw trzyma obok do pięciu ponumerowanych archiwów, od .1 do .5, i pisze dalej do świeżego pliku, zamiast wyciszać diagnostykę.

Format pliku to JSON Lines: jeden obiekt na linię. Poza treścią rekordy niosą pola, po których da się filtrować maszynowo — hostname, message, agent_id, session_id i channel. To one robią różnicę, gdy masz kilku agentów i kilka kanałów, a szukasz jednej rozmowy sprzed trzech godzin.

{
  "logging": {
    "level": "info",
    "file": "/var/log/openclaw/openclaw.log",
    "consoleLevel": "info",
    "consoleStyle": "pretty"
  }
}

consoleStyle: pretty, compact i json — który z nich naprawdę ustawisz

Style konsoli są trzy — pretty, compact i json — ale w konfiguracji ustawiasz dwa. Pretty to czytelne, kolorowane linie z prefiksem podsystemu. Json to jeden obiekt na linię, do wysyłki do zbieracza logów. Compact włącza się sam, gdy wyjście nie jest terminalem, i przestał być wartością, którą wpisuje się do pliku; openclaw doctor --fix mapuje zapisanego compact na pretty. Jeśli masz go w configu z dawnych czasów, doctor to poprawi za Ciebie.

Poziomów jest siedem: silent, fatal, error, warn, info, debug, trace. Klucz logging.level steruje plikiem, logging.consoleLevel konsolą, oba domyślnie na info. Rozdzielenie ma praktyczny sens: konsola ma być czytelna dla człowieka, plik ma mieć wszystko.

Pułapka, na której traci się wieczór. Flaga --verbose podnosi wyłącznie gadatliwość konsoli i styl logów WebSocket — nie rusza poziomu logów zapisywanych do pliku. Jeśli szukasz szczegółów w pliku, podnieś logging.level na debug albo trace. Na jeden przebieg wystarczy zmienna OPENCLAW_LOG_LEVEL=debug, która wygrywa z plikiem konfiguracyjnym, albo globalna opcja --log-level, która wygrywa ze zmienną.

Przy debugowaniu wywołań modelu nie podnoś wszystkiego do debug. Są celowane flagi środowiskowe. OPENCLAW_DEBUG_MODEL_TRANSPORT=1 wypisuje start zapytania, odpowiedź, nagłówki SDK, pierwsze zdarzenie strumienia i błędy transportu. OPENCLAW_DEBUG_MODEL_PAYLOAD=tools dokłada nazwy narzędzi widziane przez model. Wariant full-redacted daje przycięty zrzut zapytania — sekrety są maskowane, ale treść promptów i wiadomości może w nim zostać, więc nie zostawiaj go włączonego na stałe.

OPENCLAW_LOG_LEVEL=debug openclaw gateway
openclaw --log-level debug gateway run
OPENCLAW_DEBUG_MODEL_TRANSPORT=1 openclaw gateway

Agent milczy: prawie zawsze routing, prawie nigdy awaria

Brak odpowiedzi zwykle znaczy, że wiadomość dotarła i została świadomie odrzucona. Logi mówią to wprost, tylko trzeba znać sygnatury. „drop guild message (mention required)” to grupowe bramkowanie wzmianką — agent czeka, aż ktoś go zawoła. „pairing request” znaczy, że nadawca wiadomości prywatnej nie jest jeszcze zatwierdzony. Samo „blocked” albo „allowlist” w logu kanału to nadawca, pokój albo grupa poza listą dozwolonych.

Domyślna polityka wiadomości prywatnych to pairing, więc nieznany nadawca dostaje kod i czeka na zatwierdzenie. Robisz to przez openclaw pairing list --channel <kanał> i openclaw pairing approve. Jeśli chcesz politykę open, pamiętaj o jednym: wymaga ona jawnego wpisu * na allowliście kanału. Samo przestawienie polityki niczego nie otworzy.

W grupach obowiązuje groupAllowFrom. Klucz allowFrom jest tylko zapasem, na który system spada w braku tej pierwszej listy — i to jest miejsce, w którym ludzie gubią się najczęściej, bo wpisują nadawcę w jedno pole, a filtruje drugie. Na Slacku dochodzi osobna pułapka: allowlisty kanałów muszą używać identyfikatorów w formacie C12345678, nie nazw. Wpis w rodzaju #zamowienia po prostu nie zadziała, a w logu zobaczysz zwykłe „blocked”.

Kolejność sprawdzania jest zawsze ta sama. Najpierw openclaw channels status --probe, żeby wykluczyć transport. Potem openclaw pairing list, żeby wykluczyć oczekujące zatwierdzenie. Na końcu openclaw config get channels, żeby zobaczyć, co naprawdę siedzi w konfiguracji, a nie co Ci się wydaje, że tam wpisałeś.

openclaw channels status --probe
openclaw pairing list --channel <kanał>
openclaw pairing approve <kanał> <KOD>
openclaw config get channels

Kanał wysyła, ale nie przyjmuje — dwie osobne awarie

Połączenie kanału i przyjmowanie wiadomości przychodzących to dwie różne domeny awarii. Kanał potrafi mieć sprawne połączenie i normalnie wysyłać odpowiedzi, mając jednocześnie niedostępną trwałą kolejkę wejściową. Wtedy nie wchodzi ani jedna wiadomość, a z zewnątrz wszystko wygląda na sprawne.

Gdy kanał nie może otworzyć swojej kolejki wejściowej, jego start kończy się niepowodzeniem, a gateway zapisuje konto jako niezdolne do odbioru zdarzeń przychodzących, mimo że wysyłka może dalej działać. Takie konto jest oznaczone jako niesprawne niezależnie od stanu transportu i tak samo pokazuje je sprawdzenie gotowości.

Naprawa jest zwykle automatyczna. Kanał ma własną drabinkę restartów z narastającym odstępem — w logach „auto-restart attempt 1/10” i kolejne numery — a monitor zdrowia trzyma się z boku, dopóki ta drabinka się nie wyczerpie. Restarty wywołane niedostępną kolejką mają w logu inny powód niż zwykłe zawieszenie, więc da się je odróżnić bez zgadywania.

Jeśli restarty powtarzają się w kółko, przyczyna nie jest przejściowa i kolejny restart jej nie ruszy. Przeczytaj zapisany powód niepowodzenia: brak uprawnienia do otwarcia kolejki wejściowej wymaga decyzji operatora, nie restartu. Sam monitor da się wyłączyć punktowo kluczem channels.<provider>.healthMonitor.enabled, a przy wielu kontach nadpisać na poziomie konkretnego konta.

Jeszcze jedno nieporozumienie do rozbrojenia. Wiersze sesji nie są miarą tego, czy kanał żyje. openclaw sessions czyta zapisany stan rozmów, a provider może się połączyć i pokazywać zdrowy status, zanim powstanie jakikolwiek nowy wiersz sesji. Do żywej łączności służą status kanału i komendy zdrowia, nie lista sesji.

openclaw channels status --probe
openclaw channels logs --channel slack --lines 200
openclaw health --verbose

Komunikaty, które wyglądają groźnie, a mają jedną komendę

„Invalid config” i „config reload skipped” znaczą, że gateway odmówił przyjęcia nowej wersji pliku. Watcher czeka, aż ucichnie zapis, czyta wersję finalną i odrzuca błędną, nie nadpisując działającego openclaw.json. Odrzucone i nadpisane wersje zostają obok jako openclaw.json.rejected.<timestamp> oraz *.clobbered.* — masz do czego wrócić i co porównać.

EADDRINUSE albo „another gateway instance is already listening” to zajęty port 18789. Sprawdzasz lsof -i :18789, a potem albo zwalniasz port, albo przenosisz gateway kluczem gateway.port. Komunikat „refusing to bind gateway ... without auth” to działanie fail-closed: bez tokenu, hasła albo skonfigurowanego trusted-proxy gateway nie zwiąże się z adresem spoza pętli lokalnej. „Gateway start blocked: set gateway.mode=local” znaczy tyle, że konfiguracji brakuje stempla trybu lokalnego.

„HTTP 429: rate_limit_error” przychodzi od dostawcy modelu i oznacza jego limit. Dokumentacja podaje konkretny przykład od Anthropic: „Extra usage is required for long context requests”. Diagnoza idzie przez openclaw models status i openclaw config get agents.defaults.models, a przy pracy bez nadzoru najsensowniejsza naprawa to modele zapasowe, żeby ruch schodził na fallback zamiast kończyć się błędem.

W Dockerze pojawia się osobny klasyk: „blocked plugin candidate: suspicious ownership (... uid=1000, expected uid=0 or root)”. Pliki pluginu należą do innego użytkownika niż proces, który je ładuje. Instalacje w kontenerze chodzą jako node z uid 1000, więc naprawa to sudo chown -R 1000:1000 na podmontowanych katalogach konfiguracji i workspace, a potem openclaw doctor --fix. Nie usuwaj wtedy wpisu pluginu z konfiguracji — problem jest w uprawnieniach plików, nie w konfiguracji.

openclaw config file
openclaw config validate
openclaw doctor --fix
lsof -i :18789

Zanim poprosisz kogoś o pomoc: pakiet diagnostyczny

Do zgłoszenia nadaje się openclaw gateway diagnostics export. Generuje zip z podsumowaniem w Markdownie, najnowszym pakietem stabilności, oczyszczonymi metadanymi logów, zredagowanymi snapshotami statusu i zdrowia oraz kształtem konfiguracji. Treść czatu, ciała webhooków, wyjścia narzędzi, poświadczenia, ciasteczka i identyfikatory wiadomości są pominięte albo zamaskowane.

Po nagłym wyjściu gatewaya sięgnij po rejestrator stabilności. Fatalne wyjścia, przekroczone limity czasu przy zamykaniu i nieudane starty po restarcie utrwalają snapshot w ~/.openclaw/logs/stability/. Najnowszy czytasz komendą openclaw gateway stability --bundle latest. Znajdziesz tam liczby RSS i sterty oraz opóźnienie pętli zdarzeń, czyli odpowiedź na pytanie, czy zabrakło pamięci, czy proces po prostu utknął przy saturacji.

Maskowanie sekretów jest włączone zawsze i działa na konsoli, w pliku logu, w eksporcie OTLP i w tekście transkryptów sesji. Wartości od 18 znaków w górę zostają z pierwszymi sześcioma i ostatnimi czterema znakami, krótsze zamieniają się w ***. Własne wzorce dokłada się przez logging.redactPatterns — tu dokumentacja jest ostrożna i zaznacza, że podana tablica nadpisuje domyślne, więc dopisując swój wzorzec, przepisz też te, na których Ci zależy.

Krótka uwaga o granicy tej lekcji. To wszystko jest diagnostyką pojedynczej instancji, którą utrzymujesz sam. Jeśli czytanie logów o drugiej w nocy nie jest tym, na co masz ochotę, agenta da się wziąć w chmurze — ClawLabs trzyma instancje w EU na Hetznerze i bierze restarty oraz utrzymanie gatewaya na siebie. Przy self-hoście reszta tej lekcji jest Twoją instrukcją obsługi.

openclaw status --all
openclaw gateway diagnostics export
openclaw gateway stability --bundle latest