Instalacja OpenClaw krok po kroku: VPS, Windows, Docker

Czego potrzebujesz, zanim wpiszesz pierwszą komendę

Wymagania są krótkie i dwa z nich wywracają instalację natychmiast, więc sprawdź je przed startem. Node musi być w wersji 22.22.3 lub nowszej, 24.15 lub nowszej albo 25.9 lub nowszej; jako domyślny dokumentacja poleca dziś Node 26, a instalator skryptowy sam go dostarcza, gdy Node'a w systemie nie ma. Bun nie uruchomi CLI ani Gateway, bo brakuje mu obsługi node:sqlite. pnpm jest potrzebny wyłącznie przy budowaniu ze źródeł.

Sprzęt jest łaskawy. Minimum to 1 vCPU, 1 GB RAM, 500 MB wolnego dysku i system 64-bitowy. Tabela zgodności z FAQ pierwszego uruchomienia stawia Raspberry Pi 5 z 4 lub 8 GB jako wariant najlepszy, a Pi 4 z 4 GB jako dobry. Pi 4 z 2 GB działa po dodaniu swapa, a Pi Zero 2W z 512 MB nie jest polecany. Jeden wyjątek psuje ten obraz: budowanie obrazu Dockera wymaga co najmniej 2 GB RAM, bo na hoście z 1 GB pnpm install bywa ubijany przez OOM z kodem 137.

System operacyjny to macOS, Linux albo Windows. Na Windowsie masz do wyboru instalację natywną, WSL2 i aplikację Hub — do tego wracam w osobnej sekcji. Do kompletu potrzebny jest klucz API providera modelu, na przykład Anthropic, OpenAI albo Google; alternatywą jest lokalny model w Ollamie lub LM Studio.

Ostatnia rzecz do przygotowania nie jest techniczna. Zdecyduj, gdzie ten proces ma stać na stałe, zanim go postawisz. Instalacja na laptopie „na próbę” kończy się zwykle tym, że po dwóch tygodniach przenosisz cały katalog stanu na serwer i uczysz się o właścicielstwie plików w najgorszym możliwym momencie.

node --version
openclaw --version

Droga pierwsza: VPS albo Raspberry Pi

To najczęstszy wybór i najbardziej przewidywalny. Na serwerze bez ekranu instalujesz pakiet globalnie i uruchamiasz kreator z flagą instalującą usługę: npm i -g openclaw@latest, potem openclaw onboard --install-daemon. Gateway ląduje domyślnie jako jednostka systemd na poziomie użytkownika, więc wstaje po restarcie maszyny bez dodatkowej pracy.

Panel jest wystawiony na 127.0.0.1, czyli z zewnątrz niedostępny — i tak ma zostać. Przewodnik dla Hetznera stawia sprawę jednoznacznie: Gateway siedzi na loopbacku, a Ty dostajesz się do niego tunelem SSH. Komenda to ssh -N -L 18789:127.0.0.1:18789 <użytkownik>@<host>, a potem otwierasz http://127.0.0.1:18789/ w przeglądarce na własnym laptopie. Jeśli tunel nie chce wstać, sprawdź AllowTcpForwarding local w /etc/ssh/sshd_config.

Cała ścieżka na świeżym VPS-ie z Dockerem zajmuje według dokumentacji około 20 minut. Bez Dockera, samym npm, schodzi to poniżej dziesięciu, o ile Node jest w dobrej wersji. Sumienne przejście przez firewall i uprawnienia dołoży kolejne pół godziny i jest to czas dobrze wydany.

Instalator skryptowy działa tak samo na macOS, Linuksie i w WSL2: curl -fsSL https://openclaw.ai/install.sh | bash. Wybór między nim a npm to kwestia gustu. Skrypt dowozi Node'a, gdy go brakuje; npm zakłada, że masz go już we właściwej wersji.

npm i -g openclaw@latest
openclaw onboard --install-daemon
ssh -N -L 18789:127.0.0.1:18789 <użytkownik>@<host>

Droga druga: Windows natywnie, przez WSL2 albo z aplikacją Hub

Windows ma trzy warianty i różnią się bardziej, niż wygląda. Instalacja natywna idzie jedną linijką w PowerShellu: iwr -useb https://openclaw.ai/install.ps1 | iex, a zarządzany start korzysta z Harmonogramu zadań Windows, jeśli jest dostępny. WSL2 dokumentacja opisuje jako środowisko najbardziej zgodne z Linuksem i poleca je przy pracy bez ekranu. Trzecia droga to aplikacja Hub.

Windows Hub to natywny towarzysz dla Windows 10 w wersji 20H2 lub nowszej oraz Windows 11. Instaluje się bez uprawnień administratora, ma podpisane instalatory x64 i ARM64, a w środku daje status w zasobniku, start przy logowaniu, kreator pierwszego uruchomienia lokalnego Gateway w WSL, natywne okno czatu i Command Center z diagnostyką sesji, kanałów, node'ów i parowania. To najkrótsza droga dla kogoś, kto nie chce mieszkać w terminalu.

Ograniczenia WSL-a lepiej znać z góry, bo generują najwięcej pytań. WSL ma własną sieć wirtualną, więc dostęp z sieci lokalnej wymaga przekierowania portu. Zdalne node'y nie mogą używać adresu 127.0.0.1. WebChat przy zdalnym Gateway potrzebuje HTTPS albo localhosta.

Wariant czwarty leży poza dokumentacją projektu i wspominam o nim raz. ClawLabs Office uruchamia na Windowsie lokalny silnik OpenClaw z polskim modelem Bielik, bez chmury i bez konfiguracji serwera, a przy okazji działa jako most do agenta w chmurze przez szyfrowany tunel SSH.

iwr -useb https://openclaw.ai/install.ps1 | iex
openclaw onboard --install-daemon

Droga trzecia: Docker i chmura kontenerowa

Obraz oficjalny leży w dwóch miejscach: ghcr.io/openclaw/openclaw:latest jako podstawowy oraz openclaw/openclaw:latest jako mirror na Docker Hubie. Warianty tagów to między innymi -slim i -browser, obok tagów konkretnych wersji. Dokumentacja odradza nieoficjalne mirrory i zaznacza, że obraz oficjalny zawiera pluginy codex oraz diagnostics-otel.

Najprostsza droga to skrypt z repozytorium: ./scripts/docker/setup.sh. Konfiguruje Compose, przeprowadza kreator, generuje token Gateway i zapisuje go do pliku .env, tworzy katalogi sekretów profili auth i startuje kontener. Chcąc użyć gotowego obrazu zamiast lokalnego builda, ustaw wcześniej zmienną OPENCLAW_IMAGE.

Tu siedzi pułapka, która zjada ludziom wieczory. Domyślny tryb bindowania to loopback, czyli 127.0.0.1 — wewnątrz kontenera, a nie na hoście. Przy zwykłym mapowaniu -p 18789:18789 ruch wchodzi na interfejs kontenera i Gateway pozostaje nieosiągalny. Oficjalny setup.sh ustawia z tego powodu tryb lan; składając Compose samodzielnie, musisz zmienić gateway.bind świadomie i jednocześnie zadbać o uwierzytelnianie. W gateway.bind wpisuje się nazwy trybów — lan, loopback, custom, tailnet, auto — a nie adresy w rodzaju 0.0.0.0 czy 127.0.0.1.

Druga pułapka to właścicielstwo plików. Obraz działa jako użytkownik node z uid 1000, więc podmontowane katalogi muszą do niego należeć. Rozjazd kończy się błędami EACCES albo komunikatem o podejrzanym właścicielstwie przy ładowaniu pluginu, a naprawia go sudo chown -R 1000:1000 na katalogu konfiguracji i workspace, po którym uruchamiasz openclaw doctor --fix.

export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"
./scripts/docker/setup.sh
sudo chown -R 1000:1000 <katalog-konfiguracji> <katalog-workspace>

Pierwszy start: co zobaczysz i co zrobić po kolei

Kreator openclaw onboard prowadzi przez wybór providera modelu, ustawienie klucza API i konfigurację Gateway. Wykrywa dostępne poświadczenia i wymaga żywego testu odpowiedzi, zanim cokolwiek zapisze — to celowe, bo klucz z literówką ujawniłby się inaczej dopiero przy pierwszej wiadomości. Flaga --install-daemon instaluje zarządzany Gateway jako usługę, a --skip-daemon ją pomija.

Po kreatorze sprawdzasz dwie rzeczy. openclaw gateway status ma pokazać Gateway nasłuchujący na porcie 18789, a openclaw dashboard otwiera Control UI w przeglądarce. Przy sesji graficznej przeglądarka odpali się sama; na maszynie bez ekranu kreator wypisuje adres do skopiowania razem z instrukcją przekierowania portu przez SSH i czeka na połączenie do pięciu minut.

Panel poprosi o token. Znajdziesz go w konfiguracji pod kluczem gateway.auth.token, a w wariancie dockerowym w pliku .env zapisanym przez skrypt. Jeśli tokenu nie ma, wygenerujesz go komendą openclaw doctor --generate-gateway-token. Po wklejeniu w ustawieniach panelu dostajesz czat.

Test pierwszej wiadomości jest ważniejszy, niż wygląda. Kiedy agent odpowie, masz potwierdzony komplet: działający Gateway, poprawne poświadczenia providera i wybrany model. Dopiero wtedy ma sens podłączanie kanałów — o tym mówią kolejne lekcje tej ścieżki.

openclaw gateway status
openclaw dashboard
openclaw doctor --generate-gateway-token

Gdzie ludzie utykają najczęściej

Pierwsze miejsce to wersja Node'a. Instalacja przechodzi, a Gateway wywala się przy starcie na czymś, co wygląda na błąd składni, bo runtime jest za stary. Drugi wariant tego samego problemu: ktoś próbuje uruchomić CLI Bunem, a Bun nie ma node:sqlite i nie wystartuje. Sprawdzenie node --version przed instalacją załatwia oba przypadki.

Drugie miejsce to panel na maszynie bez ekranu. Gateway działa, port 18789 nasłuchuje, tylko nikt nie wie, jak się do niego dostać — i zaczyna się wystawianie na 0.0.0.0, czego dokumentacja zabrania wprost bez uwierzytelniania. Właściwa droga to tunel SSH, Tailscale Serve albo reverse proxy świadome tożsamości.

Trzecie miejsce to zawieszony kreator. Klasyczny objaw: onboarding zatrzymuje się na próbie obudzenia agenta i nie dostaje odpowiedzi. Dokumentacja podaje wtedy openclaw gateway restart, a gdy to nie pomaga — openclaw models status do sprawdzenia poświadczeń providera oraz openclaw configure --section model, jeśli model w ogóle nie został wybrany.

Czwarte i piąte to sprawy dockerowe opisane wyżej: bind i właścicielstwo katalogów. Uzupełnia je rutyna działająca niezależnie od tego, co się zepsuło — openclaw status, openclaw doctor i openclaw logs --follow w tej kolejności. Do zgłoszenia gdzieś dalej użyj openclaw status --all, bo to diagnoza tylko do odczytu z wyciętymi tokenami. Instalator można też przepuścić ponownie z wymuszoną metodą: curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method npm.

openclaw status
openclaw doctor
openclaw logs --follow
openclaw status --all

Dwie czynności przed pierwszym kanałem

Panel bez tokenu nie wpuści Cię dalej, a token wygenerujesz jedną komendą: openclaw doctor --generate-gateway-token. Wynik ląduje w konfiguracji, skąd wklejasz go w ustawieniach Control UI. W wariancie dockerowym zrobił to już za Ciebie skrypt setup.sh, zapisując wartość do pliku .env.

Druga czynność to uprawnienia i zajmuje dwie linijki. Dokumentacja zaleca 700 na katalogu ~/.openclaw i 600 na pliku ~/.openclaw/openclaw.json, bo w środku leżą poświadczenia kanałów, tokeny OAuth i transkrypty sesji. Zrób to teraz, dopóki katalog jest pusty i nie ma czego pilnować.

Ekspozycja sieciowa, tryby uwierzytelniania, sandbox i reguły zapory to lekcja dwudziesta szósta — zrób ją, zanim wystawisz cokolwiek poza loopback. Kopie zapasowe i plan powrotu to lekcja dwudziesta ósma.

openclaw doctor --generate-gateway-token
chmod 700 ~/.openclaw
chmod 600 ~/.openclaw/openclaw.json

Ile to zajmuje naprawdę i kiedy odpuścić

Optymistyczny rachunek wygląda tak: 2–5 minut instalacji, kilka minut kreatora, około 20 minut pełnej ścieżki na VPS z Dockerem. Realistyczny dokłada do tego czas na wersję Node'a, tunel SSH i pierwsze potyczki z bindem. Przy pierwszym podejściu zaplanuj popołudnie. Przy drugim wystarczy kwadrans.

Utrzymanie ciągnie się dalej. Kurs liczy utrzymanie agenta na platformie zarządzanej na półtorej do dwóch godzin miesięcznie — ten przedział stoi w lekcji piętnastej. Self-host dokłada aktualizacje silnika przez openclaw update, kopie przed każdą zmianą, rotację tokenów kanałów i restarty po awariach, więc z praktyki wychodzi trzy do czterech godzin miesięcznie, czyli 204–272 zł przy stawce 68 zł za godzinę.

Odpuść self-host, jeśli po dwóch godzinach walki z instalacją nie masz działającego czatu i nikogo, kto obejrzy to z Tobą. Zdolności nie mają z tym wiele wspólnego — diagnostyka bez kogoś obok bywa dłuższa niż cała reszta uruchomienia. Gotowa instancja w chmurze EU startuje w około 60 sekund i kosztuje od 399 zł miesięcznie. Same godziny utrzymania self-hostu wycenione po 68 zł to 204–272 zł, więc różnica na papierze wynosi 130–195 zł — dopóki nie dołożysz do niej VPS-a, tokenów i tego, że o drugiej w nocy nie ma do kogo zadzwonić.

Jeśli instalacja się udała, kolejne lekcje tej ścieżki wchodzą głębiej: konfiguracja w openclaw.json, polityki dostępu na kanałach, cron i utrzymanie. Wszystkie zakładają, że masz działający Gateway i potrafisz otworzyć panel. Ten etap masz już za sobą.