​

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 oraz RPC probe: ok.
• openclaw doctor nie zgłasza blokujących problemów z konfiguracją/usługą.
• openclaw channels status --probe pokazuje aktywny stan transportu dla poszczególnych kont oraz, tam gdzie to obsługiwane, wyniki probe/audytu, takie jak works lub audit ok.

​

Anthropic 429 extra usage required for long context

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 normalnego okna kontekstu.
2. Użyj klucza API Anthropic z rozliczaniem albo włącz Anthropic Extra Usage na koncie OAuth/subskrypcji 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

​

Brak odpowiedzi

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

• Oczekujące parowanie dla nadawców DM.
• Bramka wzmianek w grupach (requireMention, mentionPatterns).
• Niedopasowania list dozwolonych kanału/grupy.

• drop guild message (mention required → wiadomość grupowa jest ignorowana do czasu 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

• Poprawny probe URL i URL dashboardu.
• Niedopasowanie trybu uwierzytelniania/tokenu między klientem a gateway.
• Użycie HTTP tam, gdzie wymagana jest tożsamość urządzenia.

• device identity required → niezabezpieczony kontekst lub brak uwierzytelnienia urządzenia.
• origin not allowed → Origin przeglądarki nie znajduje się w gateway.controlUi.allowedOrigins (albo łączysz się z origin przeglądarki spoza 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 ładunek (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 buforowanym tokenem urządzenia.
• Ta ponowna próba z użyciem buforowanego tokenu wykorzystuje ponownie zestaw zakresów zapisany z zatwierdzonym tokenem urządzenia. Wywołujący z jawnym deviceToken / jawnymi scopes zachowują żądany zestaw zakresów.
• Poza tą ścieżką ponownej próby pierwszeństwo uwierzytelniania przy połączeniu jest następujące: jawny współdzielony token/hasło, potem jawny deviceToken, potem zapisany token urządzenia, potem token bootstrap.
• Na asynchronicznej ścieżce Tailscale Serve Control UI nieudane próby dla tego samego {scope, ip} są serializowane, zanim limiter zarejestruje błąd. Dwie błędne równoczesne ponowne próby od tego samego klienta mogą więc spowodować retry later przy drugiej próbie zamiast dwóch zwykłych niedopasowań.
• too many failed authentication attempts (retry later) od klienta loopback pochodzącego z origin przeglądarki → powtarzane nieudane próby z tego samego znormalizowanego Origin są tymczasowo blokowane; inny localhost origin używa osobnego bucket.
• powtarzające się unauthorized po tej ponownej próbie → rozjechanie współdzielonego tokenu/tokenu urządzenia; odśwież konfigurację tokenu i ponownie zatwierdź/obróć token urządzenia, jeśli potrzeba.
• gateway connect failed: → zły cel hosta/portu/URL.

​

Szybka mapa kodów szczegółów auth

openclaw --version
openclaw doctor
openclaw gateway status

1. czeka na connect.challenge
2. podpisuje ładunek 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 także 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 uwierzytelniania gateway)
• /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   # skanuj też usługi na poziomie systemu

• Runtime: stopped ze wskazówkami dotyczącymi wyjścia.
• Niedopasowanie konfiguracji usługi (Config (cli) vs Config (service)).
• Konflikty portów/listenerów.
• Dodatkowe instalacje launchd/systemd/schtasks przy użyciu --deep.
• Wskazówki 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 konfiguracji 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 spoza loopback bez prawidłowej ścieżki uwierzytelniania gateway (token/hasło albo trusted-proxy tam, gdzie skonfigurowano).
• another gateway instance is already listening / EADDRINUSE → konflikt portów.
• Other gateway-like services detected (best effort) → istnieją nieaktualne lub równoległe jednostki launchd/systemd/schtasks. W większości konfiguracji powinna działać jedna gateway na maszynę; jeśli rzeczywiście potrzebujesz więcej niż jednej, odizoluj porty + 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 danych wyjściowych JSON.
• Czy ostrzeżenie dotyczy awaryjnego przejścia na SSH, wielu gateway, brakujących zakresów czy nierozwiązanych auth ref.

• SSH tunnel failed to start; falling back to direct probes. → konfiguracja SSH się nie powiodła, 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 celową konfigurację wielu gateway albo nieaktualne/zduplikowane listenery.
• Probe diagnostics are limited by gateway scopes (missing operator.read) → połączenie się udało, ale szczegółowe RPC ma ograniczony zakres; 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 był niedostępny na 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

• Politykę DM (pairing, allowlist, open, disabled).
• Listę dozwolonych grup i wymagania dotyczące wzmianek.
• Brakujące uprawnienia/zakresy API kanału.

• mention required → wiadomość ignorowana przez politykę wymuszającą wzmiankę w grupie.
• pairing / ślady oczekującego zatwierdzenia → nadawca nie jest 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

• Czy cron jest włączony i czy istnieje następne wybudzenie.
• Status historii uruchomień zadania (ok, skipped, error).
• Powody 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 → błąd tyknięcia harmonogramu; 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 zadanie nie jest należne przy tym tyknięciu.
• heartbeat: unknown accountId → nieprawidłowy account id dla celu dostarczania heartbeat.
• heartbeat skipped z reason=dm-blocked → cel heartbeat został rozwiązany do miejsca docelowego w stylu DM, podczas gdy agents.defaults.heartbeat.directPolicy (lub nadpisanie per agent) jest ustawione na block.

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

​

Narzędzie sparowanego 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

• Czy węzeł jest online i ma oczekiwane możliwości.
• Przyznane przez system operacyjny uprawnienia do kamery/mikrofonu/lokalizacji/ekranu.
• Stan zatwierdzeń exec i listy dozwolonych.

• NODE_BACKGROUND_UNAVAILABLE → aplikacja węzła musi być na pierwszym planie.
• *_PERMISSION_REQUIRED / LOCATION_PERMISSION_REQUIRED → brak uprawnienia systemowego.
• SYSTEM_RUN_DENIED: approval required → oczekujące 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łową ścieżkę do pliku wykonywalnego przeglądarki.
• Osiągalność profilu CDP.
• Dostępność lokalnego Chrome dla profili existing-session / user.

• unknown command "browser" lub unknown command 'browser' → bundlowany plugin przeglądarki jest wykluczony przez plugins.allow.
• brak/nieobecność 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 lub wykraczający poza zakres port.
• No Chrome tabs found for profile="user" → profil dołą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łączenie nie ma osiągalnego celu albo endpoint HTTP odpowiedział, ale nadal nie udało się otworzyć WebSocketu CDP.
• Playwright is not available in this gateway build; '<feature>' is unsupported. → bieżąca instalacja gateway nie zawiera pełnego pakietu Playwright; snapshoty ARIA i podstawowe zrzuty ekranu stron mogą nadal działać, ale nawigacja, snapshoty AI, zrzuty elementów według selektorów CSS i eksport PDF pozostają niedostępne.
• 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 zrzutów ekranu Chrome MCP / existing-session muszą używać przechwycenia strony albo --ref ze snapshotu, a nie CSS --element.
• existing-session file uploads do not support element selectors; use ref/inputRef. → hooki przesyłania plików Chrome MCP wymagają ref ze snapshotu, a nie selektorów CSS.
• existing-session file uploads currently support one file at a time. → wysyłaj jeden upload na wywołanie w profilach Chrome MCP.
• existing-session dialog handling does not support timeoutMs. → hooki dialogów w profilach Chrome MCP nie obsługują nadpisań 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łączenie 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łej gateway.

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

​

Jeśli po aktualizacji coś nagle się zepsuło

​

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ą trafiać do zdalnego celu, podczas gdy lokalna usługa działa poprawnie.
• Jawne wywołania --url nie wracają do zapisanych poświadczeń.

• gateway connect failed: → zły URL docelowy.
• unauthorized → endpoint jest osiągalny, ale uwierzytelnienie jest błędne.

​

2) Guardrails dla 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 spoza loopback (lan, tailnet, custom) wymagają prawidłowej ścieżki uwierzytelniania gateway: współdzielonego uwierzytelniania tokenem/hasłem albo poprawnie skonfigurowanego wdrożenia trusted-proxy spoza loopback.
• Starsze klucze, takie jak gateway.token, nie zastępują gateway.auth.token.

• refusing to bind gateway ... without auth → powiązanie spoza loopback bez prawidłowej ścieżki auth gateway.
• RPC probe: failed przy działającym runtime → gateway działa, ale jest niedostępna 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 dashboardu/węzłów.
• 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