OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Start here

Ogólne rozwiązywanie problemów

Punkt wejścia do diagnostyki. 2 minuty do rozpoznania problemu, a następnie przejście do szczegółowej strony.

Pierwsze 60 sekund

Wykonaj kolejno następujące polecenia:

bash
openclaw statusopenclaw status --allopenclaw gateway probeopenclaw gateway statusopenclaw doctoropenclaw channels status --probeopenclaw logs --follow

Prawidłowe wyniki, po jednym wierszu dla każdego polecenia:

  • openclaw status pokazuje skonfigurowane kanały bez błędów uwierzytelniania.
  • openclaw status --all generuje pełny raport, który można udostępnić.
  • openclaw gateway probe pokazuje Reachable: yes. Capability: ... to poziom uwierzytelnienia potwierdzony przez sondę; Read probe: limited - missing scope: operator.read oznacza ograniczoną diagnostykę, a nie błąd połączenia.
  • openclaw gateway status pokazuje Runtime: running, Connectivity probe: ok oraz wiarygodną wartość Capability: .... Dodaj --require-rpc, aby wymagać również potwierdzenia RPC z zakresem odczytu.
  • openclaw doctor nie zgłasza blokujących błędów konfiguracji ani usługi.
  • openclaw channels status --probe zwraca bieżący stan transportu dla każdego konta (works / audit ok), gdy Gateway jest osiągalny; w przeciwnym razie używa podsumowań opartych wyłącznie na konfiguracji.
  • openclaw logs --follow pokazuje stabilną aktywność bez powtarzających się błędów krytycznych.

Asystent wydaje się ograniczony lub brakuje mu narzędzi

Sprawdź obowiązujący profil narzędzi:

bash
openclaw statusopenclaw status --allopenclaw doctor

Typowe przyczyny:

  • tools.profile: "minimal" zezwala tylko na session_status.
  • tools.profile: "messaging" ma ograniczony zakres i jest przeznaczony dla agentów obsługujących wyłącznie czat.
  • tools.profile: "coding" jest profilem domyślnym dla nowych konfiguracji lokalnych (praca z repozytorium, plikami, powłoką i środowiskiem uruchomieniowym).
  • tools.profile: "full" usuwa ograniczenia profilu; używaj go wyłącznie dla zaufanych agentów kontrolowanych przez operatora.
  • Ustawienie agents.list[].tools dla konkretnego agenta zawęża lub rozszerza profil główny dla tego agenta.

Zmień profil, uruchom ponownie lub przeładuj Gateway, a następnie ponownie sprawdź go za pomocą openclaw status --all. Pełna tabela profili i grup: Profile narzędzi.

Długi kontekst Anthropic — błąd 429

HTTP 429: rate_limit_error: Extra usage is required for long context requests → Błąd Anthropic 429 — długi kontekst wymaga dodatkowego użycia.

Lokalny backend zgodny z OpenAI działa bezpośrednio, ale nie działa w OpenClaw

Lokalny/samodzielnie hostowany backend /v1 odpowiada na bezpośrednie sondy /v1/chat/completions, ale nie działa z poleceniem openclaw infer model run ani podczas zwykłych tur agenta:

  1. Jeśli błąd wskazuje, że messages[].content oczekuje ciągu znaków, ustaw models.providers.<provider>.models[].compat.requiresStringContent: true.
  2. Jeśli nadal nie działają wyłącznie tury agenta OpenClaw, ustaw models.providers.<provider>.models[].compat.supportsTools: false i spróbuj ponownie.
  3. Jeśli małe wywołania bezpośrednie działają, ale większe prompty OpenClaw powodują awarię backendu, jest to ograniczenie nadrzędnego modelu lub serwera, a nie błąd OpenClaw. Kontynuuj na stronie Lokalny backend zgodny z OpenAI przechodzi bezpośrednie sondy, ale uruchomienia agenta kończą się niepowodzeniem.

Instalacja Pluginu kończy się niepowodzeniem z powodu braku rozszerzeń OpenClaw

package.json missing openclaw.extensions oznacza, że pakiet Pluginu używa struktury, której OpenClaw już nie akceptuje.

Napraw pakiet Pluginu:

  1. Dodaj openclaw.extensions do pliku package.json, wskazując zbudowane pliki środowiska uruchomieniowego (zwykle ./dist/index.js).
  2. Opublikuj pakiet ponownie, a następnie jeszcze raz uruchom openclaw plugins install <package>.
json
{  "name": "@openclaw/my-plugin",  "version": "1.2.3",  "openclaw": {    "extensions": ["./dist/index.js"]  }}

Materiały referencyjne: Architektura Pluginów

Zasady instalacji blokują instalowanie lub aktualizowanie Pluginów

Aktualizacja kończy się, ale Pluginy są nieaktualne, wyłączone albo wyświetlają komunikat blocked by install policy, install policy failed closed lub Disabled "<plugin>" after plugin update failure: sprawdź security.installPolicy.

Zasady instalacji są stosowane podczas instalowania i aktualizowania Pluginów. Wersje Pluginów @openclaw/* zwykle zmieniają się wraz z wydaniem OpenClaw, dlatego aktualizacja OpenClaw może wymagać odpowiedniej aktualizacji Pluginów podczas synchronizacji po aktualizacji.

Unikaj następujących postaci zasad, chyba że utrzymujesz również odpowiednią regułę aktualizacji:

  • Blokowanie Pluginów należących do OpenClaw na jednej, dokładnie określonej starej wersji (na przykład tylko @openclaw/*@2026.5.3).
  • Blokowanie wyłącznie według rodzaju źródła (każde żądanie npm, sieciowe lub request.mode: "update").
  • Traktowanie polecenia zasad jako opcjonalnego: gdy security.installPolicy jest włączone, brak pliku wykonywalnego zasad, jego powolne działanie, brak możliwości odczytu lub blokada uprawnień powodują bezpieczne odrzucenie operacji.
  • Zatwierdzanie wersji bez sprawdzenia wartości openclawVersion z żądania względem metadanych kandydata na Plugin.

Preferuj reguły zezwalające na zaufane aktualizacje @openclaw/* zgodne z bieżącym hostem zamiast trwałego przypinania jednej wersji. Jeśli domyślnie blokujesz npm, dodaj wąski wyjątek dla używanych identyfikatorów Pluginów i zastosuj tę samą regułę zaufania do request.mode: "update" co do instalacji.

Odzyskiwanie:

bash
openclaw doctor --deepopenclaw plugins update --allopenclaw status --all

Jeśli zasady są celowo restrykcyjne, poluzuj je na czas zaufanej aktualizacji, ponownie uruchom openclaw plugins update --all, a następnie przywróć bardziej restrykcyjną regułę. Jeśli niepowodzenie aktualizacji spowodowało wyłączenie Pluginu, sprawdź go przed ponownym włączeniem:

bash
openclaw plugins inspect <plugin-id> --runtime --jsonopenclaw plugins enable <plugin-id>

Materiały referencyjne: Zasady instalacji operatora

Plugin jest obecny, ale zablokowany z powodu podejrzanego właściciela

Polecenie openclaw doctor, konfiguracja lub ostrzeżenia podczas uruchamiania pokazują:

text
blocked plugin candidate: suspicious ownership (... uid=1000, expected uid=0 or root)plugin present but blocked

Pliki Pluginu należą do innego użytkownika systemu Unix niż proces, który je ładuje. Nie usuwaj konfiguracji Pluginu; popraw właściciela plików albo uruchom OpenClaw jako użytkownik będący właścicielem katalogu stanu.

Instalacje Docker działają jako node (uid 1000). Napraw montowania powiązane z hosta:

bash
sudo chown -R 1000:1000 /path/to/openclaw-config /path/to/openclaw-workspaceopenclaw doctor --fix

Jeśli celowo uruchamiasz OpenClaw jako użytkownik root, napraw zamiast tego zarządzany katalog główny Pluginów:

bash
sudo chown -R root:root /path/to/openclaw-config/npmopenclaw doctor --fix

Szczegółowa dokumentacja: Zablokowany właściciel ścieżki Pluginu, Docker: uprawnienia i EACCES

Drzewo decyzyjne

flowchart TD
  A[OpenClaw nie działa] --> B{Co przestaje działać jako pierwsze}
  B --> C[Brak odpowiedzi]
  B --> D[Panel lub interfejs Control UI nie może się połączyć]
  B --> E[Gateway nie uruchamia się lub usługa nie działa]
  B --> F[Kanał łączy się, ale wiadomości nie są przesyłane]
  B --> G[Cron lub Heartbeat nie uruchomił się albo niczego nie dostarczył]
  B --> H[Node jest sparowany, ale wykonanie operacji kamery, obszaru roboczego lub ekranu kończy się niepowodzeniem]
  B --> I[Narzędzie przeglądarki nie działa]

  C --> C1[/Sekcja Brak odpowiedzi/]
  D --> D1[/Sekcja Control UI/]
  E --> E1[/Sekcja Gateway/]
  F --> F1[/Sekcja przepływu kanału/]
  G --> G1[/Sekcja automatyzacji/]
  H --> H1[/Sekcja narzędzi Node/]
  I --> I1[/Sekcja przeglądarki/]
Brak odpowiedzi
bash
openclaw statusopenclaw gateway statusopenclaw channels status --probeopenclaw pairing list --channel <channel> [--account <id>]openclaw logs --follow

Prawidłowy wynik:

  • Runtime: running
  • Connectivity probe: ok
  • Capability: read-only, write-capable lub admin-capable
  • Kanał pokazuje połączenie transportu oraz, jeśli jest to obsługiwane, works lub audit ok w wyniku channels status --probe
  • Nadawca jest zatwierdzony (lub zasady wiadomości bezpośrednich są otwarte albo korzystają z listy dozwolonych)

Sygnatury dziennika:

  • drop guild message (mention required → wymóg wzmianki w Discord zablokował wiadomość.
  • pairing request → nadawca nie został zatwierdzony; oczekiwanie na zatwierdzenie parowania wiadomości bezpośrednich.
  • blocked / allowlist w dziennikach kanału → nadawca, pokój lub grupa zostały odfiltrowane.

Szczegółowe strony: Brak odpowiedzi, Rozwiązywanie problemów z kanałami, Parowanie

Panel lub interfejs Control UI nie może się połączyć
bash
openclaw statusopenclaw gateway statusopenclaw logs --followopenclaw doctoropenclaw channels status --probe

Prawidłowy wynik:

  • Dashboard: http://... jest widoczny w wyniku openclaw gateway status
  • Connectivity probe: ok
  • Capability: read-only, write-capable lub admin-capable
  • Brak pętli uwierzytelniania w dziennikach

Sygnatury dziennika:

  • device identity required → kontekst HTTP/niezabezpieczony nie może ukończyć uwierzytelniania urządzenia.
  • origin not allowed → wartość Origin przeglądarki nie jest dozwolona dla docelowego Gateway interfejsu Control UI.
  • AUTH_TOKEN_MISMATCH z canRetryWithDeviceToken=true → może automatycznie nastąpić jedna próba z zaufanym tokenem urządzenia, wykorzystująca zakresy zapisane w pamięci podręcznej sparowanego tokenu.
  • powtarzające się unauthorized po tej próbie → nieprawidłowy token lub hasło, niezgodny tryb uwierzytelniania albo nieaktualny token sparowanego urządzenia.
  • too many failed authentication attempts (retry later) → powtarzające się niepowodzenia z tej wartości Origin przeglądarki są tymczasowo blokowane; inne źródła localhost korzystają z oddzielnych limitów. Informacje o niuansach równoczesnych ponownych prób Tailscale Serve znajdziesz w sekcji Łączność panelu/interfejsu Control UI.
  • gateway connect failed: → interfejs użytkownika wskazuje nieprawidłowy adres URL lub port albo Gateway jest nieosiągalny.

Szczegółowe strony: Łączność panelu/interfejsu Control UI, Control UI, Uwierzytelnianie

Gateway nie uruchamia się lub zainstalowana usługa nie działa
bash
openclaw statusopenclaw gateway statusopenclaw logs --followopenclaw doctoropenclaw channels status --probe

Prawidłowy wynik:

  • Service: ... (loaded)
  • Runtime: running
  • Connectivity probe: ok
  • Capability: read-only, write-capable lub admin-capable

Sygnatury dziennika:

  • Gateway start blocked: set gateway.mode=local lub existing config is missing gateway.mode → tryb Gateway jest zdalny albo w konfiguracji brakuje oznaczenia trybu lokalnego i wymaga ona naprawy.
  • refusing to bind gateway ... without auth → powiązanie z adresem innym niż lokalna pętla zwrotna bez prawidłowej ścieżki uwierzytelniania (token/hasło lub skonfigurowane zaufane proxy).
  • another gateway instance is already listening lub EADDRINUSE → port jest już zajęty.

Szczegółowe strony: Usługa Gateway nie działa, Proces w tle, Konfiguracja

Kanał łączy się, ale wiadomości nie są przesyłane
bash
openclaw statusopenclaw gateway statusopenclaw logs --followopenclaw doctoropenclaw channels status --probe

Prawidłowy wynik:

  • Transport kanału jest połączony.
  • Kontrole parowania/listy dozwolonych kończą się pomyślnie.
  • Wzmianki są wykrywane tam, gdzie są wymagane.

Sygnatury dziennika:

  • mention required → wymóg wzmianki w grupie zablokował przetwarzanie.
  • pairing / pending → nadawca wiadomości bezpośredniej nie został jeszcze zatwierdzony.
  • not_in_channel, missing_scope, Forbidden, 401/403 → problem z tokenem uprawnień kanału.

Szczegółowe strony: Kanał jest połączony, ale wiadomości nie są przesyłane, Rozwiązywanie problemów z kanałami

Cron lub Heartbeat nie uruchomił się albo niczego nie dostarczył
bash
openclaw statusopenclaw gateway statusopenclaw cron statusopenclaw cron listopenclaw cron runs --id <jobId> --limit 20openclaw logs --follow

Prawidłowy wynik:

  • cron status pokazuje włączony harmonogram oraz czas następnego wybudzenia.
  • cron runs pokazuje ostatnie wpisy ok.
  • Heartbeat jest włączony i mieści się w aktywnych godzinach.

Sygnatury dziennika:

  • cron: scheduler disabled; jobs will not run automatically → Cron jest wyłączony.
  • heartbeat skipped z powodem quiet-hours → poza skonfigurowanymi godzinami aktywności.
  • heartbeat skipped z powodem empty-heartbeat-file → plik HEARTBEAT.md istnieje, ale zawiera wyłącznie puste wiersze, komentarze, nagłówki, ograniczniki bloków kodu lub szkielet pustej listy kontrolnej.
  • heartbeat skipped z powodem no-tasks-due → tryb zadań jest aktywny, ale nie nadszedł jeszcze termin wykonania żadnego zadania.
  • heartbeat skipped z powodem alerts-disabled → opcje showOk, showAlerts i useIndicator są wyłączone.
  • requests-in-flight → główna ścieżka jest zajęta; wybudzenie Heartbeat zostało odroczone.
  • unknown accountId → konto docelowe dostarczania Heartbeat nie istnieje.

Szczegółowe strony: Dostarczanie Cron i Heartbeat, Zaplanowane zadania: rozwiązywanie problemów, Heartbeat

Node jest sparowany, ale narzędzie kamery, obszaru roboczego, ekranu lub wykonywania poleceń nie działa
bash
openclaw statusopenclaw gateway statusopenclaw nodes statusopenclaw nodes describe --node <idOrNameOrIp>openclaw logs --follow

Prawidłowe dane wyjściowe:

  • Node jest wymieniony jako połączony i sparowany dla roli node.
  • Funkcja wymagana przez wywoływane polecenie jest dostępna.
  • Narzędzie ma przyznane wymagane uprawnienia.

Charakterystyczne wpisy w dzienniku:

  • NODE_BACKGROUND_UNAVAILABLE → przenieś aplikację Node na pierwszy plan.
  • *_PERMISSION_REQUIRED → brakuje uprawnienia systemu operacyjnego lub odmówiono jego przyznania.
  • SYSTEM_RUN_DENIED: approval required → oczekuje zatwierdzenie wykonania polecenia.
  • SYSTEM_RUN_DENIED: allowlist miss → polecenia nie ma na liście dozwolonych poleceń wykonywania.

Szczegółowe strony: Node sparowany, narzędzie nie działa, Rozwiązywanie problemów z Node, Zatwierdzanie wykonywania poleceń

Wykonywanie poleceń nagle wymaga zatwierdzenia
bash
openclaw config get tools.exec.hostopenclaw config get tools.exec.securityopenclaw config get tools.exec.askopenclaw gateway restart

Co się zmieniło:

  • Nieustawiona opcja tools.exec.host ma domyślną wartość auto, która wskazuje sandbox, gdy środowisko uruchomieniowe piaskownicy jest aktywne, a w przeciwnym razie gateway.
  • host=auto odpowiada tylko za trasowanie; działanie bez monitów wynika z ustawień security=full oraz ask=off w Gateway lub Node.
  • Nieustawiona opcja tools.exec.security ma domyślną wartość full w gateway/node.
  • Nieustawiona opcja tools.exec.ask ma domyślną wartość off.
  • Jeśli pojawiają się prośby o zatwierdzenie, zasady lokalne hosta lub danej sesji zaostrzyły wykonywanie poleceń względem tych wartości domyślnych.

Przywróć bieżące ustawienia domyślne niewymagające zatwierdzenia:

bash
openclaw config set tools.exec.host gatewayopenclaw config set tools.exec.security fullopenclaw config set tools.exec.ask offopenclaw gateway restart

Bezpieczniejsze rozwiązania alternatywne:

  • Ustaw tylko tools.exec.host=gateway, aby zapewnić stabilne trasowanie do hosta.
  • Użyj security=allowlist z ask=on-miss, aby wykonywać polecenia na hoście z weryfikacją poleceń nieobecnych na liście dozwolonych.
  • Włącz tryb piaskownicy, aby host=auto ponownie wskazywało sandbox.

Charakterystyczne wpisy w dzienniku:

  • Approval required. → polecenie oczekuje na /approve ....
  • SYSTEM_RUN_DENIED: approval required → oczekuje zatwierdzenie wykonania polecenia na hoście Node.
  • exec host=sandbox requires a sandbox runtime for this session → wybrano piaskownicę niejawnie lub jawnie, ale tryb piaskownicy jest wyłączony.

Szczegółowe strony: Wykonywanie poleceń, Zatwierdzanie wykonywania poleceń, Bezpieczeństwo: co sprawdza audyt

Narzędzie przeglądarki nie działa
bash
openclaw statusopenclaw gateway statusopenclaw browser statusopenclaw logs --followopenclaw doctor

Prawidłowe dane wyjściowe:

  • Stan przeglądarki wskazuje running: true oraz wybraną przeglądarkę i profil.
  • Profil openclaw uruchamia się albo profil user widzi lokalne karty Chrome.

Charakterystyczne wpisy w dzienniku:

  • unknown command "browser" → ustawiono plugins.allow, które nie zawiera browser.
  • Failed to start Chrome CDP on port → nie udało się uruchomić lokalnej przeglądarki.
  • browser.executablePath not found → skonfigurowana ścieżka do pliku wykonywalnego jest nieprawidłowa.
  • browser.cdpUrl must be http(s) or ws(s) → skonfigurowany adres URL CDP używa nieobsługiwanego schematu.
  • browser.cdpUrl has invalid port → skonfigurowany adres URL CDP zawiera nieprawidłowy port lub port spoza dozwolonego zakresu.
  • No Chrome tabs found for profile="user" → profil dołączania Chrome MCP nie ma otwartych lokalnych kart Chrome.
  • Remote CDP for profile "<name>" is not reachable → skonfigurowany zdalny punkt końcowy CDP jest nieosiągalny z tego hosta.
  • Browser attachOnly is enabled ... not reachable → profil służący wyłącznie do dołączania nie ma aktywnego celu CDP.
  • Nieaktualne ustawienia widoku, trybu ciemnego, języka lub trybu offline w profilach służących wyłącznie do dołączania albo zdalnych profilach CDP → uruchom openclaw browser stop --browser-profile <name>, aby zamknąć sesję sterowania i zwolnić stan emulacji bez ponownego uruchamiania Gateway.

Szczegółowe strony: Narzędzie przeglądarki nie działa, Brak polecenia lub narzędzia przeglądarki, Przeglądarka: rozwiązywanie problemów w systemie Linux, Przeglądarka: rozwiązywanie problemów ze zdalnym CDP w WSL2/Windows

Powiązane

Was this useful?
On this page

On this page