Rozwiązywanie problemów

To jest szczegółowy podręcznik operacyjny. Najpierw zacznij od /help/troubleshooting, aby przeprowadzić szybką diagnostykę.

Sekwencja poleceń

Uruchom w następującej kolejności:

openclaw statusopenclaw gateway statusopenclaw logs --followopenclaw doctoropenclaw channels status --probe

Sygnały prawidłowego działania:

• openclaw gateway status pokazuje Runtime: running, Connectivity probe: ok oraz wiersz Capability: ....
• openclaw doctor nie zgłasza żadnych blokujących problemów z konfiguracją ani usługą.
• openclaw channels status --probe pokazuje bieżący stan transportu dla poszczególnych kont oraz, jeśli jest to obsługiwane, works lub audit ok.

Po aktualizacji

Użyj, gdy aktualizacja została ukończona, ale Gateway nie działa, kanały są puste lub wywołania modeli kończą się błędami 401.

openclaw status --allopenclaw update status --jsonopenclaw gateway status --deepopenclaw doctor --fixopenclaw gateway restart

Sprawdź:

• Update restart w openclaw status / openclaw status --all. Oczekujące lub nieudane przekazania zawierają następne polecenie do uruchomienia.
• plugin load failed: dependency tree corrupted; run openclaw doctor --fix w sekcji Kanały: konfiguracja kanału nadal istnieje, ale rejestracja pluginu nie powiodła się przed załadowaniem kanału.
• Błędy 401 dostawcy po ponownym uwierzytelnieniu: openclaw doctor --fix sprawdza nieaktualne kopie uwierzytelniania OAuth poszczególnych agentów i usuwa stare kopie, aby wszyscy agenci korzystali z bieżącego profilu współdzielonego.

Rozbieżne instalacje i zabezpieczenie przed nowszą konfiguracją

Użyj, gdy usługa Gateway nieoczekiwanie zatrzymuje się po aktualizacji lub dzienniki wskazują, że jeden plik binarny openclaw jest starszy niż wersja, która ostatnio zapisała openclaw.json.

OpenClaw oznacza zapisy konfiguracji za pomocą meta.lastTouchedVersion. Polecenia tylko do odczytu mogą sprawdzać konfigurację zapisaną przez nowszą wersję OpenClaw, ale operacje modyfikujące procesy i usługi nie mogą być wykonywane przez starszy plik binarny. Zablokowane działania: uruchamianie, zatrzymywanie, ponowne uruchamianie i odinstalowywanie usługi Gateway, wymuszona ponowna instalacja usługi, uruchamianie Gateway w trybie usługi oraz czyszczenie portu gateway --force.

which openclawopenclaw --versionopenclaw gateway status --deepopenclaw config get meta.lastTouchedVersion

openclaw gateway install --forceopenclaw gateway restart

Niezgodność protokołu po wycofaniu wersji

Użyj, gdy po obniżeniu lub wycofaniu wersji dzienniki nadal wyświetlają protocol mismatch. Działa starszy Gateway, ale nowszy lokalny proces klienta nadal ponownie się łączy, używając zakresu protokołu, którego starszy Gateway nie obsługuje.

openclaw --versionwhich -a openclawopenclaw gateway status --deepopenclaw doctor --deepopenclaw logs --follow

Sprawdź:

• protocol mismatch ... client=... v<version> min=<n> max=<n> expected=<n> w dziennikach Gateway.
• Established clients: w openclaw gateway status --deep lub Gateway clients w openclaw doctor --deep: aktywni klienci TCP połączeni z portem Gateway, wraz z identyfikatorami PID i wierszami poleceń, jeśli system operacyjny na to pozwala.
• Proces klienta, którego wiersz polecenia wskazuje nowszą instalację OpenClaw lub skrypt opakowujący sprzed wycofania wersji.

Rozwiązanie:

1. Zatrzymaj lub ponownie uruchom nieaktualny proces klienta OpenClaw wskazany przez gateway status --deep.
2. Ponownie uruchom aplikacje lub skrypty opakowujące zawierające OpenClaw: lokalne pulpity, edytory, narzędzia pomocnicze serwera aplikacji lub długotrwale działające powłoki openclaw logs --follow.
3. Ponownie uruchom openclaw gateway status --deep lub openclaw doctor --deep i potwierdź, że identyfikator PID nieaktualnego klienta zniknął.

Nie konfiguruj starszego Gateway tak, aby akceptował nowszy, niezgodny protokół. Zmiany wersji protokołu chronią kontrakt komunikacyjny; odzyskiwanie po wycofaniu wersji wymaga uporządkowania procesów i wersji.

Pominięto dowiązanie symboliczne umiejętności jako wyjście poza ścieżkę

Użyj, gdy dzienniki zawierają:

Pomijanie ścieżki umiejętności wychodzącej poza skonfigurowany katalog główny: ... reason=symlink-escape

Każdy katalog główny umiejętności stanowi granicę zawierania. Dowiązanie symboliczne w ~/.agents/skills, <workspace>/.agents/skills, <workspace>/skills lub ~/.openclaw/skills jest pomijane, gdy jego rzeczywisty cel znajduje się poza tym katalogiem głównym, chyba że cel został jawnie oznaczony jako zaufany.

Sprawdź dowiązanie:

ls -l ~/.agents/skills/<name>realpath ~/.agents/skills/<name>openclaw config get skills.load

Jeśli cel jest zamierzony, skonfiguruj zarówno bezpośredni katalog główny umiejętności, jak i dozwolony cel dowiązania symbolicznego:

{  skills: {    load: {      extraDirs: ["~/Projects/manager/skills"],      allowSymlinkTargets: ["~/Projects/manager/skills"],    },  },}

Następnie rozpocznij nową sesję lub zaczekaj na odświeżenie przez mechanizm monitorujący umiejętności. Uruchom Gateway ponownie, jeśli działający proces został uruchomiony przed zmianą konfiguracji.

Nie używaj szerokich celów, takich jak ~, / ani cały synchronizowany folder projektu. Ogranicz allowSymlinkTargets do rzeczywistego katalogu głównego umiejętności zawierającego zaufane katalogi SKILL.md.

Jeśli zastosowanie zmian z warsztatu umiejętności ma również zapisywać dane za pośrednictwem tych zaufanych, dowiązanych symbolicznie ścieżek umiejętności obszaru roboczego, włącz skills.workshop.allowSymlinkTargetWrites. Pozostaw tę opcję wyłączoną dla współdzielonych katalogów głównych umiejętności przeznaczonych tylko do odczytu.

Powiązane:

• Konfiguracja Skills
• Przykłady konfiguracji

Błąd Anthropic 429 wymagający dodatkowego użycia dla długiego kontekstu

Użyj, gdy dzienniki lub błędy zawierają: HTTP 429: rate_limit_error: Extra usage is required for long context requests.

openclaw logs --followopenclaw models statusopenclaw config get agents.defaults.models

Sprawdź:

• Wybrany model Anthropic to model Claude 4.x w ogólnej dostępności, obsługujący kontekst 1M (Opus 4.6/4.7/4.8, Sonnet 4.6), albo konfiguracja modelu nadal zawiera starsze params.context1m: true.
• Bieżące dane uwierzytelniające Anthropic nie uprawniają do używania długiego kontekstu.
• Żądania kończą się niepowodzeniem tylko podczas długich sesji lub uruchomień modeli wymagających ścieżki kontekstu 1M.

Możliwe rozwiązania:

Powiązane:

• Anthropic
• Użycie tokenów i koszty
• Dlaczego widzę błąd HTTP 429 od Anthropic?

Odpowiedzi 403 blokowane przez usługę nadrzędną

Użyj, gdy nadrzędny dostawca LLM zwraca ogólny błąd 403, taki jak Your request was blocked.

Nie zakładaj, że zawsze jest to problem z konfiguracją OpenClaw. Odpowiedź może pochodzić z nadrzędnej warstwy zabezpieczeń, takiej jak CDN, WAF, reguła zarządzania botami lub odwrotne proxy przed punktem końcowym zgodnym z OpenAI.

openclaw statusopenclaw gateway statusopenclaw logs --follow

Sprawdź:

• Wiele modeli tego samego dostawcy kończy się niepowodzeniem w taki sam sposób.
• Tekst HTML lub ogólny komunikat zabezpieczeń zamiast zwykłego błędu API dostawcy.
• Zdarzenia zabezpieczeń po stronie dostawcy z czasu tego samego żądania.
• Powodzenie niewielkiego bezpośredniego testu curl, podczas gdy zwykłe żądania o strukturze SDK kończą się niepowodzeniem.

Jeśli dowody wskazują na blokadę WAF/CDN, najpierw popraw filtrowanie po stronie dostawcy. Preferuj precyzyjnie ograniczoną regułę zezwalającą lub pomijającą dla ścieżki API używanej przez OpenClaw i unikaj wyłączania ochrony całej witryny.

Powiązane:

• Punkty końcowe zgodne z OpenAI
• Konfiguracja dostawcy
• Dzienniki

Lokalny backend zgodny z OpenAI przechodzi testy bezpośrednie, ale uruchomienia agenta kończą się niepowodzeniem

Użyj, gdy:

• curl ... /v1/models działa.
• Niewielkie bezpośrednie wywołania /v1/chat/completions działają.
• Uruchomienia modeli OpenClaw kończą się niepowodzeniem tylko podczas zwykłych tur agenta.

curl http://127.0.0.1:1234/v1/modelscurl 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" --jsonopenclaw logs --follow

Sprawdź:

• Niewielkie wywołania bezpośrednie kończą się powodzeniem, ale uruchomienia OpenClaw zawodzą tylko przy większych promptach.
• Błędy model_not_found lub 404, mimo że bezpośrednie /v1/chat/completions działa z tym samym identyfikatorem modelu bez prefiksu.
• Błędy backendu informujące, że messages[].content oczekuje ciągu znaków.
• Sporadyczne ostrzeżenia incomplete turn detected ... stopReason=stop payloads=0 z lokalnym backendem zgodnym z OpenAI.
• Awarie backendu występujące tylko przy większej liczbie tokenów promptu lub pełnych promptach środowiska wykonawczego agenta.

Powiązane:

• Konfiguracja
• Modele lokalne
• Punkty końcowe zgodne z OpenAI

Brak odpowiedzi

Jeśli kanały działają, ale nic nie odpowiada, przed ponownym łączeniem czegokolwiek należy sprawdzić routing i zasady.

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

Należy sprawdzić:

• Oczekujące parowanie nadawców wiadomości bezpośrednich.
• Ograniczenie odpowiedzi w grupie do wzmianek (requireMention, mentionPatterns).
• Niezgodności list dozwolonych kanałów/grup.

Typowe sygnatury:

• drop guild message (mention required → wiadomość grupowa jest ignorowana do czasu wzmianki.
• pairing request → nadawca wymaga zatwierdzenia.
• blocked / allowlist → nadawca/kanał został odfiltrowany przez zasady.

Powiązane:

• Rozwiązywanie problemów z kanałami
• Grupy
• Parowanie

Łączność interfejsu sterowania panelu

Jeśli panel/interfejs sterowania nie może się połączyć, należy zweryfikować adres URL, tryb uwierzytelniania i założenia dotyczące bezpiecznego kontekstu.

openclaw gateway statusopenclaw statusopenclaw logs --followopenclaw doctoropenclaw gateway status --json

Należy sprawdzić:

• Poprawny adres URL sondy i adres URL panelu.
• Niezgodność trybu uwierzytelniania/tokena między klientem a gatewayem.
• Użycie protokołu HTTP tam, gdzie wymagana jest tożsamość urządzenia.

Jeśli po aktualizacji lokalna przeglądarka nie może połączyć się z 127.0.0.1:18789, najpierw należy przywrócić lokalną usługę Gateway i potwierdzić, że udostępnia panel:

openclaw gateway restartlsof -i :18789curl http://127.0.0.1:18789

Jeśli curl zwraca kod HTML OpenClaw, Gateway działa, a pozostały problem prawdopodobnie dotyczy pamięci podręcznej przeglądarki, starego łącza bezpośredniego lub nieaktualnego stanu karty. Należy otworzyć bezpośrednio http://127.0.0.1:18789 i przejść dalej z panelu. Jeśli po ponownym uruchomieniu usługa nie pozostaje uruchomiona, należy wykonać openclaw gateway start i ponownie sprawdzić openclaw gateway status.

Skrócona mapa kodów szczegółów uwierzytelniania

Aby wybrać następną czynność, należy użyć error.details.code z nieudanej odpowiedzi connect:

Kontrola migracji uwierzytelniania urządzeń v2:

openclaw --versionopenclaw doctoropenclaw gateway status

Jeśli dzienniki zawierają błędy wartości jednorazowej/podpisu, należy zaktualizować łączącego się klienta i zweryfikować go:

Jeśli openclaw devices rotate / revoke / remove zostanie nieoczekiwanie odrzucone:

• Sesje z tokenem sparowanego urządzenia 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 tych zakresów operatora, które już posiada sesja wywołującego.

Powiązane:

• Konfiguracja (tryby uwierzytelniania gatewaya)
• Interfejs sterowania
• Urządzenia
• Dostęp zdalny
• Uwierzytelnianie zaufanego serwera proxy

Usługa Gateway nie jest uruchomiona

Należy użyć, gdy usługa jest zainstalowana, ale proces nie pozostaje uruchomiony.

openclaw gateway statusopenclaw statusopenclaw logs --followopenclaw doctoropenclaw gateway status --deep   # skanuje również usługi na poziomie systemu

Należy sprawdzić:

• Runtime: stopped ze wskazówkami dotyczącymi zakończenia.
• Niezgodność konfiguracji usługi (Config (cli) a Config (service)).
• Konflikty portów/procesów nasłuchujących.
• Dodatkowe instalacje launchd/systemd/schtasks w przypadku użycia --deep.
• Wskazówki dotyczące czyszczenia Other gateway-like services detected (best effort).

Powiązane:

• Wykonywanie w tle i narzędzie procesów
• Konfiguracja
• Doctor

Gateway w systemie macOS po cichu przestaje odpowiadać, a następnie wznawia działanie po użyciu panelu

Użyj tego rozwiązania, gdy kanały (Telegram, WhatsApp itp.) na hoście macOS przestają odpowiadać na okres od kilku minut do kilku godzin, a Gateway zdaje się wracać do działania w chwili otwarcia interfejsu Control UI, połączenia przez SSH lub innej interakcji z hostem. Zwykle nie ma żadnego oczywistego objawu w openclaw status, ponieważ zanim zostanie to sprawdzone, Gateway znów działa.

ls ~/.openclaw/logs/stability/ | tail -5openclaw gateway stability --bundle latestpmset -g log | grep -iE "sleep|wake|maintenance" | tail -50launchctl print gui/$UID/ai.openclaw.gateway | grep -E "state|last exit|runs"

Należy szukać:

• Co najmniej jednego pakietu *-uncaught_exception.json w ~/.openclaw/logs/stability/, w którym error.code ustawiono na przejściowy kod sieciowy, taki jak ENETDOWN, ENETUNREACH, EHOSTUNREACH lub ECONNREFUSED.
• Wierszy pmset -g log, takich jak Entering Sleep state due to 'Maintenance Sleep' lub en0 driver is slow (msg: WillChangeState to 0), zbieżnych czasowo ze znacznikami awarii. Power Nap / Maintenance Sleep na krótko przełącza sterownik Wi-Fi w stan 0; każde wychodzące connect(), które trafi w to okno, może zakończyć się błędem ENETDOWN nawet na hoście, który poza tym ma pełną łączność sieciową.
• Danych wyjściowych launchctl print wskazujących state = not running z wieloma niedawnymi runs i kodem wyjścia, szczególnie gdy przerwa między awarią a następnym uruchomieniem wynosi około godziny, a nie kilka sekund. Po serii awarii launchd w systemie macOS stosuje nieudokumentowaną blokadę ochronną ponownego uruchamiania, przez którą może przestać respektować KeepAlive=true, dopóki zewnętrzny wyzwalacz, taki jak interaktywne logowanie, połączenie z panelem lub launchctl kickstart, nie uzbroi jej ponownie.

Typowe oznaki:

• Pakiet stabilności, którego error.code to ENETDOWN lub pokrewny kod, a stos wywołań wskazuje na net lookupAndConnect / Socket.connect środowiska Node. OpenClaw 2026.5.26 i nowsze wersje klasyfikują je jako niegroźne, przejściowe błędy sieciowe, dzięki czemu nie są już przekazywane do najwyższego poziomu obsługi nieprzechwyconych błędów; w przypadku starszej wersji należy najpierw przeprowadzić aktualizację.
• Długie okresy braku aktywności, które kończą się natychmiast po połączeniu z interfejsem Control UI lub hostem przez SSH: to aktywność widoczna dla użytkownika ponownie uzbraja blokadę ponownego uruchamiania launchd, a nie jakiekolwiek działanie panelu wobec Gateway.
• Licznik runs zwiększający się w ciągu dnia bez odpowiadającego mu wiersza received SIG*; shutting down w ~/Library/Logs/openclaw/gateway.log: prawidłowe zamknięcia zapisują sygnał w dzienniku, natomiast przejściowe awarie tego nie robią.

Co zrobić:

1. Zaktualizuj Gateway, jeśli używana wersja jest starsza niż 2026.5.26. Po aktualizacji przyszłe błędy ENETDOWN będą rejestrowane jako ostrzeżenia zamiast kończyć proces.

2. Ogranicz aktywność uśpienia konserwacyjnego na hostach Mac mini / komputerach stacjonarnych przeznaczonych do pracy jako stale dostępne serwery:

   sudo pmset -a sleep 0 disksleep 0 standby 0 powernap 0

   Znacznie ogranicza to podstawowy problem z krótkotrwałym zanikiem działania sterownika, ale nie eliminuje go całkowicie. Niezależnie od tych flag system nadal może przeprowadzać niektóre uśpienia konserwacyjne na potrzeby podtrzymywania połączeń TCP i obsługi mDNS.

3. Dodaj mechanizm nadzoru żywotności, aby przyszła seria awarii zatrzymana przez launchd została szybko wykryta:

   # Przykładowe sprawdzenie żywotności uwzględniające launchd, odpowiednie dla Cron lub LaunchAgent uruchamianego co 5 minutstate=$(launchctl print gui/$UID/ai.openclaw.gateway 2>/dev/null | awk -F'= ' '/state =/ {print $2; exit}')if [ "$state" != "running" ]; then  launchctl kickstart -k gui/$UID/ai.openclaw.gatewayfi

   Celem jest zewnętrzne ponowne uzbrojenie blokady ponownego uruchamiania; samo KeepAlive=true nie wystarcza w systemie macOS po serii awarii.

Powiązane:

• Uwagi dotyczące platformy macOS
• Rejestrowanie
• Doctor

Pętla nadzorcy launchd w systemie macOS z powielonymi agentami LaunchAgent Gateway/Node

Użyj tego rozwiązania, gdy instalacja w systemie macOS uruchamia się ponownie co kilka sekund, testy kondycji openclaw naprzemiennie wskazują dostępność i niedostępność, a wysyłanie przez kanały zatrzymuje się, mimo że usługa wydaje się działać.

Zaobserwowano to w starszych instalacjach, w których jednocześnie aktywne były agenty LaunchAgent ai.openclaw.gateway i ai.openclaw.node, a każdy z nich wstrzykiwał OPENCLAW_LAUNCHD_LABEL. W takim stanie OpenClaw może wykryć nadzór launchd, spróbować przekazać ponowne uruchomienie z powrotem do launchd i wpaść w szybką pętlę EADDRINUSE/ponownego uruchamiania zamiast utrzymywać jeden stabilny proces Gateway.

for i in 1 2 3 4; do  ps aux | grep 'openclaw.*index.js' | grep -v grep | awk '{print $2}'  sleep 10done openclaw gateway status --deepopenclaw node statuslaunchctl print gui/$UID/ai.openclaw.gateway | grep -E 'state|last exit|runs'tail -n 80 ~/Library/Logs/openclaw/gateway.log

Należy szukać:

• Więcej niż jednego identyfikatora PID Gateway w 30-sekundowej próbce zamiast jednego stabilnego procesu.
• EADDRINUSE, another gateway instance is already listening lub powtarzających się wierszy ponownego uruchamiania/przekazywania w gateway.log.
• Jednoczesnego załadowania ~/Library/LaunchAgents/ai.openclaw.gateway.plist i ~/Library/LaunchAgents/ai.openclaw.node.plist na hoście, na którym powinna działać tylko jedna zarządzana usługa Gateway.

Co zrobić:

1. Jeśli na tym hoście powinna działać wyłącznie usługa Gateway, usuń zarządzaną usługę Node za pośrednictwem OpenClaw. Pomiń ten krok, jeśli usługa Node jest aktywnie wykorzystywana do zdalnych funkcji Node; jej odinstalowanie zatrzyma te funkcje na tym hoście:

   openclaw node uninstall

2. Zainstaluj trwały skrypt opakowujący Gateway, który przed uruchomieniem OpenClaw wyczyści odziedziczone znaczniki launchd. Użyj obsługiwanej opcji --wrapper; nie edytuj wygenerowanego pliku w ~/.openclaw/service-env/, ponieważ ponowna instalacja usługi, aktualizacja i naprawa przez Doctor ponownie generują ten plik:

   mkdir -p ~/.local/bincat >~/.local/bin/openclaw-launchd-workaround <<'EOF'#!/bin/shset -euunset OPENCLAW_LAUNCHD_LABEL LAUNCH_JOB_LABEL LAUNCH_JOB_NAME XPC_SERVICE_NAME || trueexec openclaw "$@"EOFchmod 700 ~/.local/bin/openclaw-launchd-workaround openclaw gateway install \  --wrapper ~/.local/bin/openclaw-launchd-workaround \  --force

   gateway install zachowuje ścieżkę skryptu opakowującego podczas wymuszonych ponownych instalacji, aktualizacji i napraw przez Doctor.

3. Sprawdź, czy Gateway działa stabilnie i obsługuje RPC, a nie tylko nasłuchuje:

   openclaw gateway status --deep --require-rpc for i in 1 2 3 4; do  ps aux | grep 'openclaw.*index.js' | grep -v grep | awk '{print $2}'  sleep 10done

   Próbka PID powinna wskazywać jeden stabilny proces zamiast zmieniającego się zestawu identyfikatorów PID, a obsługa przychodzących wiadomości kanałów powinna zostać wznowiona.

4. Po aktualizacji do wersji, w której naprawiono podstawową pętlę dwóch agentów LaunchAgent, usuń obejście i ponownie zainstaluj standardową zarządzaną usługę:

   OPENCLAW_WRAPPER= openclaw gateway install --forcerm ~/.local/bin/openclaw-launchd-workaround

Powiązane:

• Uwagi dotyczące platformy macOS
• Doctor
• CLI Gateway

Gateway kończy działanie podczas dużego użycia pamięci

Użyj tego rozwiązania, gdy Gateway znika pod obciążeniem, nadzorca zgłasza ponowne uruchomienie w stylu OOM lub dzienniki zawierają wzmiankę o critical memory pressure bundle written.

openclaw gateway status --deepopenclaw logs --followopenclaw gateway stability --bundle latestopenclaw gateway diagnostics export

Należy szukać:

• Reason: diagnostic.memory.pressure.critical w najnowszym pakiecie stabilności.
• Memory pressure: z critical/rss_threshold, critical/heap_threshold lub critical/rss_growth.
• Wartości V8 heap: zbliżonych do limitu sterty.
• Wpisów Largest session files:, takich jak agents/<agent>/sessions/<session>.jsonl lub sessions/<session>.jsonl.
• Liczników pamięci cgroup systemu Linux, gdy Gateway działa wewnątrz kontenera lub usługi z ograniczoną pamięcią.

Typowe oznaki:

• critical memory pressure bundle written pojawia się krótko przed ponownym uruchomieniem → OpenClaw przechwycił pakiet stabilności sprzed OOM. Sprawdź go za pomocą openclaw gateway stability --bundle latest.
• memory pressure: level=critical ... memoryPressureSnapshot=disabled pojawia się w dziennikach Gateway → OpenClaw wykrył krytyczną presję pamięci, ale migawka stabilności sprzed OOM jest wyłączona.
• Largest session files: wskazuje bardzo dużą, zanonimizowaną ścieżkę transkrypcji → ogranicz zachowywaną historię sesji, sprawdź przyrost sesji lub przenieś stare transkrypcje poza aktywny magazyn przed ponownym uruchomieniem.
• Liczba używanych bajtów V8 heap: jest zbliżona do limitu sterty → zmniejsz obciążenie związane z promptami/sesjami, ogranicz liczbę jednoczesnych zadań lub zwiększ limit sterty Node dopiero po potwierdzeniu, że obciążenie jest oczekiwane.
• Memory pressure: critical/rss_growth → użycie pamięci szybko wzrosło w obrębie jednego okna próbkowania. Sprawdź najnowsze dzienniki pod kątem dużego importu, niekontrolowanych danych wyjściowych narzędzia, powtarzanych ponowień lub partii zakolejkowanych zadań agenta.
• Krytyczna presja pamięci pojawia się w dziennikach, ale nie istnieje żaden pakiet → jest to ustawienie domyślne. Ustaw diagnostics.memoryPressureSnapshot: true, aby podczas przyszłych zdarzeń krytycznej presji pamięci przechwytywać pakiet stabilności sprzed OOM.

Pakiet stabilności nie zawiera ładunku. Obejmuje operacyjne dane dotyczące pamięci i zanonimizowane względne ścieżki plików, ale nie tekst wiadomości, treści Webhooków, dane uwierzytelniające, tokeny, pliki cookie ani surowe identyfikatory sesji. Do zgłoszeń błędów należy dołączać eksport diagnostyczny zamiast kopiować surowe dzienniki.

Powiązane:

• Kondycja Gateway
• Eksport diagnostyczny
• Sesje

Gateway odrzucił nieprawidłową konfigurację

Użyj tego rozwiązania, gdy uruchomienie Gateway kończy się niepowodzeniem z komunikatem Invalid config lub dzienniki przeładowania na gorąco informują o pominięciu nieprawidłowej edycji.

openclaw logs --followopenclaw config fileopenclaw config validateopenclaw doctor

Należy szukać:

• Invalid config at ...
• config reload skipped (invalid config): ...
• Config write rejected: ...
• Pliku openclaw.json.rejected.* ze znacznikiem czasu obok aktywnej konfiguracji.
• Pliku openclaw.json.clobbered.* ze znacznikiem czasu, jeśli doctor --fix naprawił uszkodzoną bezpośrednią edycję.
• OpenClaw zachowuje 32 najnowsze pliki .clobbered.* dla każdej ścieżki konfiguracji i rotuje starsze.

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

Powiązane:

• Konfiguracja
• Konfiguracja: przeładowywanie na gorąco
• Konfiguracja: ścisła walidacja
• Doctor

Ostrzeżenia sondy Gateway

Użyj, gdy openclaw gateway probe nawiązuje z czymś połączenie, ale nadal wyświetla blok ostrzeżeń.

openclaw gateway probeopenclaw gateway probe --jsonopenclaw gateway probe --ssh user@gateway-host

Sprawdź:

• warnings[].code i primaryTargetId w danych wyjściowych JSON.
• Czy ostrzeżenie dotyczy rozwiązania awaryjnego SSH, wielu instancji Gateway, brakujących zakresów czy nierozwiązanych odwołań uwierzytelniania.

Typowe sygnatury:

• SSH tunnel failed to start; falling back to direct probes. → konfiguracja SSH nie powiodła się, ale polecenie nadal próbowało użyć bezpośrednich skonfigurowanych celów lub celów pętli zwrotnej.
• multiple reachable gateway identities detected → odpowiedziały odrębne instancje Gateway albo OpenClaw nie mógł potwierdzić, że osiągalne cele są tą samą instancją Gateway. Tunel SSH, adres URL serwera proxy lub skonfigurowany zdalny adres URL prowadzący do tej samej instancji Gateway są traktowane jako jedna instancja Gateway z wieloma transportami, nawet gdy porty transportów są różne.
• Read-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 lub użyj poświadczeń z operator.read.
• Gateway accepted the WebSocket connection, but follow-up read diagnostics failed → połączenie zadziałało, ale pełny zestaw diagnostycznych RPC przekroczył limit czasu lub zakończył się niepowodzeniem. Należy traktować to jako osiągalny Gateway z ograniczoną diagnostyką; porównaj connect.ok i connect.rpcOk w danych wyjściowych --json.
• Capability: pairing-pending lub gateway closed (1008): pairing required → Gateway odpowiedział, ale ten klient nadal wymaga sparowania lub zatwierdzenia przed uzyskaniem zwykłego dostępu operatora.
• Tekst ostrzeżenia o nierozwiązanym SecretRef gateway.auth.* / gateway.remote.* → materiały uwierzytelniające były niedostępne w tej ścieżce polecenia dla celu, którego obsługa nie powiodła się.

Powiązane:

• Gateway
• Wiele instancji Gateway na tym samym hoście
• Dostęp zdalny

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

Jeśli stan kanału wskazuje połączenie, ale przepływ wiadomości nie działa, należy skupić się na zasadach, uprawnieniach i regułach dostarczania właściwych dla kanału.

openclaw channels status --probeopenclaw pairing list --channel <channel> [--account <id>]openclaw status --deepopenclaw logs --followopenclaw config get channels

Sprawdź:

• Zasady wiadomości prywatnych (pairing, allowlist, open, disabled).
• Listę dozwolonych grup i wymagania dotyczące wzmianek.
• Brakujące uprawnienia lub zakresy interfejsu API kanału.

Typowe sygnatury:

• mention required → wiadomość została zignorowana przez zasady wzmianek grupowych.
• pairing / ślady oczekującego zatwierdzenia → nadawca nie został zatwierdzony.
• missing_scope, not_in_channel, Forbidden, 401/403 → problem z uwierzytelnianiem lub uprawnieniami kanału.

Powiązane:

• Rozwiązywanie problemów z kanałami
• Discord
• Telegram
• WhatsApp

Dostarczanie Cron i Heartbeat

Jeśli Cron lub Heartbeat nie został wykonany albo nie dostarczył wiadomości, najpierw sprawdź stan harmonogramu, a następnie cel dostarczania.

openclaw cron statusopenclaw cron listopenclaw cron runs --id <jobId> --limit 20openclaw system heartbeat lastopenclaw logs --follow

Sprawdź:

• Czy Cron jest włączony i czy wskazano następne wybudzenie.
• Stan historii uruchomień zadania (ok, skipped, error).
• Przyczyny pominięcia Heartbeat (quiet-hours, requests-in-flight, cron-in-progress, lanes-busy, alerts-disabled, empty-heartbeat-file, no-tasks-due).

Powiązane:

• Heartbeat
• Zaplanowane zadania
• Zaplanowane zadania: rozwiązywanie problemów

Node jest sparowany, ale narzędzie nie działa

Jeśli Node jest sparowany, ale narzędzia nie działają, należy odizolować stan pierwszego planu, uprawnień i zatwierdzeń.

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

Sprawdź:

• Czy Node jest online i ma oczekiwane możliwości.
• Przyznane uprawnienia systemu operacyjnego do kamery, mikrofonu, lokalizacji i ekranu.
• Stan zatwierdzeń wykonywania poleceń i listy dozwolonych elementów.

Typowe sygnatury:

• NODE_BACKGROUND_UNAVAILABLE → aplikacja Node musi działać na pierwszym planie.
• *_PERMISSION_REQUIRED / LOCATION_PERMISSION_REQUIRED → brak uprawnienia systemu operacyjnego.
• SYSTEM_RUN_DENIED: approval required → zatwierdzenie wykonania oczekuje.
• SYSTEM_RUN_DENIED: allowlist miss → polecenie zostało zablokowane przez listę dozwolonych elementów.

Powiązane:

• Zatwierdzenia wykonywania poleceń
• Rozwiązywanie problemów z Node
• Node

Narzędzie przeglądarki nie działa

Użyj, gdy działania narzędzia przeglądarki kończą się niepowodzeniem, mimo że sam Gateway działa prawidłowo.

openclaw browser statusopenclaw browser start --browser-profile openclawopenclaw browser profilesopenclaw logs --followopenclaw doctor

Sprawdź:

• Czy ustawiono plugins.allow i czy zawiera browser.
• Prawidłową ścieżkę do pliku wykonywalnego przeglądarki.
• Osiągalność profilu CDP.
• Dostępność lokalnej przeglądarki Chrome dla profili existing-session / user.

Powiązane:

• Przeglądarka (zarządzana przez OpenClaw)
• Rozwiązywanie problemów z przeglądarką

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

Większość problemów po aktualizacji wynika z rozbieżności konfiguracji lub egzekwowania teraz bardziej rygorystycznych ustawień domyślnych.

openclaw gateway statusopenclaw config get gateway.modeopenclaw config get gateway.remote.urlopenclaw config get gateway.auth.mode

openclaw config get gateway.bindopenclaw config get gateway.auth.modeopenclaw config get gateway.auth.tokenopenclaw gateway statusopenclaw logs --follow

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

Jeśli po wykonaniu tych kontroli konfiguracja usługi i środowisko uruchomieniowe nadal są niespójne, należy ponownie zainstalować metadane usługi z tego samego profilu/katalogu stanu:

openclaw gateway install --forceopenclaw gateway restart

Powiązane materiały:

• Uwierzytelnianie
• Wykonywanie w tle i narzędzie procesów
• Parowanie nodów

Powiązane materiały

• Doctor
• Często zadawane pytania
• Procedura operacyjna Gateway