agents.defaults.sandbox, ale piaskownica jest domyślnie wyłączona i nie wymaga uruchamiania samego Gateway w Dockerze. Dostępne są również backendy piaskownicy SSH i OpenShell; zobacz Piaskownica.
Obsługujesz wielu użytkowników? Model jednej komórki na dzierżawcę opisano w sekcji Hosting wielodostępny.
Wymagania wstępne
- Docker Desktop (lub Docker Engine) + Docker Compose v2
- Co najmniej 2 GB pamięci RAM na zbudowanie obrazu (
pnpm installmoże zostać zakończony przez mechanizm OOM na hostach z 1 GB pamięci, z kodem wyjścia 137) - Wystarczająca ilość miejsca na dysku na obrazy i dzienniki
- Na serwerze VPS lub hoście publicznym należy zapoznać się z sekcją Zabezpieczenia przed dostępem sieciowym, zwłaszcza z łańcuchem zapory
DOCKER-USERDockera
Gateway w kontenerze
Zbuduj obraz
openclaw:local. Aby zamiast tego użyć gotowego obrazu:openclaw/openclaw:ghcr.io/openclaw/openclaw lub openclaw/openclaw i unikać nieoficjalnych kopii, które nie stosują harmonogramu wydań ani zasad przechowywania OpenClaw. Oficjalne tagi: main, latest, <version> (np. 2026.2.26) oraz tagi wersji beta, takie jak 2026.2.26-beta.1 (wersje beta nigdy nie zmieniają latest/main). Domyślny obraz main/latest/<version> zawiera pluginy codex i diagnostics-otel. Dostępny jest także wariant -browser (np. latest-browser) z wbudowanym Chromium, przydatny dla narzędzia przeglądarki w piaskownicy bez konieczności instalowania Playwright przy pierwszym uruchomieniu.Ponowne uruchomienie bez dostępu do sieci
--offline sprawdza, czy OPENCLAW_IMAGE istnieje już lokalnie, wyłącza niejawne pobieranie i budowanie przez Compose, a następnie wykonuje standardową procedurę: synchronizację .env, korekty uprawnień, konfigurację początkową, synchronizację konfiguracji Gateway i uruchomienie Compose.Jeśli OPENCLAW_SANDBOX=1, konfiguracja offline sprawdza również skonfigurowane domyślne obrazy piaskownicy i obrazy poszczególnych agentów w demonie wskazywanym przez OPENCLAW_DOCKER_SOCKET, w tym etykietę kontraktu przeglądarki na obrazach przeglądarki opartych na Dockerze. Jeśli wymagany obraz nie istnieje lub jest nieaktualny, konfiguracja kończy się bez zmiany konfiguracji piaskownicy, zamiast błędnie zgłaszać powodzenie.Dokończ konfigurację początkową
- prosi o klucze API dostawcy
- generuje token Gateway i zapisuje go w
.env - tworzy katalog klucza tajnego profilu uwierzytelniania
- uruchamia Gateway za pomocą Docker Compose
openclaw-gateway (z --no-deps --entrypoint node), ponieważ openclaw-cli współdzieli przestrzeń nazw sieci Gateway i działa dopiero po utworzeniu kontenera Gateway.Otwórz interfejs sterowania
http://127.0.0.1:18789/ i wklej token zapisany w .env w Settings. Jeśli kontener przełączono na uwierzytelnianie hasłem, zamiast tokenu należy użyć tego hasła.Potrzebujesz ponownie adresu URL?Procedura ręczna
.git. Należy przekazać tożsamość źródła jako argumenty kompilacji,
jak pokazano powyżej, aby ekran Informacje obrazu wyświetlał pobrany commit i
jeden znacznik czasu kompilacji. scripts/docker/setup.sh automatycznie ustala i przekazuje obie wartości.
docker compose należy uruchamiać z katalogu głównego repozytorium. Jeśli włączono OPENCLAW_EXTRA_MOUNTS lub OPENCLAW_HOME_VOLUME, skrypt konfiguracyjny zapisuje docker-compose.extra.yml; należy dołączyć go po każdym samodzielnie utrzymywanym docker-compose.override.yml, np. -f docker-compose.yml -f docker-compose.override.yml -f docker-compose.extra.yml.Uaktualnianie obrazów kontenerów
Po zastąpieniu obrazu OpenClaw przy zachowaniu tego samego zamontowanego stanu i konfiguracji nowy Gateway przed osiągnięciem gotowości wykonuje bezpieczne podczas uruchamiania migracje aktualizacyjne i uzgadnianie pluginów. Rutynowe uaktualnienia obrazu nie powinny wymagać osobnego uruchomieniaopenclaw doctor --fix.
Jeśli podczas uruchamiania nie można bezpiecznie ukończyć tych napraw, Gateway kończy działanie, zamiast
zgłaszać prawidłowy stan. Przy skonfigurowanych zasadach ponownego uruchamiania Docker, Podman lub Kubernetes może wskazywać,
że kontener Gateway jest ponownie uruchamiany. Należy zachować zamontowany wolumin stanu, a następnie jednokrotnie uruchomić
ten sam obraz z openclaw doctor --fix jako poleceniem kontenera, używając
tych samych punktów montowania stanu i konfiguracji co Gateway:
Zmienne środowiskowe
Opcjonalne zmienne obsługiwane przezscripts/docker/setup.sh (a w przypadku kontenera Gateway również bezpośrednio przez docker-compose.yml):
brew; zależności te należy dostarczyć za pomocą niestandardowego obrazu lub zainstalować ręcznie. Należy użyć OPENCLAW_IMAGE_APT_PACKAGES w przypadku zależności z pakietów Debiana oraz OPENCLAW_IMAGE_PIP_PACKAGES w przypadku zależności Pythona (podczas budowania uruchamiane jest python3 -m pip install --break-system-packages, dlatego należy przypinać wersje i używać wyłącznie zaufanych indeksów).
Jeśli Docker zgłasza ResourceExhausted, cannot allocate memory lub przerywa działanie podczas tsdown, należy zwiększyć limit pamięci kreatora Dockera lub ponowić próbę z mniejszymi, jawnie określonymi rozmiarami sterty:
Obrazy budowane ze źródeł z wybranymi pluginami
OPENCLAW_EXTENSIONS wybiera identyfikatory manifestów pluginów z roboczej kopii źródłowej;
akceptowane są również istniejące nazwy katalogów źródłowych, jeśli się różnią. Kompilacja
Docker raz przyporządkowuje wybór do katalogów źródłowych, instaluje zależności
produkcyjne, a gdy wybrany plugin jest publikowany oddzielnie z użyciem
openclaw.build.bundledDist: false, kompiluje jego środowisko uruchomieniowe do głównego, dołączonego
katalogu dist. Ten sposób pakowania, stosowany wyłącznie w Dockerze, nie zmienia kontraktu
artefaktu npm ani ClawHub pluginu. Nieznane, nieprawidłowe lub niejednoznaczne identyfikatory
powodują niepowodzenie kompilacji obrazu. Znane identyfikatory zależności lub dostępne
wyłącznie w źródłach zachowują dotychczasowy sposób przygotowywania źródeł i zależności,
bez uzyskania skompilowanego wpisu w głównym katalogu dist. Wybrany plugin ze
zintegrowanymi wpisami kompilacji musi zostać pomyślnie skompilowany; źródła i wyniki
środowiska uruchomieniowego niewybranych zewnętrznych pluginów są usuwane.
Na przykład te polecenia tworzą oddzielne, wieloarchitekturowe, samodzielne
obrazy gatewaya FakeCo dla ClickClack, Slack i Microsoft Teams. ClawRouter jest
już częścią głównego środowiska uruchomieniowego OpenClaw, dlatego obraz ClickClack wybiera tylko
clickclack. Jawnie pusty argument przeglądarki sprawia, że domyślny obraz nie
zawiera Chromium:
--platform linux/arm64 --load lub --platform linux/amd64 --load dla pojedynczej
natywnej kompilacji lokalnej. Wynik wieloplatformowy oraz dołączone SBOM i dane pochodzenia
wymagają rejestru albo innego miejsca docelowego Buildx, które zachowuje atestacje. Po
wypchnięciu sprawdź manifest i wdróż niezmienny skrót zamiast
zmiennego tagu SHA źródeł:
OPENCLAW_EXTRA_MOUNTS=/path/to/fork/extensions/synology-chat:/app/extensions/synology-chat:ro. Zastąpi to odpowiadający mu skompilowany pakiet /app/dist/extensions/synology-chat dla tego samego identyfikatora pluginu.
Obserwowalność
Eksport OpenTelemetry jest wysyłany z kontenera Gateway do kolektora OTLP; nie wymaga publikowania portu Dockera. Aby umieścić dołączony eksporter w obrazie kompilowanym lokalnie:diagnostics-otel; zainstaluj samodzielnie clawhub:@openclaw/diagnostics-otel tylko wtedy, gdy został usunięty. Aby włączyć eksport, zezwól na plugin diagnostics-otel i włącz go w konfiguracji, a następnie ustaw diagnostics.otel.enabled=true (pełny przykład znajduje się w sekcji Eksport OpenTelemetry). Nagłówki uwierzytelniania kolektora przekazuje się przez diagnostics.otel.headers, a nie przez zmienne środowiskowe Dockera.
Metryki Prometheus ponownie wykorzystują już opublikowany port Gateway. Zainstaluj clawhub:@openclaw/diagnostics-prometheus, włącz plugin diagnostics-prometheus, a następnie skonfiguruj pobieranie metryk z adresu:
/metrics ani nieuwierzytelnionej ścieżki odwrotnego proxy. Zobacz Metryki Prometheus.
Kontrole kondycji
Punkty końcowe sond kontenera (nie wymagają uwierzytelniania):HEALTHCHECK odpytuje /healthz; powtarzające się niepowodzenia oznaczają kontener jako unhealthy, dzięki czemu orkiestratory mogą go ponownie uruchomić lub zastąpić.
Uwierzytelniona, szczegółowa migawka kondycji:
LAN a interfejs pętli zwrotnej
scripts/docker/setup.sh domyślnie ustawia OPENCLAW_GATEWAY_BIND=lan, aby http://127.0.0.1:18789 na hoście działał z publikowaniem portów Dockera.
lan(domyślnie): przeglądarka i CLI na hoście mogą uzyskać dostęp do opublikowanego portu gatewaya.loopback: tylko procesy wewnątrz przestrzeni nazw sieci kontenera mogą uzyskać bezpośredni dostęp do gatewaya.
gateway.bind (lan / loopback / custom / tailnet / auto), a nie aliasów hosta takich jak 0.0.0.0 lub 127.0.0.1.Lokalne dostawcy na hoście
Wewnątrz kontenera127.0.0.1 oznacza sam kontener, a nie hosta. Dla dostawców działających na hoście użyj host.docker.internal:
docker-compose.yml mapuje host.docker.internal na gateway hosta w Docker Engine dla systemu Linux (Docker Desktop udostępnia ten sam alias w systemach macOS/Windows). Usługi hosta muszą nasłuchiwać pod adresem dostępnym dla Dockera:
docker run? Dodaj samodzielnie to samo mapowanie, np. --add-host=host.docker.internal:host-gateway.
Backend Claude CLI w Dockerze
Oficjalny obraz nie zawiera fabrycznie Claude Code. Zainstaluj go i zaloguj się wewnątrz użytkownikanode kontenera, a następnie zachowaj ten katalog domowy kontenera, aby aktualizacje obrazu nie usuwały pliku wykonywalnego ani stanu uwierzytelniania.
W przypadku nowej instalacji włącz trwały wolumin /home/node przed uruchomieniem konfiguracji:
.env — skrypt konfiguracji zawsze nadpisuje .env wartościami z bieżącej powłoki i wartościami domyślnymi; nie odczytuje samodzielnie tego pliku:
.env zawiera wartości, których powłoka nie może wczytać, najpierw ręcznie ponownie wyeksportuj używane wartości (OPENCLAW_IMAGE, porty, tryb powiązania, niestandardowe ścieżki, OPENCLAW_EXTRA_MOUNTS, piaskownicę, pominięcie wdrażania). Wygenerowana nakładka montuje wolumin domowy zarówno dla openclaw-gateway, jak i openclaw-cli; pozostałe polecenia uruchamiaj z tą nakładką (oraz najpierw z docker-compose.override.yml, jeśli jest używany):
claude w /home/node/.local/bin/claude. Skonfiguruj OpenClaw tak, aby używał tej ścieżki:
claude-cli:
OPENCLAW_HOME_VOLUME zachowuje natywną instalację w /home/node/.local/bin i /home/node/.local/share/claude, a także ustawienia i dane uwierzytelniania Claude Code w /home/node/.claude i /home/node/.claude.json. Zachowanie wyłącznie /home/node/.openclaw nie wystarczy; jeśli zamiast woluminu domowego używany jest OPENCLAW_EXTRA_MOUNTS, zamontuj wszystkie te ścieżki Claude w obu usługach.
Bonjour / mDNS
Sieć mostkowa Dockera zwykle nie przekazuje niezawodnie ruchu multiemisji Bonjour/mDNS (224.0.0.251:5353). Gdy OPENCLAW_DISABLE_BONJOUR nie jest ustawione, dołączony plugin Bonjour automatycznie wyłącza rozgłaszanie w sieci LAN po wykryciu działania w kontenerze, dzięki czemu nie wpada w pętlę awarii podczas ponawiania multiemisji odrzucanej przez most. Ustaw OPENCLAW_DISABLE_BONJOUR=1, aby wymusić wyłączenie niezależnie od wyniku wykrywania, albo 0, aby wymusić włączenie (wyłącznie w sieci hosta, macvlan lub innej sieci, w której wiadomo, że multiemisja mDNS działa).
W pozostałych przypadkach dla hostów Dockera używaj opublikowanego adresu URL Gateway, Tailscale lub rozległego DNS-SD. Ograniczenia i wskazówki dotyczące rozwiązywania problemów zawiera sekcja Wykrywanie Bonjour.
Pamięć masowa i trwałość
Docker Compose montuje przez powiązanieOPENCLAW_CONFIG_DIR w /home/node/.openclaw, OPENCLAW_WORKSPACE_DIR w /home/node/.openclaw/workspace oraz OPENCLAW_AUTH_PROFILE_SECRET_DIR w /home/node/.config/openclaw, dzięki czemu te ścieżki przetrwają zastąpienie kontenera. Gdy zmienna nie jest ustawiona, docker-compose.yml używa ścieżki zapasowej w ${HOME} albo /tmp, jeśli brakuje samego HOME, dzięki czemu docker compose up nigdy nie generuje specyfikacji woluminu z pustym źródłem w podstawowych środowiskach.
Ten zamontowany katalog konfiguracji zawiera:
openclaw.json— konfigurację zachowaniaagents/<agentId>/agent/auth-profiles.json— zapisane dane uwierzytelniania OAuth/kluczem API dostawcy.env— sekrety środowiska uruchomieniowego pochodzące ze zmiennych środowiskowych, takie jakOPENCLAW_GATEWAY_TOKEN
OPENCLAW_CONFIG_DIR.
Zainstalowane pluginy dostępne do pobrania przechowują stan pakietów w zamontowanym katalogu domowym OpenClaw, dzięki czemu rekordy instalacji i katalogi główne pakietów przetrwają zastąpienie kontenera; uruchomienie gatewaya nie regeneruje drzew zależności dołączonych pluginów.
Pełne informacje o trwałości maszyny wirtualnej zawiera sekcja Środowisko uruchomieniowe maszyny wirtualnej Docker — co i gdzie jest zachowywane.
Miejsca szybkiego wzrostu użycia dysku: media/, bazy danych SQLite poszczególnych agentów, starsze transkrypcje sesji JSONL, współdzielona baza danych stanu SQLite, katalogi główne pakietów zainstalowanych pluginów oraz rotacyjne dzienniki plikowe w /tmp/openclaw/.
Pomocnicze funkcje powłoki (opcjonalnie)
Aby skrócić codzienne polecenia, zainstaluj ClawDock:scripts/shell-helpers/clawdock-helpers.sh, uruchom ponownie powyższe polecenie, aby lokalny skrypt pomocniczy wskazywał bieżącą lokalizację. Następnie używaj clawdock-start, clawdock-stop, clawdock-dashboard itd. (uruchom clawdock-help, aby wyświetlić pełną listę).
Włącz piaskownicę agenta dla Gateway Docker
Włącz piaskownicę agenta dla Gateway Docker
docker.sock dopiero po pomyślnym spełnieniu wymagań wstępnych piaskownicy. Jeśli nie można ukończyć konfiguracji piaskownicy, resetuje agents.defaults.sandbox.mode do off. Tryb kodu Codex jest wyłączony podczas tur, w których piaskownica OpenClaw jest aktywna (zobacz Piaskownica § Backend Docker); nigdy nie montuj gniazda Docker hosta w kontenerach piaskownicy agenta.Automatyzacja / CI (bez interakcji)
Automatyzacja / CI (bez interakcji)
-T:Uwaga dotycząca bezpieczeństwa współdzielonej sieci
Uwaga dotycząca bezpieczeństwa współdzielonej sieci
openclaw-cli używa network_mode: "service:openclaw-gateway", aby polecenia CLI mogły komunikować się z Gateway przez 127.0.0.1. Należy traktować to jako współdzieloną granicę zaufania. Konfiguracja Compose usuwa NET_RAW/NET_ADMIN i włącza no-new-privileges zarówno dla openclaw-gateway, jak i openclaw-cli.Błędy DNS Docker Desktop w openclaw-cli
Błędy DNS Docker Desktop w openclaw-cli
openclaw-cli we współdzielonej sieci kończy się niepowodzeniem po usunięciu NET_RAW, co objawia się jako EAI_AGAIN podczas poleceń korzystających z npm, takich jak openclaw plugins install. Do normalnej pracy zachowaj domyślny, wzmocniony plik Compose. Poniższe nadpisanie przywraca domyślne możliwości wyłącznie kontenerowi openclaw-cli — używaj go do jednorazowego polecenia wymagającego dostępu do rejestru, a nie jako domyślnego sposobu uruchamiania:openclaw-cli został już utworzony jako długotrwale działający, utwórz go ponownie z tym samym nadpisaniem — docker compose exec/docker exec nie mogą zmienić możliwości systemu Linux w już utworzonym kontenerze.Uprawnienia i EACCES
Uprawnienia i EACCES
node (uid 1000). Jeśli występują błędy uprawnień dotyczące /home/node/.openclaw, upewnij się, że montowania powiązane z hosta należą do uid 1000:blocked plugin candidate: suspicious ownership (... uid=1000, expected uid=0 or root), po którym występuje plugin present but blocked — uid procesu i właściciel zamontowanego katalogu Pluginu są różni. Zalecane jest uruchamianie z domyślnym uid 1000 i poprawienie własności montowania powiązanego. Zmieniaj właściciela /path/to/openclaw-config/npm na root:root tylko wtedy, gdy OpenClaw jest celowo uruchamiany długoterminowo jako root.Szybsze ponowne kompilacje
Szybsze ponowne kompilacje
pnpm install, dopóki pliki blokady się nie zmienią:Opcje kontenera dla zaawansowanych użytkowników
Opcje kontenera dla zaawansowanych użytkowników
node. Aby uzyskać kontener o większych możliwościach:- Zachowaj
/home/node:export OPENCLAW_HOME_VOLUME="openclaw_home" - Wbuduj zależności systemowe:
export OPENCLAW_IMAGE_APT_PACKAGES="git curl jq" - Wbuduj zależności Pythona:
export OPENCLAW_IMAGE_PIP_PACKAGES="requests==2.32.5 humanize==4.14.0" - Wbuduj Playwright Chromium:
export OPENCLAW_INSTALL_BROWSER=1lub użyj oficjalnego znacznika obrazu-browser - Alternatywnie zainstaluj przeglądarki Playwright w trwałym woluminie:
- Zachowaj pobrane pliki przeglądarek: użyj
OPENCLAW_HOME_VOLUMElubOPENCLAW_EXTRA_MOUNTS. OpenClaw automatycznie wykrywa zarządzaną przez Playwright przeglądarkę Chromium obrazu w systemie Linux.
OAuth OpenAI Codex (Docker bez interfejsu graficznego)
OAuth OpenAI Codex (Docker bez interfejsu graficznego)
Metadane obrazu bazowego
Metadane obrazu bazowego
node:24-bookworm-slim i uruchamia tini jako proces o PID 1, aby procesy zombie były sprzątane, a sygnały prawidłowo obsługiwane w długotrwale działających kontenerach. Publikuje adnotacje obrazu bazowego OCI, w tym org.opencontainers.image.base.name i org.opencontainers.image.source. Dependabot odświeża przypięty skrót obrazu bazowego Node; kompilacje wydań nie uruchamiają osobnej warstwy aktualizacji dystrybucji. Zobacz adnotacje obrazów OCI.Uruchamianie na VPS?
Instrukcje wdrażania na współdzielonej maszynie wirtualnej, w tym wbudowywania plików binarnych, trwałości i aktualizacji, znajdują się w sekcjach Hetzner (VPS Docker) oraz Środowisko uruchomieniowe maszyny wirtualnej Docker.Piaskownica agenta
Gdyagents.defaults.sandbox jest włączone z backendem Docker, Gateway wykonuje narzędzia agenta (powłokę, odczyt i zapis plików itd.) wewnątrz izolowanych kontenerów Docker, podczas gdy sam Gateway pozostaje na hoście — tworzy to twardą barierę wokół niezaufanych lub wielodostępnych sesji agentów bez umieszczania całego Gateway w kontenerze.
Zakres piaskownicy może obejmować agenta (domyślnie), sesję lub być współdzielony; każdy zakres otrzymuje własny obszar roboczy zamontowany w /workspace. Można również skonfigurować zasady zezwalania na narzędzia lub ich blokowania, izolację sieci, limity zasobów i kontenery przeglądarek.
Pełna konfiguracja, obrazy, uwagi dotyczące bezpieczeństwa i profile wielu agentów:
- Piaskownica — pełna dokumentacja piaskownicy
- OpenShell — interaktywny dostęp do powłoki kontenerów piaskownicy
- Piaskownica i narzędzia dla wielu agentów — ustawienia zastępujące dla poszczególnych agentów
Szybkie włączanie
docker build do wykonania bezpośrednio.
Rozwiązywanie problemów
Brak obrazu lub kontener piaskownicy nie uruchamia się
Brak obrazu lub kontener piaskownicy nie uruchamia się
scripts/sandbox-setup.sh (kopia robocza kodu źródłowego) albo bezpośredniego polecenia docker build z sekcji Piaskownica § Obrazy i konfiguracja (instalacja npm), lub ustaw agents.defaults.sandbox.docker.image na własny obraz. Kontenery są automatycznie tworzone dla poszczególnych sesji na żądanie.Błędy uprawnień w piaskownicy
Błędy uprawnień w piaskownicy
docker.user na UID:GID zgodne z własnością zamontowanego obszaru roboczego albo zmień właściciela folderu obszaru roboczego.Nie znaleziono niestandardowych narzędzi w piaskownicy
Nie znaleziono niestandardowych narzędzi w piaskownicy
sh -lc (powłoka logowania), która wczytuje /etc/profile i może resetować PATH. Ustaw docker.env.PATH, aby dodać ścieżki niestandardowych narzędzi na początku, albo dodaj skrypt w /etc/profile.d/ w pliku Dockerfile.Proces zakończony z powodu braku pamięci podczas budowania obrazu (kod wyjścia 137)
Proces zakończony z powodu braku pamięci podczas budowania obrazu (kod wyjścia 137)
Brak autoryzacji lub wymagane parowanie w interfejsie Control UI
Brak autoryzacji lub wymagane parowanie w interfejsie Control UI
Cel Gateway wskazuje ws://172.x.x.x lub występują błędy parowania z CLI Docker
Cel Gateway wskazuje ws://172.x.x.x lub występują błędy parowania z CLI Docker
Powiązane
- Przegląd instalacji — wszystkie metody instalacji
- Podman — alternatywa dla Docker oparta na Podman
- ClawDock — społecznościowa konfiguracja Docker Compose
- Aktualizowanie — utrzymywanie aktualnej wersji OpenClaw
- Konfiguracja — konfiguracja Gateway po instalacji