OpenClaw nie działa? Diagnostyka błędów i typowych problemów

Pierwsze 60 sekund: cztery komendy zanim zaczniesz grzebać

Zanim otworzysz plik konfiguracyjny i zaczniesz cokolwiek zmieniać, uruchom sekwencję diagnostyczną. Zajmuje mniej więcej minutę i w większości przypadków od razu pokazuje, gdzie leży problem. Ta sama kolejność sprawdza się przy każdej klasie błędu — od nieodpowiadającego agenta po zerwane połączenie kanału.

Komenda openclaw status daje przegląd całej instalacji: system operacyjny wraz z informacją o dostępnej aktualizacji, osiągalność gateway i usługi, listę agentów i sesji, konfigurację providerów oraz problemy runtime. openclaw gateway status zawęża obraz do samego gateway. openclaw doctor wykrywa i naprawia sporą część problemów automatycznie, a openclaw logs --follow pokazuje, co dzieje się na żywo.

Jeśli zamierzasz zgłosić problem gdzieś dalej, użyj openclaw status --all. Dokumentacja opisuje to jako diagnozę tylko do odczytu z ogonem logów i zredagowanymi tokenami — taki output możesz wkleić bez obawy, że wyjdą z niego sekrety. Pełny pakiet diagnostyczny eksportuje openclaw gateway diagnostics export.

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

Gateway nie startuje albo port jest zajęty

Dokumentacja wymienia trzy najczęstsze przyczyny i każda ma własny komunikat. „existing config is missing gateway.mode" oznacza brak trybu pracy — trzeba ustawić gateway.mode na local. „refusing to bind gateway without auth" to efekt działania fail-closed: uwierzytelnianie jest wymagane domyślnie, więc bez skonfigurowanego tokenu, hasła albo trybu trusted-proxy gateway odmawia przyjmowania połączeń WebSocket. Trzeci wariant to EADDRINUSE lub „another gateway instance is already listening".

Konflikt portu sprawdzasz przez lsof -i :18789 — 18789 to domyślny port gateway. Precedencja jest prosta: --port wygrywa z OPENCLAW_GATEWAY_PORT, ta z kluczem gateway.port, a na końcu jest wartość domyślna. Jeśli port zajmuje coś, czego nie chcesz ubijać, przenieś gateway gdzie indziej. CLI ma też flagę --force, która ubija istniejące listenery, oraz --port do jednorazowego nadpisania.

Gdy problem dotyczy usługi systemowej, a nie samego procesu, pomaga przeinstalowanie wpisu: openclaw gateway install --force, potem openclaw gateway start. Warto również przepuścić konfigurację przez openclaw config validate — OpenClaw akceptuje wyłącznie pliki w pełni zgodne ze schematem, a nieznane klucze, złe typy albo niepoprawne wartości blokują start.

lsof -i :18789
openclaw config set gateway.port <nowy_port>
openclaw gateway restart

Agent milczy — najczęściej blokuje routing, nie awaria

Brak odpowiedzi rzadko oznacza, że coś się wywaliło. Znacznie częściej wiadomość dotarła i została świadomie odrzucona przez kontrolę dostępu. Logi mówią to wprost, trzeba tylko wiedzieć, czego szukać.

„drop guild message (mention required" znaczy, że wiadomość grupowa jest ignorowana, dopóki ktoś nie wspomni agenta — to ustawienie requireMention. „pairing request" oznacza, że nadawca DM czeka na zatwierdzenie parowania: domyślna polityka dmPolicy to „pairing", więc nieznany nadawca dostaje kod o ograniczonym czasie życia. Kody wygasają po godzinie, a w WhatsApp oczekujące żądania są limitowane do trzech na konto. Wpisy „blocked" albo „allowlist" wskazują nadawcę lub pokój poza listą dozwolonych.

Zatwierdzanie parowania idzie przez openclaw pairing list <kanał> i openclaw pairing approve <kanał> <CODE>. Osobna pułapka dotyczy Slacka: allowlisty kanałów muszą używać identyfikatorów w formacie C12345678, nie nazw. Klucz oparty na nazwie typu #nazwa-kanalu po cichu nie zadziała przy groupPolicy ustawionym na „allowlist", a w logach zobaczysz tylko zwykłe „blocked".

openclaw channels status --probe
openclaw pairing list --channel <channel>
openclaw config get channels

Wygasłe tokeny kanałów: 401, 403 i „Unauthorized"

Kody 401 i 403 na operacjach kanału to sygnatura utraconego albo niewystarczającego uprawnienia. Zaczynasz od openclaw channels status --probe, potem openclaw logs --follow, a openclaw config get channels pokazuje, co faktycznie siedzi w konfiguracji. Uwierzytelnij kanał ponownie i przy okazji porównaj scope'y z wymaganiami platformy — Slack potrzebuje między innymi app_mentions:read, channels:history, chat:write i users:read, a Discord wymaga włączonego Message Content Intent.

Jeśli 401 wraca mimo ponownego zalogowania, sprawdź cienie OAuth per-agent. Dokumentacja wskazuje tu openclaw doctor --fix, które wykrywa nieaktualne kopie profili uwierzytelniania i je usuwa. Pełna sekwencja to openclaw status --all, następnie openclaw doctor --fix, na końcu openclaw gateway restart.

WhatsApp ma własny scenariusz. Przy pętli reconnectu robisz kopię katalogu poświadczeń, wylogowujesz konto i logujesz się od nowa kodem QR. Poświadczenia leżą w ~/.openclaw/credentials/whatsapp/<accountId>/creds.json, obok trzymana jest kopia creds.json.bak. Pamiętaj też, że wysyłka wychodząca wymaga aktywnego listenera dla danego konta — bez niego kończy się natychmiastowym błędem.

cp -a ~/.openclaw/credentials/whatsapp/<accountId> ~/.openclaw/credentials/whatsapp/<accountId>.bak
openclaw channels logout --channel whatsapp --account <accountId>
openclaw channels login --channel whatsapp --account <accountId>

Limit API i błędy uprawnień systemowych

HTTP 429 z rate_limit_error to przekroczony limit po stronie providera. Dokumentacja podaje konkretny przykład komunikatu Anthropic: „HTTP 429: rate_limit_error: Extra usage is required for long context requests". Diagnoza idzie przez openclaw models status, openclaw logs --follow i openclaw config get agents.defaults.models.

Naprawa ma trzy warianty: przełączenie na model ze standardowym oknem kontekstu, użycie poświadczenia uprawnionego do długiego kontekstu albo skonfigurowanie modeli zapasowych, żeby ruch przechodził na fallback zamiast się wywalać. Ostatnia opcja jest najsensowniejsza, jeśli agent ma pracować bez nadzoru.

Zupełnie inna klasa to permission denied, EACCES oraz komunikaty z sufiksem _PERMISSION_REQUIRED, na przykład LOCATION_PERMISSION_REQUIRED. To brakujące uprawnienie systemu operacyjnego — kamera, mikrofon, lokalizacja albo dostęp do ekranu — i nadaje się je w ustawieniach systemu, nie w konfiguracji OpenClaw. Pomocne komendy: openclaw doctor, openclaw status --deep, openclaw approvals get --node <idOrNameOrIp>.

Osobny przypadek pojawia się w Dockerze: „blocked plugin candidate: suspicious ownership (uid=1000, expected uid=0 or root)". Rozwiązanie to sudo chown -R 1000:1000 <config> <workspace>, a potem openclaw doctor --fix. Przy okazji sprawdź uprawnienia plików — zalecane jest 600 na ~/.openclaw/openclaw.json i 700 na katalogu ~/.openclaw/, bo trzyma poświadczenia kanałów, tokeny OAuth i transkrypty sesji.

openclaw models status
openclaw config get agents.defaults.models

Gdzie są logi i jak je czytać

Logi plikowe lądują domyślnie w /tmp/openclaw/ jako openclaw-YYYY-MM-DD.log. Przy nazwanych profilach nazwa zmienia się na openclaw-<profile>-YYYY-MM-DD.log. Na Windowsie oraz wtedy, gdy katalog domyślny jest niebezpieczny, niezapisywalny albo okazuje się dowiązaniem symbolicznym, OpenClaw przechodzi na os.tmpdir()/openclaw-<uid>. Rotacja startuje przy logging.maxFileBytes, domyślnie 100 MB, i trzyma do pięciu archiwów z sufiksami od .1 do .5.

Zachowanie logowania regulują klucze logging.file, logging.level, logging.consoleLevel, logging.consoleStyle i logging.maxFileBytes. consoleLevel domyślnie stoi na „info", a consoleStyle przyjmuje „pretty”, „compact” albo „json" albo „json". Jedna pułapka warta zapamiętania: flaga --verbose wpływa wyłącznie na wyjście konsolowe i styl logów WebSocket, a nie na poziom logów zapisywanych do pliku. Jeśli szukasz szczegółów w pliku, musisz podnieść logging.level.

Ruch WebSocket podglądasz flagą --ws-log przy openclaw gateway. Tryb auto jest domyślny i pokazuje tylko błędy oraz wolne wywołania, compact paruje request z response, a full wypisuje wszystko per-frame. Po crashu gateway sięgnij po rejestrator zdarzeń diagnostycznych — openclaw gateway stability --bundle latest czyta utrwalone snapshoty stabilności.

Jeśli czytanie logów o drugiej w nocy nie jest tym, na co masz ochotę, agenta można wziąć w chmurze ClawLabs (serwery w EU, Hetzner) — wtedy utrzymanie gateway i restarty są po naszej stronie. Przy self-hoście reszta tej strony wystarczy.

openclaw logs --follow
openclaw gateway stability --bundle latest
openclaw gateway diagnostics export

Agent działa, ale nie robi tego, co powinien

Jeśli agent odpowiada, lecz brakuje mu narzędzi, sprawdź profil narzędzi. Efektywny profil pokaże openclaw status --all albo openclaw doctor.

Nieoczekiwane pytania o zgodę przy wykonywaniu poleceń to kwestia ustawień tools.exec. Sprawdź tools.exec.host, tools.exec.security i tools.exec.ask. Zachowanie bez zatwierdzeń przywracają kolejno host=gateway, security=full i ask=off plus restart gateway, ale bezpieczniejszy układ to security=allowlist z ask=on-miss albo host=auto, które rozwiązuje się do sandboxa.

Cron i heartbeat mają własny słownik komunikatów. „scheduler disabled" to wyłączony scheduler, „heartbeat skipped (quiet-hours)" oznacza porę poza godzinami aktywności, „heartbeat skipped (empty-heartbeat-file)" pojawia się, gdy plik zawiera sam szkielet, a „heartbeat skipped (alerts-disabled)" wymaga włączenia co najmniej jednego alertu — showOk, showAlerts albo useIndicator. „unknown accountId" to po prostu nieistniejące konto docelowe. Podejrzysz to przez openclaw cron status, openclaw cron list i openclaw cron runs --id <jobId> --limit 20.

Gdy konfiguracja została odrzucona, zobaczysz „Invalid config" lub „config reload skipped". Gateway obserwuje plik i przeładowuje zmiany na gorąco, ale edycje z zewnątrz traktuje jako niezaufane do momentu walidacji — czeka, aż ucichnie zapis, czyta plik finalny i odrzuca błędne wersje bez nadpisywania openclaw.json. Odrzucone zapisy zostają obok jako openclaw.json.rejected.<timestamp>, a openclaw doctor --fix przywraca ostatnią znaną dobrą kopię.

openclaw config file
openclaw config validate
openclaw doctor --fix

• minimal — tylko session_status
• messaging — wyłącznie funkcje czatu
• coding — domyślny lokalnie, praca z repo, plikami i shellem
• full — bez ograniczeń, zarezerwowany dla zaufanych agentów