OpenClaw: Najczęstsze problemy, błędy i ich rozwiązania

Masz OpenClaw. Przeszedłeś przez instalację. Może nawet podążałeś za naszym przewodnikiem instalacji i konfiguracji. A potem - coś się wysypało. Terminal krzyczy czerwonym tekstem, odpowiedzi nie przychodzą, Docker zachowuje się jakby miał własne zdanie na temat Twojej sieci. Znamy to. Naprawiamy to dosłownie codziennie.

Ten artykuł nie jest teoretycznym omówieniem „co może pójść nie tak". To konkretna lista problemów, które ludzie faktycznie napotykają, z konkretnymi rozwiązaniami, które faktycznie działają. Bez owijania w bawełnę.

Problem #1: npm build failures - „nie mogę zbudować projektu"

To jest absolutny klasyk. Wpisujesz npm run build albo npm install, a terminal zwraca ścianę błędów. Zanim zaczniesz losowo googlować fragmenty error logów, sprawdź kilka rzeczy po kolei.

Pierwsza przyczyna to wersja Node.js. OpenClaw wymaga Node.js w wersji 22 lub wyższej. Jeśli masz starszą wersję, build się nie powiedzie i komunikaty błędów będą kompletnie mylące - nie powiedzą Ci wprost „masz za starą wersję Node". Zamiast tego dostaniesz kryptyczne komunikaty o brakujących funkcjach lub nieobsługiwanych składniach. Sprawdź swoją wersję wpisując node --version w terminalu. Jeśli widzisz cokolwiek poniżej 22, musisz zaktualizować. Najłatwiej przez nvm (Node Version Manager) - nvm install 22 i po problemie.

Druga przyczyna to uszkodzony cache npm. Jeśli wcześniej przerywałeś instalację, zmieniałeś wersję Node albo majstrowałeś przy node_modules, cache npm może być w stanie, który uniemożliwia prawidłową instalację. Rozwiązanie jest brutalne, ale skuteczne: usuń folder node_modules, usuń plik package-lock.json i uruchom npm install od nowa. Tak, to potrwa dłużej. Tak, to jedyny pewny sposób.

Trzecia przyczyna, o której mało kto pisze, to problemy z uprawnieniami na Linuxie. Jeśli kiedykolwiek uruchomiłeś npm install z sudo, pliki w node_modules mogą mieć złe uprawnienia. Każda kolejna próba instalacji bez sudo się wysypie, a z sudo - pogłębi problem. Rozwiązanie: sudo chown -R $(whoami) node_modules albo, lepiej, zacznij od czystego katalogu z prawidłowymi uprawnieniami.

Czwarta przyczyna to konflikty zależności. OpenClaw zależy od wielu pakietów, a te pakiety zależą od swoich pakietów. Czasem nowa wersja jednej biblioteki łamie kompatybilność z inną. Jeśli widzisz błędy typu ERESOLVE unable to resolve dependency tree, spróbuj npm install --legacy-peer-deps. To nie jest eleganckie rozwiązanie, ale w większości przypadków pozwala przejść dalej.

Problem #2: sharp i better-sqlite3 na macOS - natywne moduły, które odmawiają współpracy

To jest problem, który dotyka przede wszystkim użytkowników macOS, szczególnie tych z procesorami Apple Silicon (M1, M2, M3, M4). Moduły sharp (do przetwarzania obrazów) i better-sqlite3 (do lokalnej bazy danych) wymagają kompilacji natywnego kodu C/C++. Na macOS oznacza to, że potrzebujesz Xcode Command Line Tools.

Jeśli nigdy ich nie instalowałeś, wystarczy wpisać xcode-select --install w terminalu. Jeśli instalowałeś je dawno temu, a potem aktualizowałeś macOS, mogą być w niedziałającym stanie. W takim przypadku musisz je przeinstalować: sudo rm -rf /Library/Developer/CommandLineTools a potem ponownie xcode-select --install.

Problem z sharp na Apple Silicon jest szczególnie podstępny. Moduł musi być skompilowany dla architektury arm64, ale jeśli masz zainstalowany Node.js przez Rosettę (emulację x86), npm zainstaluje wersję x86 sharp, która nie będzie działać z natywnym Node. Sprawdź architekturę swojego Node.js: node -p process.arch. Jeśli widzisz x64 na Macu z Apple Silicon, masz problem. Odinstaluj Node i zainstaluj go ponownie bez Rosetty - najlepiej przez nvm albo bezpośrednio z nodejs.org (wersja ARM64).

Z better-sqlite3 problem jest podobny, ale dochodzi jeszcze kwestia Pythona. Kompilacja natywnych modułów Node.js wymaga Pythona 3 i narzędzia node-gyp. Jeśli node-gyp nie może znaleźć Pythona, build się wysypie. Na macOS Python jest preinstalowany, ale w starszych wersjach systemu to Python 2, który nie jest obsługiwany. Upewnij się, że python3 --version zwraca coś sensownego.

Jeśli nic z tego nie pomaga, jest rozwiązanie nuklearne: npm rebuild przebudowuje wszystkie natywne moduły od zera. W skrajnych przypadkach musisz ręcznie przebudować konkretny moduł: npm rebuild sharp --platform=darwin --arch=arm64.

Warto tu wspomnieć, że w naszym przewodniku bezpieczeństwa OpenClaw omawiamy dlaczego te natywne moduły są istotne - better-sqlite3 przechowuje lokalnie dane konwersacji, a sharp przetwarza obrazy, które mogą zawierać wrażliwe treści.

Problem #3: Docker networking - „kontener działa, ale nic nie widzi"

Docker to teoretycznie najłatwiejszy sposób na uruchomienie OpenClaw. W praktyce Docker wprowadza warstwę sieciową, która potrafi wygenerować problemy niewidoczne przy bezpośrednim uruchomieniu.

Najczęstszy scenariusz: OpenClaw w Dockerze nie może połączyć się z API providera (OpenAI, Anthropic, lokalny Ollama). Kontener działa, logi wyglądają normalnie, ale odpowiedzi nie przychodzą albo pojawiają się timeouty.

Pierwsza rzecz do sprawdzenia to tryb sieciowy Dockera. Domyślnie Docker tworzy własną sieć (bridge), a kontenery mają własne adresy IP. Jeśli Twój provider API jest dostępny na localhost, kontener go nie widzi - bo localhost wewnątrz kontenera to sam kontener, nie Twój komputer. Rozwiązanie dla Linuxa: użyj --network=host przy uruchamianiu kontenera. Dla macOS i Windows: użyj specjalnego hostname host.docker.internal zamiast localhost w konfiguracji.

Drugi problem to DNS. Kontenery Docker używają domyślnie serwera DNS Googla (8.8.8.8). Jeśli jesteś w sieci firmowej z własnym DNS albo masz VPN, kontener może nie być w stanie rozwiązać nazw domen. Objaw: błędy typu ENOTFOUND api.openai.com. Rozwiązanie: dodaj --dns do polecenia docker run z adresem Twojego lokalnego DNS, albo skonfiguruj DNS w docker-compose.yml.

Trzeci problem dotyczy portów. Jeśli OpenClaw ma wystawić web UI na porcie 3000, musisz zmapować ten port: -p 3000:3000. Bez tego kontener działa, UI działa wewnątrz kontenera, ale z przeglądarki na Twoim komputerze nic nie zobaczysz. To brzmi banalnie, ale zapominanie o mapowaniu portów to jeden z najczęstszych błędów.

Czwarty problem to wolumeny i uprawnienia do plików. Jeśli montujesz lokalny katalog z konfiguracją do kontenera (np. -v ./config:/app/config), uprawnienia plików mogą być niezgodne. Kontener domyślnie uruchamia procesy jako root, a Twoje lokalne pliki mogą mieć inne uprawnienia. Efekt: OpenClaw albo nie może odczytać konfiguracji, albo nie może zapisać logów i bazy danych.

Piąty, rzadszy problem: firewalle i polityki sieciowe. Na niektórych systemach Linux (szczególnie z SELinux lub AppArmor) Docker może mieć ograniczone uprawnienia sieciowe. Jeśli wszystko inne wygląda dobrze, a kontener nadal nie może się połączyć - sprawdź logi systemowe pod kątem blokad.

Problem #4: puste odpowiedzi - „OpenClaw działa, ale nic nie odpowiada"

Ten problem jest szczególnie frustrujący, bo technicznie wszystko wygląda dobrze. Serwer działa, interfejs się ładuje, pytania się wysyłają, ale odpowiedzi są puste albo pojawia się ogólnikowy komunikat o błędzie.

Przyczyna numer jeden, którą widzimy najczęściej i która jest jednocześnie najgłupsza: spacja na końcu klucza API. Tak, dosłownie. Kopiujesz klucz API z panelu OpenAI lub Anthropic, wklejasz do pliku .env i nie zauważasz, że na końcu wkradła się spacja lub znak nowej linii. Klucz API ze spacją na końcu jest traktowany jako inny klucz - autoryzacja się nie powiedzie, ale komunikat błędu często nie mówi wprost „zły klucz". Zamiast tego dostajesz pustą odpowiedź lub enigmatyczny error 401.

Rozwiązanie: otwórz plik .env, przejdź do linii z kluczem API i upewnij się, że po ostatnim znaku klucza nie ma żadnych dodatkowych znaków. Żadnych spacji, żadnych tabulatorów, żadnych niewidocznych znaków. W vimie możesz to zobaczyć wpisując :set list - niewidoczne znaki zostaną oznaczone. W VS Code włącz renderowanie białych znaków (View > Render Whitespace).

Przyczyna numer dwa: niewłaściwy model w konfiguracji. Jeśli w konfiguracji masz ustawiony model, do którego Twój klucz API nie ma dostępu (np. gpt-4 przy kluczu z darmowego planu), zapytanie się nie powiedzie. Niektóre modele wymagają osobnego dostępu - np. GPT-4 Turbo wymagał wcześniej oddzielnej rejestracji. Sprawdź w panelu dostawcy, do których modeli masz faktyczny dostęp.

Przyczyna numer trzy: przekroczony limit wydatków lub wyczerpane kredyty. OpenAI i Anthropic mają systemy limitów. Jeśli Twoje konto nie ma środków albo osiągnęło limit miesięczny, API po prostu odmówi obsługi żądań. Komunikat błędu powinien to wskazywać, ale nie zawsze jest czytelnie przekazywany przez OpenClaw do interfejsu użytkownika.

Przyczyna numer cztery: problem z kontekstem konwersacji. Jeśli historia konwersacji jest zbyt długa, żądanie do API może przekroczyć limit tokenów. Efekt: API odrzuca żądanie, a OpenClaw zwraca pustą odpowiedź. Rozwiązanie: zacznij nową konwersację albo zmniejsz parametr kontekstu w konfiguracji.

Problem #5: WhatsApp pairing - parowanie nie działa lub się rozłącza

Integracja WhatsApp to jedna z najbardziej pożądanych funkcji OpenClaw i jednocześnie jedno z największych źródeł problemów. WhatsApp nie oferuje oficjalnego API dla tego typu integracji (poza WhatsApp Business API, które wymaga weryfikacji firmy). OpenClaw korzysta z nieoficjalnego protokołu, co oznacza, że parowanie jest kruche z natury.

Najczęstszy problem: kod parowania pojawia się, skanujesz go w WhatsApp, ale połączenie się nie ustanawia albo zrywa się po kilku minutach. Przyczyny mogą być różne. Po pierwsze, konto WhatsApp może być jednocześnie podłączone do zbyt wielu urządzeń (limit to 4 urządzenia połączone). Po drugie, jeśli sesja się zrywa i próbujesz natychmiast ponownie sparować, musisz poczekać - WhatsApp ma wewnętrzny cooldown na ponowne parowanie.

Jest też poważniejszy problem bezpieczeństwa, udokumentowany w GitHub Issue #5144: kod parowania może wyciec do logów. Jeśli masz włączone logowanie na poziomie debug, kod QR lub kod numeryczny parowania może zostać zapisany w logach w formie jawnej. Każdy, kto ma dostęp do logów, może teoretycznie przejąć Twoją sesję WhatsApp. To nie jest teoretyczne zagrożenie - to realne ryzyko, szczególnie jeśli uruchamiasz OpenClaw na współdzielonym serwerze.

Rozwiązanie doraźne: upewnij się, że logowanie jest ustawione na poziom info lub warning, nie debug, podczas parowania WhatsApp. Po sparowaniu zresetuj logi. Rozwiązanie systemowe: profesjonalna instalacja, w której sesja WhatsApp jest izolowana, a logi są odpowiednio filtrowane.

Jeśli interesuje Cię głębsza analiza integracji WhatsApp z OpenClaw, przeczytaj nasz dedykowany artykuł o konfiguracji WhatsApp w OpenClaw, gdzie omawiamy temat znacznie szerzej.

Problem #6: rate limiting - „zbyt wiele żądań"

Rate limiting to mechanizm, który ogranicza liczbę żądań, jakie możesz wysłać do API w określonym czasie. Każdy dostawca AI ma swoje limity i jeśli je przekroczysz, zamiast odpowiedzi dostaniesz błąd 429 (Too Many Requests).

Problem pojawia się szczególnie wtedy, gdy używasz OpenClaw intensywnie - wiele konwersacji jednocześnie, długie konteksty, częste zapytania. Na darmowych lub tanich planach limity są restrykcyjne. Dostawcy jak OpenAI, Anthropic czy Google stosują różne limity w zależności od planu i modelu - tańsze modele mają wyższe limity, najsilniejsze modele mają niższe. Konkretne liczby zmieniają się regularnie, więc sprawdź aktualną dokumentację swojego dostawcy.

Co się dzieje w praktyce: wysyłasz pytanie, czekasz, czekasz, i po jakimś czasie dostajesz komunikat o błędzie albo po prostu nic się nie dzieje. OpenClaw nie zawsze obsługuje błędy rate limitingu w sposób zrozumiały dla użytkownika - czasem po prostu „wisi".

Rozwiązania są trzy. Pierwsze: podnieś swój plan u dostawcy API. Więcej płacisz, wyższe limity masz. Drugie: skonfiguruj OpenClaw do używania kolejkowania żądań, jeśli Twoja wersja to obsługuje. Trzecie: rozłóż użycie w czasie - nie próbuj testować 20 konwersacji jednocześnie.

Warto też wiedzieć, że rate limiting działa per klucz API, nie per instalacja. Jeśli masz ten sam klucz w OpenClaw i w innych aplikacjach, wszystkie dzielą ten sam limit.

Problem #7: aktualizacje i migracje - „zaktualizowałem i wszystko się zepsuło"

OpenClaw jest aktywnie rozwijany, co jest zarówno zaletą, jak i źródłem problemów. Aktualizacje mogą zmienić format konfiguracji, strukturę bazy danych, wymagane zmienne środowiskowe. Jeśli zaktualizujesz bezrefleksyjnie (np. git pull i npm install), możesz wylądować w stanie, gdzie stara konfiguracja nie pasuje do nowego kodu.

Przed każdą aktualizacją zrób trzy rzeczy. Po pierwsze: przeczytaj changelog. Serio. Nikt tego nie robi i potem wszyscy narzekają. Changelog powie Ci, czy są breaking changes. Po drugie: zrób backup konfiguracji i bazy danych. Skopiuj folder z danymi OpenClaw w bezpieczne miejsce. Po trzecie: jeśli aktualizacja jest duża (zmiana major version), rozważ czystą instalację zamiast aktualizacji in-place.

Jeśli już zaktualizowałeś i wszystko się zepsuło, nie panikuj. Sprawdź, czy w repozytorium jest skrypt migracyjny. Porównaj swój plik konfiguracyjny z przykładowym plikiem konfiguracyjnym z nowej wersji. Często problem to brakująca nowa zmienna środowiskowa, którą trzeba dodać do .env.

Potrzebujesz pomocy z OpenClaw?

Bądźmy szczerzy. Jeśli dotarłeś do tego miejsca w artykule i nadal masz problem, to jest spora szansa, że Twoja sytuacja wymaga więcej niż skopiowania polecenia z bloga. Niektóre problemy są wynikiem specyficznej kombinacji systemu operacyjnego, wersji oprogramowania, konfiguracji sieciowej i oczekiwań użytkownika, których nie da się pokryć żadnym poradnikiem.

Naprawiamy instalacje OpenClaw regularnie. Widzimy te same problemy w kółko i wiemy, jak je rozwiązywać szybko. Profesjonalna instalacja to nie jest kwestia prestiżu - to kwestia czasu. Możesz spędzić weekend debugując problem z sharp na macOS, albo możesz mieć działającą instalację w kilka godzin.

Co dostajesz przy profesjonalnej instalacji przez Syntalith:

Prawidłowo skonfigurowane środowisko, które nie wysypie się przy pierwszej aktualizacji. Izolowane sesje WhatsApp bez ryzyka wycieku kodu parowania. Monitoring, który powie Ci o problemie zanim sam go zauważysz. I wsparcie - nie forum na GitHubie, gdzie Twoje pytanie zniknie w szumie, tylko bezpośredni kontakt z ludźmi, którzy wiedzą, co robią.

Nie próbujemy Cię naciągnąć na usługę, której nie potrzebujesz. Jeśli Twój problem to spacja w kluczu API, to naprawdę wystarczy usunąć tę spację. Ale jeśli Twoja firma chce używać OpenClaw produkcyjnie, z WhatsApp, z wieloma użytkownikami, z odpowiednim bezpieczeństwem - to nie jest projekt weekendowy. To jest infrastruktura, która wymaga profesjonalnego podejścia.

Podsumowanie: szybka ściągawka

Zanim skontaktujesz się z nami, przejdź przez tę listę kontrolną. Większość problemów rozwiązuje jeden z tych kroków.

Node.js musi być w wersji 22 lub wyższej. Klucz API nie może mieć spacji na końcu. Na macOS z Apple Silicon Node.js musi działać natywnie, nie przez Rosettę. Docker wymaga prawidłowego mapowania portów i DNS. Aktualizacje wymagają przeczytania changelogu. WhatsApp pairing wymaga ustawienia logowania na poziom nie niższy niż info.

Jeśli po przejściu przez tę listę nadal masz problem, albo jeśli nie chcesz w ogóle przechodzić przez te wszystkie kroki - napisz do nas. Instalujemy, konfigurujemy i utrzymujemy OpenClaw dla firm, które wolą mieć działające narzędzie niż projekt do debugowania. Kontakt: contact@syntalith.ai, telefon +48 888 78 48 78. Odpowiadamy w ciągu jednego dnia roboczego.