Napraw niedostępność usługi OpenClaw w ZimaOS lub CasaOS

OpenClaw wyświetlający komunikat Usługa niedostępna nie wskazuje jednej konkretnej awarii. W wątku społeczności IceWhale z lutego 2026 roku diagnostyka ujawniła kolejno trzy różne warstwy problemu: wymagany token bramy, niewystarczające uprawnienia do sprawdzania stanu Dockera z poziomu konta hosta ZimaOS oraz kontener OpenClaw, który nigdy nie ukończył początkowej konfiguracji.

Wątek jest szczególnie przydatny, ponieważ niektóre pośrednie sugestie okazały się błędne w przypadku obrazu spakowanego przez Big-Bear. Dodanie zmyślonej GATEWAY_MODE zmienna środowiskowa nie rozwiązała pętli ponownych uruchomień, a dodanie --gateway.mode=local do niewłaściwego polecenia spowodowało nieznana opcja Bieżąca dokumentacja OpenClaw potwierdza, że gateway.mode=local należy do trwałej konfiguracji OpenClaw, a wdrożenia Dockera powinny uruchomić proces wstępnej konfiguracji lub konfiguracji w celu jej utworzenia.

Najpierw sprawdź, czy kontener OpenClaw rzeczywiście działa

W pierwotnym wpisie aplikacja OpenClaw informowała, że nie działa prawidłowo, i wyświetlała wskazówkę dotyczącą OPENCLAW_GATEWAY_TOKEN.

Przed zmianą ustawień aplikacji sprawdź stan kontenera na hoście ZimaOS lub CasaOS:

docker ps -a | grep openclaw

Jeśli kontener jest ponownie uruchamiany lub został zatrzymany, odczytaj jego logi:

docker logs big-bear-openclaw --tail 100

Dokładna nazwa kontenera może być inna. Użyj docker ps -a aby ustalić rzeczywistą nazwę, zamiast zakładać, że zawsze jest to big-bear-openclaw.

Wygeneruj i zapisz OPENCLAW_GATEWAY_TOKEN

Pierwsza sugestia społeczności dotyczyła wygenerowania silnego losowego tokenu bramy:

openssl rand -hex 32

Jeśli OpenSSL jest niedostępny, w wątku zaproponowano lokalną alternatywę generującą losowe bajty:

head -c 32 /dev/urandom | xxd -p -c 32

Aktualna oficjalna dokumentacja Dockera OpenClaw również używa OPENCLAW_GATEWAY_TOKEN do uwierzytelniania bramy. Jego standardowy skrypt konfiguracji generuje token i zapisuje go w pliku wdrożenia .env automatycznie. W aplikacji CasaOS spakowanej ręcznie wprowadź wygenerowaną wartość w polu zmiennej środowiskowej oczekiwanym przez ten obraz.

Traktuj ten token jako sekret. Nie wklejaj go na publicznym forum, do zrzutu ekranu, zgłoszenia pomocy technicznej ani repozytorium.

Błąd uprawnień Dockera nie jest błędem uprawnień OpenClaw

Po dodaniu tokenu autor pierwotnego wpisu napotkał:

odmowa dostępu podczas próby połączenia z gniazdem demona Dockera
/var/run/docker.sock: connect: permission denied

Społeczność zalecała tymczasowe podniesienie uprawnień przed uruchomieniem administracyjnych poleceń Dockera:

sudo -i
docker ps

Używaj uprawnień roota tylko w przypadku poleceń, które rzeczywiście ich wymagają. Nie osłabiaj /var/run/docker.sock uprawnień ani nie ustawiaj gniazda Dockera jako dostępnego dla wszystkich tylko po to, aby usunąć ten błąd. Dostęp do Dockera w praktyce zapewnia uprawnienia administracyjne do hosta.

Prawdziwy błąd OpenClaw brzmiał „Missing config”

Po uzyskaniu dostępu do logów Dockera pojawił się ważny komunikat:

Brak konfiguracji. Uruchom `openclaw setup` lub ustaw gateway.mode=local

Było to bardziej praktyczne niż ogólna strona „Service Unavailable”. Aktualna dokumentacja bramy OpenClaw potwierdza, że brama odmawia normalnego uruchomienia, jeśli jej konfiguracja nie zawiera:

gateway.mode = local

Aktualny OpenClaw stwierdza również, że jedna z poniższych opcji konfiguracja openclaw lub openclaw onboard --mode local zapisuje tryb lokalnej bramy do trwałej konfiguracji.

Dlaczego GATEWAY_MODE=local nie naprawiło tego obrazu

Jedna z pośrednich odpowiedzi społeczności sugerowała dodanie:

GATEWAY_MODE=local

Użytkownik spróbował tego rozwiązania, ale pętla restartów trwała nadal. To ważne sprostowanie, które należy zachować: aktualna oficjalna dokumentacja OpenClaw nie definiuje ogólnej GATEWAY_MODE zmiennej środowiskowej jako zamiennika trwałego gateway.mode ustawieniem używanym w tym procesie.

Nie zamieniaj każdego klucza konfiguracji OpenClaw zawierającego kropkę na wymyśloną zmienną środowiskową pisaną wielkimi literami. Użyj metody konfiguracji opisanej w dokumentacji dokładnie używanego obrazu OpenClaw lub szablonu wdrożeniowego.

Dlaczego --gateway.mode=local spowodowało błąd „Unknown option”

Późniejsza próba społeczności polegała na dołączeniu:

--gateway.mode=local

do polecenia kontenera CasaOS. Obraz zwrócił wtedy:

unknown option '--gateway.mode'

Wątek prawidłowo wskazał przyczynę: CasaOS dołączał flagę do warstwy polecenia, która jej nie obsługiwała. Aktualny interfejs CLI OpenClaw używa poleceń takich jak openclaw gateway, konfiguracja openclaw, openclaw onboardoraz openclaw config set; gateway.mode jest kluczem konfiguracji, a nie uniwersalną flagą środowiska uruchomieniowego na najwyższym poziomie, którą można umieścić w dowolnym miejscu polecenia kontenera.

Obraz Big-Bear wymaga trwałego, zainicjalizowanego katalogu konfiguracji

Ostateczna diagnoza społeczności skupiała się na tym montowaniu:

/DATA/AppData/big-bear-openclaw
→ /home/node/.openclaw

Kontener oczekiwał konfiguracji w ścieżce /home/node/.openclaw, ale zamontowany katalog nie został zainicjalizowany. Jest to zgodne z aktualną dokumentacją OpenClaw dotyczącą Dockera: zamontowany katalog konfiguracji zawiera trwałe openclaw.json, dane profilu uwierzytelniania i sekrety pobierane ze zmiennych środowiskowych.

Ostateczna sugestia w wątku brzmiała, aby uruchomić konfigurację wewnątrz kontenera, tak aby zamontowany katalog otrzymał rzeczywistą konfigurację OpenClaw. Jednak autor pierwotnego posta nie wrócił z ostatecznym potwierdzeniem po tej ostatniej odpowiedzi. Należy traktować to jako najsilniejszą diagnozę w wątku, a nie jako zweryfikowane ostateczne rozwiązanie.

Preferuj aktualne wdrażanie OpenClaw w Dockerze podczas nowej instalacji

W przypadku aktualnego wdrożenia skorzystaj z oficjalnego przewodnika instalacji OpenClaw w Dockerze, zamiast odtwarzać sekwencję rozwiązywania problemów z 2026 roku, naprawiając po kolei każdy błąd.

Aktualny OpenClaw udostępnia skrypt konfiguracji Dockera, który:

• buduje obraz bramy lub pobiera go;
• przeprowadza wdrażanie;
• generuje token bramy;
• zapisuje trwałą konfigurację;
• tworzy wymagane katalogi na sekrety;
• uruchamia bramę za pośrednictwem Docker Compose.

W przypadku bezgłowego wdrożenia Dockera aktualny OpenClaw dokumentuje również nieinteraktywne wdrażanie z lokalnym trybem bramy i uwierzytelnianiem tokenem. Jest to lepsze rozwiązanie niż ręczne wymyślanie zmiennych środowiskowych lub dodawanie nieobsługiwanych flag.

Aktualny wzorzec ręcznej konfiguracji

Aktualny przewodnik OpenClaw dotyczący Dockera opisuje wzorzec ręcznej konfiguracji równoważny z:

openclaw onboard --mode local --no-install-daemon
openclaw config set gateway.mode local
openclaw config set gateway.bind lan

W Docker Compose polecenia te są zwykle wykonywane za pośrednictwem dedykowanego kontenera CLI lub kontenera wdrożeniowego zdefiniowanego przez projekt. Nie wklejaj poleceń wykonywanych na hoście do gotowego obrazu CasaOS bez wcześniejszego sprawdzenia jego punktu wejścia i podpięć.

Aktualna dokumentacja OpenClaw Gateway CLI potwierdza, że polecenia openclaw setup i openclaw onboard --mode local tworzą wymaganą lokalną konfigurację bramy.

Używaj tego samego tokenu bramy w interfejsie Control UI

Aktualna dokumentacja OpenClaw dotycząca Dockera udostępnia interfejs Control UI na porcie 18789 w standardowej konfiguracji Compose i instruuje użytkowników, aby wkleili token bramy ze środowiska wdrożeniowego do ustawień interfejsu użytkownika.

Niezgodność tokenów może powodować błędy uwierzytelniania po prawidłowym uruchomieniu bramy, ale różni się od sytuacji, w której kontener wielokrotnie się zamyka, ponieważ nie istnieje konfiguracja. Najpierw zdiagnozuj uruchamianie, a dopiero potem uwierzytelnianie w interfejsie użytkownika.

Nie traktuj --allow-unconfigured jako stałego rozwiązania

OpenClaw udostępnia --allow-unconfigured dla uruchamiania doraźnego lub deweloperskiego. Aktualna dokumentacja wyraźnie wskazuje, że pomija to zabezpieczenie trybu lokalnego bez zapisywania ani naprawiania konfiguracji. Jest to przydatne do testów, ale nie zastępuje prawidłowego wdrożenia trwałego serwera.

Lista kontrolna rozwiązywania problemów z niedostępną usługą OpenClaw

1. Sprawdź, czy kontener OpenClaw działa, zakończył pracę, czy uruchamia się ponownie.
2. Przed zmianą ustawień przeczytaj dzienniki bieżącego kontenera.
3. Potwierdź OPENCLAW_GATEWAY_TOKEN istnieje i jest traktowany jako sekret.
4. Jeśli polecenia Dockera kończą się błędem odmowy dostępu do gniazda, użyj autoryzowanej powłoki administracyjnej zamiast osłabiać uprawnienia do gniazda Dockera.
5. Szukaj konkretnie Brak konfiguracji lub gateway.mode=local błędy.
6. Potwierdź, że ścieżka AppData na hoście jest zamontowana do katalogu konfiguracji OpenClaw oczekiwanego przez obraz.
7. Uruchom obsługiwany przez OpenClaw proces konfiguracji lub inicjalizacji, aby openclaw.json zostanie utworzony w trwałej pamięci masowej.
8. Nie polegaj na GATEWAY_MODE=local chyba że dokumentacja konkretnego obrazu wyraźnie to definiuje.
9. Nie dopisuj --gateway.mode=local do dowolnego polecenia kontenera CasaOS.
10. Uruchom ponownie kontener i ponownie sprawdź dzienniki po zapisaniu konfiguracji.
11. Dopiero gdy brama pozostanie uruchomiona, rozwiązuj problemy z uwierzytelnianiem tokenem w interfejsie sterowania lub z konfiguracją dostawcy modeli.

FAQ dotyczące niedostępności usługi OpenClaw

Czy OpenClaw wymaga OPENCLAW_GATEWAY_TOKEN?

Aktualne wdrożenia OpenClaw w Dockerze obsługują i często używają OPENCLAW_GATEWAY_TOKEN do uwierzytelniania bramy. Oficjalny skrypt instalacyjny może wygenerować taki token automatycznie. Pakiety i obrazy firm trzecich mogą udostępniać tę wartość w inny sposób, dlatego postępuj zgodnie z rzeczywistym schematem zmiennych środowiskowych danego obrazu.

Co oznacza „permission denied /var/run/docker.sock”?

Oznacza to, że bieżący użytkownik hosta nie ma dostępu do demona Dockera. Nie oznacza to samo w sobie, że wewnętrzny katalog danych OpenClaw nie pozwala na zapis. Do diagnostyki Dockera użyj autoryzowanego konta administracyjnego.

Jak ustawić gateway.mode=local?

Użyj obsługiwanego przez OpenClaw polecenia konfiguracji, wdrażania lub inicjalizacji, aby wartość została zapisana w trwałym openclaw.json. Aktualna dokumentacja mówi konfiguracja openclaw lub openclaw onboard --mode local tworzy to ustawienie.

Czy powinienem dodać GATEWAY_MODE=local?

Nie na podstawie tego wątku. Ta sugestia nie rozwiązała pętli ponownego uruchamiania pakietowego obrazu użytkownika, a aktualna dokumentacja projektu upstream traktuje gateway.mode jako konfigurację, a nie jako ogólną zmienną środowiskową o nazwie GATEWAY_MODE.

Dlaczego opcja --gateway.mode=local jest zgłaszana jako nieznana?

Ponieważ opcję dopisano do niewłaściwej warstwy polecenia w pakiecie CasaOS. Klucz konfiguracji z kropką nie jest automatycznie prawidłową flagą wiersza poleceń dla każdego pliku binarnego OpenClaw ani każdego punktu wejścia.

Czy problem opisany w wątku społeczności został definitywnie rozwiązany?

Wątek doprowadził do mocnej końcowej diagnozy — niezainicjowanego trwałego katalogu konfiguracji — i zalecał uruchomienie konfiguracja openclaw wewnątrz kontenera. Autor oryginalnego wpisu nie opublikował po tej ostatniej instrukcji ostatecznego potwierdzenia, więc strona nie powinna twierdzić, że problem został zweryfikowanie rozwiązany, jeśli źródło tego nie potwierdza.