Rozwiązywanie problemów

• model_not_found z lokalnym serwerem w stylu MLX/vLLM → sprawdź, czy baseUrl zawiera /v1, api ma wartość "openai-completions" dla backendów /v1/chat/completions, a models.providers.<provider>.models[].id jest nieprefiksowanym lokalnym identyfikatorem dostawcy. Wybierz go raz z prefiksem dostawcy, na przykład mlx/mlx-community/Qwen3-30B-A3B-6bit; zachowaj wpis katalogu jako mlx-community/Qwen3-30B-A3B-6bit.
• messages[...].content: invalid type: sequence, expected a string → backend odrzuca strukturalne części treści Chat Completions. Naprawa: ustaw models.providers.<provider>.models[].compat.requiresStringContent: true.
• incomplete turn detected ... stopReason=stop payloads=0 → backend zakończył żądanie Chat Completions, ale nie zwrócił widocznego dla użytkownika tekstu asystenta dla tej tury. OpenClaw jednokrotnie ponawia bezpieczne do odtworzenia puste tury zgodne z OpenAI; utrzymujące się awarie zwykle oznaczają, że backend emituje pustą/nietekstową treść albo tłumi tekst końcowej odpowiedzi.
• bezpośrednie małe żądania się udają, ale uruchomienia agentów OpenClaw zawodzą przez awarie backendu/modelu (na przykład Gemma w niektórych kompilacjach inferrs) → transport OpenClaw najpewniej jest już poprawny; backend zawodzi na większym kształcie promptu środowiska uruchomieniowego agenta.
• awarie zmniejszają się po wyłączeniu narzędzi, ale nie znikają → schematy narzędzi były częścią obciążenia, ale pozostały problem nadal dotyczy wydajności upstreamowego modelu/serwera albo błędu backendu.

1. Ustaw compat.requiresStringContent: true dla backendów Chat Completions obsługujących tylko ciągi znaków.
2. Ustaw compat.supportsTools: false dla modeli/backendów, które nie obsługują niezawodnie powierzchni schematów narzędzi OpenClaw.
3. Gdzie to możliwe, obniż obciążenie promptu: mniejszy bootstrap przestrzeni roboczej, krótsza historia sesji, lżejszy model lokalny albo backend z lepszą obsługą długiego kontekstu.
4. Jeśli małe bezpośrednie żądania nadal przechodzą, a tury agentów OpenClaw wciąż powodują awarie wewnątrz backendu, traktuj to jako ograniczenie upstreamowego serwera/modelu i zgłoś tam reprodukcję z zaakceptowanym kształtem payloadu.

• device identity required → niezabezpieczony kontekst albo brak uwierzytelniania urządzenia.
• origin not allowed → przeglądarkowy Origin nie znajduje się w gateway.controlUi.allowedOrigins (albo łączysz się z pochodzenia przeglądarki innego niż local loopback bez jawnej listy dozwolonych).
• device nonce required / device nonce mismatch → klient nie kończy przepływu uwierzytelniania urządzenia opartego na wyzwaniu (connect.challenge + device.nonce).
• device signature invalid / device signature expired → klient podpisał niewłaściwy payload (albo nieaktualny znacznik czasu) dla bieżącego handshake'u.
• AUTH_TOKEN_MISMATCH z canRetryWithDeviceToken=true → klient może wykonać jedną zaufaną próbę ponowienia z buforowanym tokenem urządzenia.
• Ta próba ponowienia z buforowanym tokenem używa buforowanego zestawu zakresów zapisanego ze sparowanym tokenem urządzenia. Wywołujący z jawnym deviceToken / jawnymi scopes zachowują zamiast tego swój żądany zestaw zakresów.
• Poza tą ścieżką ponowienia pierwszeństwo uwierzytelniania połączenia to najpierw jawny współdzielony token/hasło, potem jawny deviceToken, potem zapisany token urządzenia, a następnie token bootstrapu.
• Na asynchronicznej ścieżce interfejsu sterowania Tailscale Serve nieudane próby dla tego samego {scope, ip} są serializowane, zanim limiter zapisze niepowodzenie. Dwie złe równoczesne próby ponowienia z tego samego klienta mogą więc pokazać retry later przy drugiej próbie zamiast dwóch zwykłych niezgodności.
• too many failed authentication attempts (retry later) z klienta przeglądarkowego pochodzącego z local loopback → powtarzające się niepowodzenia z tego samego znormalizowanego Origin są tymczasowo blokowane; inne pochodzenie localhost używa osobnego zasobnika.
• powtarzające się unauthorized po tej próbie ponowienia → rozjazd współdzielonego tokenu/tokenu urządzenia; odśwież konfigurację tokenu i w razie potrzeby ponownie zatwierdź/obróć token urządzenia.
• gateway connect failed: → niewłaściwy host/port/docelowy adres URL.

• Gateway start blocked: set gateway.mode=local lub existing config is missing gateway.mode → lokalny tryb Gateway nie jest włączony albo plik konfiguracji został nadpisany i utracił gateway.mode. Poprawka: ustaw gateway.mode="local" w konfiguracji albo ponownie uruchom openclaw onboard --mode local / openclaw setup, aby ponownie ostemplować oczekiwaną konfigurację trybu lokalnego. Jeśli uruchamiasz OpenClaw przez Podman, domyślna ścieżka konfiguracji to ~/.openclaw/openclaw.json.
• refusing to bind gateway ... without auth → wiązanie poza loopback bez prawidłowej ścieżki uwierzytelniania Gateway (token/hasło albo zaufane proxy, jeśli skonfigurowane).
• another gateway instance is already listening / EADDRINUSE → konflikt portu.
• Other gateway-like services detected (best effort) → istnieją nieaktualne lub równoległe jednostki launchd/systemd/schtasks. Większość konfiguracji powinna utrzymywać jeden Gateway na maszynę; jeśli potrzebujesz więcej niż jednego, odizoluj porty oraz konfigurację/stan/przestrzeń roboczą. Zobacz /gateway#multiple-gateways-same-host.
• System-level OpenClaw gateway service detected z doctor → istnieje systemowa jednostka systemd, gdy brakuje usługi na poziomie użytkownika. Usuń lub wyłącz duplikat przed zezwoleniem doctor na instalację usługi użytkownika albo ustaw OPENCLAW_SERVICE_REPAIR_POLICY=external, jeśli jednostka systemowa jest zamierzonym nadzorcą.
• Gateway service port does not match current gateway config → zainstalowany nadzorca nadal przypina stary --port. Uruchom openclaw doctor --fix albo openclaw gateway install --force, a następnie zrestartuj usługę Gateway.

• Konfiguracja nie przeszła walidacji podczas uruchamiania, przeładowania na gorąco lub zapisu wykonywanego przez OpenClaw.
• Uruchomienie Gateway kończy się zamknięciem zamiast przepisania openclaw.json.
• Przeładowanie na gorąco pomija nieprawidłowe edycje zewnętrzne i utrzymuje aktywną bieżącą konfigurację środowiska uruchomieniowego.
• Zapisy wykonywane przez OpenClaw odrzucają nieprawidłowe/destrukcyjne ładunki przed zatwierdzeniem i zapisują .rejected.*.
• openclaw doctor --fix odpowiada za naprawę. Może usunąć prefiksy niebędące JSON-em albo przywrócić ostatnią znaną dobrą kopię, zachowując odrzucony ładunek jako .clobbered.*.

CONFIG="$(openclaw config file)"
ls -lt "$CONFIG".clobbered.* "$CONFIG".rejected.* 2>/dev/null | head
diff -u "$CONFIG" "$(ls -t "$CONFIG".clobbered.* 2>/dev/null | head -n 1)"
openclaw config validate
openclaw doctor

• .clobbered.* istnieje → doctor zachował uszkodzoną edycję zewnętrzną podczas naprawy aktywnej konfiguracji.
• .rejected.* istnieje → zapis konfiguracji wykonywany przez OpenClaw nie przeszedł sprawdzeń schematu lub nadpisania przed zatwierdzeniem.
• Config write rejected: → zapis próbował usunąć wymagany kształt, gwałtownie zmniejszyć plik albo utrwalić nieprawidłową konfigurację.
• config reload skipped (invalid config): → bezpośrednia edycja nie przeszła walidacji i została zignorowana przez działający Gateway.
• Invalid config at ... → uruchomienie nie powiodło się, zanim usługi Gateway zostały uruchomione.
• missing-meta-vs-last-good, gateway-mode-missing-vs-last-good lub size-drop-vs-last-good:* → zapis wykonywany przez OpenClaw został odrzucony, ponieważ utracił pola lub rozmiar względem ostatniej znanej dobrej kopii zapasowej.
• Config last-known-good promotion skipped → kandydat zawierał zredagowane symbole zastępcze sekretów, takie jak ***.

1. Uruchom openclaw doctor --fix, aby doctor naprawił konfigurację z prefiksem/nadpisaną albo przywrócił ostatnią znaną dobrą.
2. Skopiuj tylko zamierzone klucze z .clobbered.* lub .rejected.*, a następnie zastosuj je za pomocą openclaw config set albo config.patch.
3. Uruchom openclaw config validate przed restartem.
4. Jeśli edytujesz ręcznie, zachowaj pełną konfigurację JSON5, nie tylko częściowy obiekt, który chcesz zmienić.

• cron: scheduler disabled; jobs will not run automatically → Cron wyłączony.
• cron: timer tick failed → takt harmonogramu nie powiódł się; sprawdź błędy plików/logów/środowiska uruchomieniowego.
• heartbeat skipped z reason=quiet-hours → poza oknem aktywnych godzin.
• heartbeat skipped z reason=empty-heartbeat-file → HEARTBEAT.md istnieje, ale zawiera tylko puste wiersze / nagłówki markdown, więc OpenClaw pomija wywołanie modelu.
• heartbeat skipped z reason=no-tasks-due → HEARTBEAT.md zawiera blok tasks:, ale żadne zadania nie są wymagalne w tym takcie.
• heartbeat: unknown accountId → nieprawidłowy identyfikator konta dla celu dostarczenia Heartbeat.
• heartbeat skipped z reason=dm-blocked → cel Heartbeat został rozwiązany jako miejsce docelowe typu DM, gdy agents.defaults.heartbeat.directPolicy (lub nadpisanie dla agenta) jest ustawione na block.

• unknown command "browser" lub unknown command 'browser' → dołączony Plugin przeglądarki jest wykluczony przez plugins.allow.
• brakuje narzędzia przeglądarki / jest niedostępne, gdy browser.enabled=true → plugins.allow wyklucza browser, więc Plugin nigdy się nie załadował.
• Failed to start Chrome CDP on port → nie udało się uruchomić procesu przeglądarki.
• browser.executablePath not found → skonfigurowana ścieżka jest nieprawidłowa.
• browser.cdpUrl must be http(s) or ws(s) → skonfigurowany URL CDP używa nieobsługiwanego schematu, takiego jak file: lub ftp:.
• browser.cdpUrl has invalid port → skonfigurowany URL CDP ma nieprawidłowy port lub port spoza zakresu.
• Playwright is not available in this gateway build; '<feature>' is unsupported. → bieżąca instalacja Gateway nie ma głównej zależności środowiska uruchomieniowego przeglądarki; zainstaluj ponownie lub zaktualizuj OpenClaw, a potem uruchom ponownie Gateway. Migawki ARIA i podstawowe zrzuty ekranu stron nadal mogą działać, ale nawigacja, migawki AI, zrzuty ekranu elementów przez selektory CSS i eksport PDF pozostają niedostępne.

• Could not find DevToolsActivePort for chrome → istniejąca sesja Chrome MCP nie mogła jeszcze podłączyć się do wybranego katalogu danych przeglądarki. Otwórz stronę inspekcji przeglądarki, włącz zdalne debugowanie, pozostaw przeglądarkę otwartą, zatwierdź pierwszy monit podłączenia, a potem spróbuj ponownie. Jeśli stan zalogowania nie jest wymagany, preferuj zarządzany profil openclaw.
• No Chrome tabs found for profile="user" → profil podłączenia Chrome MCP nie ma otwartych lokalnych kart Chrome.
• Remote CDP for profile "<name>" is not reachable → skonfigurowany zdalny punkt końcowy CDP nie jest osiągalny z hosta Gateway.
• Browser attachOnly is enabled ... not reachable lub Browser attachOnly is enabled and CDP websocket ... is not reachable → profil tylko do podłączania nie ma osiągalnego celu albo punkt końcowy HTTP odpowiedział, ale WebSocket CDP nadal nie mógł zostać otwarty.

• fullPage is not supported for element screenshots → żądanie zrzutu ekranu połączyło --full-page z --ref lub --element.
• element screenshots are not supported for existing-session profiles; use ref from snapshot. → wywołania zrzutu ekranu Chrome MCP / existing-session muszą używać przechwytywania strony albo --ref z migawki, a nie CSS --element.
• existing-session file uploads do not support element selectors; use ref/inputRef. → haki przesyłania Chrome MCP potrzebują referencji z migawek, a nie selektorów CSS.
• existing-session file uploads currently support one file at a time. → wysyłaj jedno przesyłanie na wywołanie w profilach Chrome MCP.
• existing-session dialog handling does not support timeoutMs. → haki okien dialogowych w profilach Chrome MCP nie obsługują nadpisań limitu czasu.
• existing-session type does not support timeoutMs overrides. → pomiń timeoutMs dla act:type w profilach profile="user" / istniejącej sesji Chrome MCP albo użyj zarządzanego/CDP profilu przeglądarki, gdy wymagany jest niestandardowy limit czasu.
• existing-session evaluate does not support timeoutMs overrides. → pomiń timeoutMs dla act:evaluate w profilach profile="user" / istniejącej sesji Chrome MCP albo użyj zarządzanego/CDP profilu przeglądarki, gdy wymagany jest niestandardowy limit czasu.
• response body is not supported for existing-session profiles yet. → responsebody nadal wymaga zarządzanej przeglądarki albo surowego profilu CDP.
• nieaktualne nadpisania widoku / trybu ciemnego / ustawień regionalnych / offline w profilach tylko do podłączania lub zdalnych profilach CDP → uruchom openclaw browser stop --browser-profile <name>, aby zamknąć aktywną sesję sterowania i zwolnić stan emulacji Playwright/CDP bez restartowania całego Gateway.

openclaw gateway status
openclaw config get gateway.mode
openclaw config get gateway.remote.url
openclaw config get gateway.auth.mode

Co sprawdzić:

• Jeśli gateway.mode=remote, wywołania CLI mogą trafiać do zdalnego celu, mimo że lokalna usługa działa poprawnie.
• Jawne wywołania --url nie wracają awaryjnie do zapisanych poświadczeń.

Typowe sygnatury:

• gateway connect failed: → niewłaściwy docelowy URL.
• unauthorized → punkt końcowy osiągalny, ale uwierzytelnianie nieprawidłowe.

openclaw config get gateway.bind
openclaw config get gateway.auth.mode
openclaw config get gateway.auth.token
openclaw gateway status
openclaw logs --follow

Co sprawdzić:

• Powiązania inne niż loopback (lan, tailnet, custom) wymagają prawidłowej ścieżki uwierzytelniania Gateway: uwierzytelniania współdzielonym tokenem/hasłem albo poprawnie skonfigurowanego wdrożenia trusted-proxy poza loopback.
• Stare klucze, takie jak gateway.token, nie zastępują gateway.auth.token.

Typowe sygnatury:

• refusing to bind gateway ... without auth → powiązanie inne niż loopback bez prawidłowej ścieżki uwierzytelniania Gateway.
• Connectivity probe: failed, gdy środowisko uruchomieniowe działa → Gateway żyje, ale jest niedostępny przy bieżącym uwierzytelnianiu/URL.

openclaw devices list
openclaw pairing list --channel <channel> [--account <id>]
openclaw logs --follow
openclaw doctor

Co sprawdzić:

• Oczekujące zatwierdzenia urządzeń dla panelu/nodes.
• Oczekujące zatwierdzenia parowania DM po zmianach zasad lub tożsamości.

Typowe sygnatury:

• device identity required → uwierzytelnianie urządzenia nie jest spełnione.
• pairing required → nadawca/urządzenie musi zostać zatwierdzone.