​

Rozwiązywanie problemów z gateway

​

Drabina poleceń

openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe

• openclaw gateway status pokazuje Runtime: running i RPC probe: ok.
• openclaw doctor nie zgłasza blokujących problemów z konfiguracją ani usługami.
• openclaw channels status --probe pokazuje aktywny stan transportu dla każdego konta oraz, tam gdzie jest to obsługiwane, wyniki probe/audytu, takie jak works lub audit ok.

​

Anthropic 429: wymagane dodatkowe użycie dla długiego kontekstu

openclaw logs --follow
openclaw models status
openclaw config get agents.defaults.models

• Wybrany model Anthropic Opus/Sonnet ma params.context1m: true.
• Bieżące poświadczenie Anthropic nie kwalifikuje się do użycia długiego kontekstu.
• Żądania kończą się błędem tylko w długich sesjach/uruchomieniach modelu, które wymagają ścieżki beta 1M.

1. Wyłącz context1m dla tego modelu, aby wrócić do zwykłego okna kontekstu.
2. Użyj poświadczenia Anthropic, które kwalifikuje się do żądań długiego kontekstu, albo przełącz się na klucz API Anthropic.
3. Skonfiguruj modele zapasowe, aby uruchomienia były kontynuowane, gdy żądania Anthropic z długim kontekstem są odrzucane.

• /providers/anthropic
• /reference/token-use
• /help/faq#why-am-i-seeing-http-429-ratelimiterror-from-anthropic

​

Lokalny backend zgodny z OpenAI przechodzi bezpośrednie probe, ale uruchomienia agenta kończą się błędem

• curl ... /v1/models działa
• małe bezpośrednie wywołania /v1/chat/completions działają
• uruchomienia modeli OpenClaw kończą się błędem tylko podczas zwykłych tur agenta

curl http://127.0.0.1:1234/v1/models
curl http://127.0.0.1:1234/v1/chat/completions \
  -H 'content-type: application/json' \
  -d '{"model":"<id>","messages":[{"role":"user","content":"hi"}],"stream":false}'
openclaw infer model run --model <provider/model> --prompt "hi" --json
openclaw logs --follow

• małe bezpośrednie wywołania kończą się sukcesem, ale uruchomienia OpenClaw kończą się błędem tylko przy większych promptach
• błędów backendu o messages[].content, które oczekuje ciągu znaków
• awarii backendu, które pojawiają się tylko przy większej liczbie tokenów promptu lub pełnych promptach środowiska uruchomieniowego agenta

• 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.
• małe bezpośrednie żądania kończą się sukcesem, ale uruchomienia agenta OpenClaw kończą się błędami backendu/modelu (na przykład Gemma w niektórych buildach inferrs) → transport OpenClaw najprawdopodobniej jest już poprawny; backend nie radzi sobie z większym kształtem promptu środowiska uruchomieniowego agenta.
• błędy zmniejszają się po wyłączeniu narzędzi, ale nie znikają → schematy narzędzi były częścią obciążenia, ale pozostały problem nadal leży po stronie upstream modelu/serwera albo jest błędem backendu.

1. Ustaw compat.requiresStringContent: true dla backendów Chat Completions obsługujących wyłącznie treść tekstową.
2. Ustaw compat.supportsTools: false dla modeli/backendów, które nie potrafią niezawodnie obsłużyć powierzchni schematu narzędzi OpenClaw.
3. Tam, gdzie to możliwe, zmniejsz obciążenie promptu: mniejszy bootstrap workspace, krótsza historia sesji, lżejszy model lokalny albo backend z lepszym wsparciem dla długiego kontekstu.
4. Jeśli małe bezpośrednie żądania nadal przechodzą, a tury agenta OpenClaw wciąż powodują awarie w backendzie, potraktuj to jako ograniczenie upstream serwera/modelu i zgłoś tam reprodukcję z zaakceptowanym kształtem payloadu.

• /gateway/local-models
• /gateway/configuration
• /gateway/configuration-reference#openai-compatible-endpoints

​

Brak odpowiedzi

openclaw status
openclaw channels status --probe
openclaw pairing list --channel <channel> [--account <id>]
openclaw config get channels
openclaw logs --follow

• Oczekującego parowania dla nadawców wiadomości prywatnych.
• Wymogu wzmianki w grupie (requireMention, mentionPatterns).
• Niezgodności listy dozwolonych kanałów/grup.

• drop guild message (mention required → wiadomość grupowa została zignorowana do momentu wzmianki.
• pairing request → nadawca wymaga zatwierdzenia.
• blocked / allowlist → nadawca/kanał został odfiltrowany przez politykę.

• /channels/troubleshooting
• /channels/pairing
• /channels/groups

​

Łączność dashboard/control UI

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

• Poprawnego probe URL i dashboard URL.
• Niezgodności trybu/tokena uwierzytelniania między klientem a gateway.
• Użycia HTTP tam, gdzie wymagana jest tożsamość urządzenia.

• device identity required → niezabezpieczony kontekst lub brak uwierzytelniania urządzenia.
• origin not allowed → przeglądarkowe Origin nie znajduje się w gateway.controlUi.allowedOrigins (albo łączysz się z pochodzenia przeglądarki innego niż 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ł nieprawidłowy payload (albo użył nieaktualnego znacznika czasu) dla bieżącego handshake.
• AUTH_TOKEN_MISMATCH z canRetryWithDeviceToken=true → klient może wykonać jedną zaufaną ponowną próbę z użyciem buforowanego tokena urządzenia.
• Ta ponowna próba z buforowanym tokenem używa ponownie zestawu zakresów przechowywanego wraz z tokenem sparowanego urządzenia. Wywołania z jawnym deviceToken / jawnymi scopes zachowują swój żądany zestaw zakresów.
• Poza tą ścieżką ponownej próby pierwszeństwo uwierzytelniania połączenia jest następujące: najpierw jawny współdzielony token/hasło, potem jawny deviceToken, potem zapisany token urządzenia, a na końcu token bootstrap.
• W asynchronicznej ścieżce Tailscale Serve Control UI nieudane próby dla tego samego {scope, ip} są serializowane, zanim limiter zapisze niepowodzenie. Dwie błędne równoległe ponowne próby od tego samego klienta mogą więc spowodować retry later przy drugiej próbie zamiast dwóch zwykłych niezgodności.
• too many failed authentication attempts (retry later) z klienta loopback o pochodzeniu przeglądarkowym → powtarzające się niepowodzenia z tego samego znormalizowanego Origin są tymczasowo blokowane; inne pochodzenie localhost używa osobnego kubełka.
• powtarzające się unauthorized po tej ponownej próbie → rozjazd współdzielonego tokena/tokena urządzenia; odśwież konfigurację tokena i w razie potrzeby ponownie zatwierdź/obróć token urządzenia.
• gateway connect failed: → nieprawidłowy host/port/docelowy URL.

​

Krótka mapa kodów szczegółów uwierzytelniania

openclaw --version
openclaw doctor
openclaw gateway status

1. czeka na connect.challenge
2. podpisuje payload powiązany z wyzwaniem
3. wysyła connect.params.device.nonce z tym samym nonce wyzwania

• sesje tokenów sparowanych urządzeń mogą zarządzać tylko własnym urządzeniem, chyba że wywołujący ma również operator.admin
• openclaw devices rotate --scope ... może żądać tylko takich zakresów operatora, które sesja wywołująca już posiada

• /web/control-ui
• /gateway/configuration (tryby gateway auth)
• /gateway/trusted-proxy-auth
• /gateway/remote
• /cli/devices

​

Usługa gateway nie działa

openclaw gateway status
openclaw status
openclaw logs --follow
openclaw doctor
openclaw gateway status --deep   # skanuje też usługi na poziomie systemu

• Runtime: stopped z podpowiedziami dotyczącymi zakończenia.
• Niezgodności konfiguracji usługi (Config (cli) vs Config (service)).
• Konfliktów portów/listenerów.
• Dodatkowych instalacji launchd/systemd/schtasks przy użyciu --deep.
• Podpowiedzi czyszczenia Other gateway-like services detected (best effort).

• Gateway start blocked: set gateway.mode=local lub existing config is missing gateway.mode → lokalny tryb gateway nie jest włączony albo plik konfiguracyjny został nadpisany i utracił gateway.mode. Naprawa: ustaw gateway.mode="local" w konfiguracji albo ponownie uruchom openclaw onboard --mode local / openclaw setup, aby ponownie zapisać oczekiwaną konfigurację trybu lokalnego. Jeśli uruchamiasz OpenClaw przez Podman, domyślną ścieżką konfiguracji jest ~/.openclaw/openclaw.json.
• refusing to bind gateway ... without auth → powiązanie inne niż loopback bez prawidłowej ścieżki gateway auth (token/hasło albo trusted-proxy, jeśli skonfigurowano).
• another gateway instance is already listening / EADDRINUSE → konflikt portu.
• Other gateway-like services detected (best effort) → istnieją przestarzałe lub równoległe jednostki launchd/systemd/schtasks. W większości konfiguracji należy utrzymywać jeden gateway na maszynę; jeśli rzeczywiście potrzebujesz więcej niż jednego, odizoluj porty oraz config/state/workspace. Zobacz /gateway#multiple-gateways-same-host.

• /gateway/background-process
• /gateway/configuration
• /gateway/doctor

​

Ostrzeżenia probe gateway

openclaw gateway probe
openclaw gateway probe --json
openclaw gateway probe --ssh user@gateway-host

• warnings[].code i primaryTargetId w wyjściu JSON.
• Czy ostrzeżenie dotyczy fallbacku SSH, wielu gateway, brakujących zakresów czy nierozwiązanych odwołań auth.

• SSH tunnel failed to start; falling back to direct probes. → konfiguracja SSH nie powiodła się, ale polecenie nadal próbowało bezpośrednich skonfigurowanych/celów loopback.
• multiple reachable gateways detected → odpowiedział więcej niż jeden cel. Zwykle oznacza to zamierzoną konfigurację wielogatewayową albo nieaktualne/zduplikowane listenery.
• Probe diagnostics are limited by gateway scopes (missing operator.read) → połączenie zadziałało, ale szczegółowe RPC jest ograniczone zakresem; sparuj tożsamość urządzenia albo użyj poświadczeń z operator.read.
• nierozwiązany tekst ostrzeżenia gateway.auth.* / gateway.remote.* SecretRef → materiał uwierzytelniający nie był dostępny w tej ścieżce polecenia dla nieudanego celu.

• /cli/gateway
• /gateway#multiple-gateways-same-host
• /gateway/remote

​

Kanał połączony, ale wiadomości nie przepływają

openclaw channels status --probe
openclaw pairing list --channel <channel> [--account <id>]
openclaw status --deep
openclaw logs --follow
openclaw config get channels

• Polityki DM (pairing, allowlist, open, disabled).
• Listy dozwolonych grup i wymagań wzmianki.
• Brakujących uprawnień/zakresów API kanału.

• mention required → wiadomość została zignorowana przez politykę wzmianki w grupie.
• ślady pairing / oczekującego zatwierdzenia → nadawca nie został zatwierdzony.
• missing_scope, not_in_channel, Forbidden, 401/403 → problem z uwierzytelnianiem/uprawnieniami kanału.

• /channels/troubleshooting
• /channels/whatsapp
• /channels/telegram
• /channels/discord

​

Dostarczanie cron i heartbeat

openclaw cron status
openclaw cron list
openclaw cron runs --id <jobId> --limit 20
openclaw system heartbeat last
openclaw logs --follow

• Włączonego cron i obecnego następnego wybudzenia.
• Stanu historii uruchomień zadania (ok, skipped, error).
• Powodów pominięcia heartbeat (quiet-hours, requests-in-flight, alerts-disabled, empty-heartbeat-file, no-tasks-due).

• cron: scheduler disabled; jobs will not run automatically → cron jest wyłączony.
• cron: timer tick failed → tick harmonogramu zakończył się błędem; sprawdź błędy plików/logów/runtime.
• heartbeat skipped z reason=quiet-hours → poza oknem aktywnych godzin.
• heartbeat skipped z reason=empty-heartbeat-file → HEARTBEAT.md istnieje, ale zawiera tylko puste linie / 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ą zaplanowane na ten tick.
• heartbeat: unknown accountId → nieprawidłowy account id dla celu dostarczania heartbeat.
• heartbeat skipped z reason=dm-blocked → cel heartbeat został rozwiązany jako miejsce docelowe w stylu DM, podczas gdy agents.defaults.heartbeat.directPolicy (lub nadpisanie dla konkretnego agenta) ma wartość block.

• /automation/cron-jobs#troubleshooting
• /automation/cron-jobs
• /gateway/heartbeat

​

Sparowane narzędzie węzła kończy się błędem

openclaw nodes status
openclaw nodes describe --node <idOrNameOrIp>
openclaw approvals get --node <idOrNameOrIp>
openclaw logs --follow
openclaw status

• Węzła online z oczekiwanymi możliwościami.
• Przyznanych przez system operacyjny uprawnień do kamery/mikrofonu/lokalizacji/ekranu.
• Stanu zatwierdzeń exec i listy dozwolonych.

• NODE_BACKGROUND_UNAVAILABLE → aplikacja węzła musi być na pierwszym planie.
• *_PERMISSION_REQUIRED / LOCATION_PERMISSION_REQUIRED → brakuje uprawnienia systemowego.
• SYSTEM_RUN_DENIED: approval required → oczekuje zatwierdzenie exec.
• SYSTEM_RUN_DENIED: allowlist miss → polecenie zablokowane przez listę dozwolonych.

• /nodes/troubleshooting
• /nodes/index
• /tools/exec-approvals

​

Narzędzie przeglądarki kończy się błędem

openclaw browser status
openclaw browser start --browser-profile openclaw
openclaw browser profiles
openclaw logs --follow
openclaw doctor

• Czy plugins.allow jest ustawione i zawiera browser.
• Prawidłowej ścieżki do pliku wykonywalnego przeglądarki.
• Osiągalności profilu CDP.
• Dostępności lokalnego Chrome dla profili existing-session / user.

• unknown command "browser" lub unknown command 'browser' → wbudowany plugin przeglądarki jest wykluczony przez plugins.allow.
• brak / niedostępność narzędzia przeglądarki przy browser.enabled=true → plugins.allow wyklucza browser, więc plugin nigdy się nie załadował.
• Failed to start Chrome CDP on port → proces przeglądarki nie uruchomił się.
• 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.
• 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 endpoint 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łączenia nie ma osiągalnego celu albo endpoint HTTP odpowiedział, ale nadal nie udało się otworzyć WebSocket CDP.
• Playwright is not available in this gateway build; '<feature>' is unsupported. → bieżąca instalacja gateway nie zawiera pełnego pakietu Playwright; migawki ARIA i podstawowe zrzuty ekranu strony nadal mogą działać, ale nawigacja, migawki AI, zrzuty ekranu elementów według selektorów CSS i eksport PDF pozostają niedostępne.
• fullPage is not supported for element screenshots → żądanie zrzutu ekranu łączy --full-page z --ref lub --element.
• element screenshots are not supported for existing-session profiles; use ref from snapshot. → wywołania zrzutów ekranu Chrome MCP / existing-session muszą używać przechwycenia strony albo --ref z migawki, a nie CSS --element.
• existing-session file uploads do not support element selectors; use ref/inputRef. → hooki przesyłania plików Chrome MCP wymagają odwołań do migawki, a nie selektorów CSS.
• existing-session file uploads currently support one file at a time. → dla profili Chrome MCP wysyłaj jeden upload na wywołanie.
• existing-session dialog handling does not support timeoutMs. → hooki dialogów w profilach Chrome MCP nie obsługują nadpisania timeout.
• response body is not supported for existing-session profiles yet. → responsebody nadal wymaga zarządzanej przeglądarki albo surowego profilu CDP.
• nieaktualne nadpisania viewport / dark-mode / locale / offline w profilach tylko-dołączenia lub zdalnych CDP → uruchom openclaw browser stop --browser-profile <name>, aby zamknąć aktywną sesję sterowania i zwolnić stan emulacji Playwright/CDP bez restartowania całego gateway.

• /tools/browser-linux-troubleshooting
• /tools/browser

​

Jeśli po aktualizacji coś nagle przestało działać

​

1) Zmieniło się zachowanie auth i nadpisywania URL

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

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

• gateway connect failed: → nieprawidłowy docelowy URL.
• unauthorized → endpoint jest osiągalny, ale auth jest nieprawidłowe.

​

2) Reguły bind i auth są bardziej rygorystyczne

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

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

• refusing to bind gateway ... without auth → powiązanie inne niż loopback bez prawidłowej ścieżki gateway auth.
• RPC probe: failed przy działającym runtime → gateway działa, ale jest niedostępny przy bieżącym auth/url.

​

3) Zmienił się stan parowania i tożsamości urządzenia

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

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

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

openclaw gateway install --force
openclaw gateway restart

• /gateway/pairing
• /gateway/authentication
• /gateway/background-process