Docker

Docker jest opcjonalny. Użyj go tylko wtedy, gdy chcesz skonteneryzowany Gateway albo zweryfikować przepływ Docker.

Czy Docker jest dla mnie odpowiedni?

• Tak: chcesz izolowane, tymczasowe środowisko Gateway albo uruchomić OpenClaw na hoście bez lokalnych instalacji.
• Nie: uruchamiasz na własnym komputerze i chcesz po prostu najszybszą pętlę deweloperską. Zamiast tego użyj normalnego przepływu instalacji.
• Uwaga o sandboxingu: domyślny backend sandboxa używa Docker, gdy sandboxing jest włączony, ale sandboxing jest domyślnie wyłączony i nie wymaga uruchamiania całego Gateway w Docker. Dostępne są też backendy sandboxa SSH i OpenShell. Zobacz Sandboxing.

Wymagania wstępne

• Docker Desktop (lub Docker Engine) + Docker Compose v2
• Co najmniej 2 GB RAM na budowanie obrazu (pnpm install może zostać zakończone przez OOM na hostach z 1 GB, z kodem wyjścia 137)
• Wystarczająco dużo miejsca na dysku na obrazy i logi
• Jeśli uruchamiasz na VPS/hoście publicznym, przejrzyj Wzmacnianie zabezpieczeń przy ekspozycji sieciowej, zwłaszcza politykę zapory Docker DOCKER-USER.

Skonteneryzowany Gateway

./scripts/docker/setup.sh

export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"./scripts/docker/setup.sh

export OPENCLAW_IMAGE="openclaw/openclaw:latest"./scripts/docker/setup.sh

docker load -i openclaw-image.tarexport OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"./scripts/docker/setup.sh --offline

docker compose run --rm openclaw-cli dashboard --no-open

# WhatsApp (QR)docker compose run --rm openclaw-cli channels login # Telegramdocker compose run --rm openclaw-cli channels add --channel telegram --token "<token>" # Discorddocker compose run --rm openclaw-cli channels add --channel discord --token "<token>"

Przepływ ręczny

Jeśli wolisz uruchomić każdy krok samodzielnie zamiast używać skryptu konfiguracji:

docker build -t openclaw:local -f Dockerfile .docker compose run --rm --no-deps --entrypoint node openclaw-gateway \  dist/index.js onboard --mode local --no-install-daemondocker compose run --rm --no-deps --entrypoint node openclaw-gateway \  dist/index.js config set --batch-json '[{"path":"gateway.mode","value":"local"},{"path":"gateway.bind","value":"lan"},{"path":"gateway.controlUi.allowedOrigins","value":["http://localhost:18789","http://127.0.0.1:18789"]}]'docker compose up -d openclaw-gateway

Zmienne środowiskowe

Skrypt konfiguracji akceptuje te opcjonalne zmienne środowiskowe:

Oficjalny obraz Docker nie zawiera Homebrew. Podczas onboardingu OpenClaw ukrywa instalatory zależności Skills dostępne tylko przez brew, gdy działa w kontenerze Linux bez brew; te zależności muszą zostać dostarczone przez obraz niestandardowy albo zainstalowane ręcznie. Dla zależności dostępnych z pakietów Debian użyj OPENCLAW_IMAGE_APT_PACKAGES podczas budowania obrazu. Starsza nazwa OPENCLAW_DOCKER_APT_PACKAGES nadal jest akceptowana. Dla zależności Python użyj OPENCLAW_IMAGE_PIP_PACKAGES. To uruchamia python3 -m pip install --break-system-packages podczas budowania obrazu, więc przypinaj wersje pakietów i używaj tylko zaufanych indeksów pakietów. Budowania ze źródeł domyślnie ustawiają OPENCLAW_DOCKER_BUILD_NODE_OPTIONS na --max-old-space-size=8192 i pozostawiają OPENCLAW_DOCKER_BUILD_TSDOWN_MAX_OLD_SPACE_MB nieustawione, aby wrapper tsdown mógł respektować limity pamięci kontenera. Domyślnie ustawiają też OPENCLAW_DOCKER_BUILD_SKIP_DTS=1, ponieważ obrazy runtime usuwają pliki deklaracji po budowaniu. Jeśli Docker zgłasza ResourceExhausted, cannot allocate memory albo przerywa podczas tsdown, zwiększ limit pamięci buildera Docker albo spróbuj ponownie z mniejszymi jawnymi stertami, na przykład OPENCLAW_DOCKER_BUILD_NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_DOCKER_BUILD_TSDOWN_MAX_OLD_SPACE_MB=4096.

Maintainerzy mogą testować źródło dołączonego pluginu względem spakowanego obrazu, montując jeden katalog źródłowy pluginu na jego spakowaną ścieżkę źródłową, na przykład OPENCLAW_EXTRA_MOUNTS=/path/to/fork/extensions/synology-chat:/app/extensions/synology-chat:ro. Ten zamontowany katalog źródłowy nadpisuje pasujący skompilowany pakiet /app/dist/extensions/synology-chat dla tego samego identyfikatora pluginu.

Obserwowalność

Eksport OpenTelemetry jest wychodzący z kontenera Gateway do Twojego kolektora OTLP. Nie wymaga opublikowanego portu Docker. Jeśli budujesz obraz lokalnie i chcesz, aby dołączony eksporter OpenTelemetry był dostępny wewnątrz obrazu, uwzględnij jego zależności runtime:

export OPENCLAW_EXTENSIONS="diagnostics-otel"export OTEL_EXPORTER_OTLP_ENDPOINT="http://otel-collector:4318"export OTEL_SERVICE_NAME="openclaw-gateway"./scripts/docker/setup.sh

Zainstaluj oficjalny plugin @openclaw/diagnostics-otel z ClawHub w spakowanych instalacjach Docker przed włączeniem eksportu. Niestandardowe obrazy budowane ze źródeł nadal mogą zawierać lokalne źródło pluginu z OPENCLAW_EXTENSIONS=diagnostics-otel. Aby włączyć eksport, zezwól i włącz plugin diagnostics-otel w konfiguracji, a następnie ustaw diagnostics.otel.enabled=true albo użyj przykładu konfiguracji w Eksport OpenTelemetry. Nagłówki uwierzytelniania kolektora są konfigurowane przez diagnostics.otel.headers, a nie przez zmienne środowiskowe Docker.

Metryki Prometheus używają już opublikowanego portu Gateway. Zainstaluj clawhub:@openclaw/diagnostics-prometheus, włącz plugin diagnostics-prometheus, a następnie pobieraj metryki:

http://<gateway-host>:18789/api/diagnostics/prometheus

Trasa jest chroniona uwierzytelnianiem Gateway. Nie wystawiaj osobnego publicznego portu /metrics ani nieuwierzytelnionej ścieżki reverse proxy. Zobacz Metryki Prometheus.

Kontrole kondycji

Endpointy sond kontenera (uwierzytelnianie niewymagane):

curl -fsS http://127.0.0.1:18789/healthz   # livenesscurl -fsS http://127.0.0.1:18789/readyz     # readiness

Obraz Docker zawiera wbudowany HEALTHCHECK, który odpytuje /healthz. Jeśli kontrole nadal kończą się niepowodzeniem, Docker oznacza kontener jako unhealthy, a systemy orkiestracji mogą go zrestartować lub zastąpić.

Uwierzytelniony szczegółowy zrzut stanu zdrowia:

docker compose exec openclaw-gateway node dist/index.js health --token "$OPENCLAW_GATEWAY_TOKEN"

LAN a loopback

scripts/docker/setup.sh domyślnie ustawia OPENCLAW_GATEWAY_BIND=lan, dzięki czemu dostęp hosta do http://127.0.0.1:18789 działa z publikowaniem portów Docker.

• lan (domyślnie): przeglądarka hosta i CLI hosta mogą dotrzeć do opublikowanego portu gateway.
• loopback: tylko procesy wewnątrz przestrzeni nazw sieci kontenera mogą dotrzeć bezpośrednio do gateway.

Lokalne providery hosta

Gdy OpenClaw działa w Docker, 127.0.0.1 wewnątrz kontenera oznacza sam kontener, a nie komputer hosta. Używaj host.docker.internal dla providerów AI, które działają na hoście:

Dołączona konfiguracja Docker używa tych adresów URL hosta jako domyślnych wartości onboardingu LM Studio i Ollama, a docker-compose.yml mapuje host.docker.internal na gateway hosta Docker dla Linux Docker Engine. Docker Desktop zapewnia już tę samą nazwę hosta w macOS i Windows.

Usługi hosta muszą także nasłuchiwać na adresie osiągalnym z Docker:

lms server start --port 1234 --bind 0.0.0.0OLLAMA_HOST=0.0.0.0:11434 ollama serve

Jeśli używasz własnego pliku Compose lub polecenia docker run, dodaj takie samo mapowanie hosta samodzielnie, na przykład --add-host=host.docker.internal:host-gateway.

Backend Claude CLI w Docker

Oficjalny obraz Docker OpenClaw nie ma wstępnie zainstalowanego Claude Code. Zainstaluj i zaloguj się do Claude Code wewnątrz użytkownika kontenera, który uruchamia OpenClaw, a następnie utrwal katalog domowy tego kontenera, aby aktualizacje obrazu nie usuwały pliku binarnego ani stanu uwierzytelnienia Claude.

W przypadku nowych instalacji Docker włącz trwały wolumin /home/node przed uruchomieniem konfiguracji:

export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"export OPENCLAW_HOME_VOLUME="openclaw_home"./scripts/docker/setup.sh

W przypadku istniejącej instalacji Docker najpierw zatrzymaj stos i ponownie wczytaj bieżące wartości Docker .env przed ponownym uruchomieniem konfiguracji. Skrypt konfiguracyjny nie odczytuje samodzielnie .env; przepisuje .env z bieżącej powłoki i wartości domyślnych. Dla wygenerowanego .env uruchom:

set -a. ./.envset +aexport OPENCLAW_HOME_VOLUME="${OPENCLAW_HOME_VOLUME:-openclaw_home}"./scripts/docker/setup.sh

Jeśli Twój .env zawiera wartości, których powłoka nie może wczytać, najpierw ręcznie ponownie wyeksportuj istniejące wartości, na których polegasz, takie jak OPENCLAW_IMAGE, porty, tryb wiązania, niestandardowe ścieżki, OPENCLAW_EXTRA_MOUNTS, sandbox i ustawienia pomijania onboardingu. Wygenerowana nakładka montuje wolumin domowy zarówno dla openclaw-gateway, jak i openclaw-cli.

Uruchom pozostałe polecenia z wygenerowaną nakładką Compose, aby obie usługi montowały utrwalony katalog domowy. Jeśli Twoja konfiguracja używa także docker-compose.override.yml, uwzględnij go przed docker-compose.extra.yml.

Zainstaluj Claude Code w tym utrwalonym katalogu domowym:

docker compose -f docker-compose.yml -f docker-compose.extra.yml run --rm \  --entrypoint sh openclaw-cli -lc \  'curl -fsSL https://claude.ai/install.sh | bash'

Natywny instalator zapisuje plik binarny claude pod /home/node/.local/bin/claude. Wskaż OpenClaw tę ścieżkę kontenera:

docker compose -f docker-compose.yml -f docker-compose.extra.yml run --rm \  openclaw-cli config set \  agents.defaults.cliBackends.claude-cli.command \  /home/node/.local/bin/claude

Zaloguj się i zweryfikuj z wnętrza tego samego utrwalonego katalogu domowego kontenera:

docker compose -f docker-compose.yml -f docker-compose.extra.yml run --rm \  --entrypoint /home/node/.local/bin/claude openclaw-cli auth logindocker compose -f docker-compose.yml -f docker-compose.extra.yml run --rm \  --entrypoint /home/node/.local/bin/claude openclaw-cli auth status --textdocker compose -f docker-compose.yml -f docker-compose.extra.yml run --rm \  openclaw-cli models auth login \  --provider anthropic --method cli --set-defaultdocker compose -f docker-compose.yml -f docker-compose.extra.yml run --rm \  openclaw-cli models list --provider anthropic

Następnie możesz użyć dołączonego backendu claude-cli:

docker compose -f docker-compose.yml -f docker-compose.extra.yml run --rm \  openclaw-cli agent \  --agent main \  --model claude-cli/claude-sonnet-4-6 \  --message "Say hello from Docker Claude CLI"

OPENCLAW_HOME_VOLUME utrwala natywną instalację Claude Code pod /home/node/.local/bin i /home/node/.local/share/claude, a także ustawienia Claude Code oraz stan uwierzytelnienia pod /home/node/.claude i /home/node/.claude.json. Utrwalenie samego /home/node/.openclaw nie wystarczy do ponownego użycia Claude CLI. Jeśli używasz OPENCLAW_EXTRA_MOUNTS zamiast woluminu domowego, zamontuj wszystkie te ścieżki Claude w obu usługach Docker.

Bonjour / mDNS

Sieć mostkowa Dockera zwykle nie przekazuje niezawodnie multicastu Bonjour/mDNS (224.0.0.251:5353). Dlatego dołączona konfiguracja Compose domyślnie ustawia OPENCLAW_DISABLE_BONJOUR=1, aby Gateway nie wpadał w pętlę awarii ani wielokrotnie nie restartował rozgłaszania, gdy mostek odrzuca ruch multicast.

Dla hostów Docker użyj opublikowanego URL-a Gateway, Tailscale albo rozległego DNS-SD. Ustaw OPENCLAW_DISABLE_BONJOUR=0 tylko podczas działania z siecią hosta, macvlan albo inną siecią, w której wiadomo, że multicast mDNS działa.

Informacje o pułapkach i rozwiązywaniu problemów znajdziesz w sekcji wykrywanie Bonjour.

Przechowywanie i trwałość danych

Docker Compose montuje przez bind mount OPENCLAW_CONFIG_DIR do /home/node/.openclaw, OPENCLAW_WORKSPACE_DIR do /home/node/.openclaw/workspace oraz OPENCLAW_AUTH_PROFILE_SECRET_DIR do /home/node/.config/openclaw, więc te ścieżki przetrwają wymianę kontenera. Gdy dowolna zmienna nie jest ustawiona, dołączony docker-compose.yml używa lokalizacji pod ${HOME}, albo /tmp, gdy brakuje także samego HOME. Dzięki temu docker compose up nie emituje specyfikacji woluminu z pustym źródłem w podstawowych środowiskach.

Ten zamontowany katalog konfiguracji to miejsce, w którym OpenClaw przechowuje:

• openclaw.json dla konfiguracji zachowania
• agents/<agentId>/agent/auth-profiles.json dla zapisanych danych uwierzytelniania dostawcy OAuth/kluczem API
• .env dla sekretów środowiskowych czasu działania, takich jak OPENCLAW_GATEWAY_TOKEN

Katalog klucza sekretu profilu uwierzytelniania przechowuje lokalny klucz szyfrowania używany dla materiału tokenów profilu uwierzytelniania opartego na OAuth. Przechowuj go ze stanem hosta Docker, ale oddzielnie od OPENCLAW_CONFIG_DIR.

Zainstalowane pobieralne pluginy przechowują stan swoich pakietów w zamontowanym katalogu domowym OpenClaw, więc rekordy instalacji pluginów i katalogi główne pakietów przetrwają wymianę kontenera. Uruchomienie Gateway nie generuje drzew zależności dołączonych pluginów.

Pełne szczegóły trwałości danych we wdrożeniach VM znajdziesz w sekcji Środowisko wykonawcze Docker VM - co gdzie jest utrwalane.

Miejsca szybkiego wzrostu użycia dysku: obserwuj media/, pliki JSONL sesji, współdzieloną bazę danych stanu SQLite, katalogi główne pakietów zainstalowanych pluginów oraz rotowane logi plikowe w /tmp/openclaw/.

Pomocnicze skrypty powłoki (opcjonalne)

Aby ułatwić codzienne zarządzanie Dockerem, zainstaluj ClawDock:

mkdir -p ~/.clawdock && curl -sL https://raw.githubusercontent.com/openclaw/openclaw/main/scripts/clawdock/clawdock-helpers.sh -o ~/.clawdock/clawdock-helpers.shecho 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc && source ~/.zshrc

Jeśli zainstalowano ClawDock ze starszej surowej ścieżki scripts/shell-helpers/clawdock-helpers.sh, uruchom ponownie powyższe polecenie instalacji, aby lokalny plik pomocniczy śledził nową lokalizację.

Następnie używaj clawdock-start, clawdock-stop, clawdock-dashboard itd. Uruchom clawdock-help, aby zobaczyć wszystkie polecenia. Pełny przewodnik po narzędziach pomocniczych znajdziesz w sekcji ClawDock.

export OPENCLAW_SANDBOX=1./scripts/docker/setup.sh

export OPENCLAW_SANDBOX=1export OPENCLAW_DOCKER_SOCKET=/run/user/1000/docker.sock./scripts/docker/setup.sh

docker compose run -T --rm openclaw-cli gateway probedocker compose run -T --rm openclaw-cli devices list --json

printf '%s\n' \  'services:' \  '  openclaw-cli:' \  '    cap_drop: !reset []' \  > docker-compose.cli-no-dropped-caps.local.yml docker compose -f docker-compose.yml -f docker-compose.cli-no-dropped-caps.local.yml run --rm openclaw-cli plugins install <package>

sudo chown -R 1000:1000 /path/to/openclaw-config /path/to/openclaw-workspace

FROM node:24-bookwormRUN curl -fsSL https://bun.sh/install | bashENV PATH="/root/.bun/bin:${PATH}"RUN corepack enableWORKDIR /appCOPY package.json pnpm-lock.yaml pnpm-workspace.yaml .npmrc ./COPY ui/package.json ./ui/package.jsonCOPY scripts ./scriptsRUN pnpm install --frozen-lockfileCOPY . .RUN pnpm buildRUN pnpm ui:installRUN pnpm ui:buildENV NODE_ENV=productionCMD ["node","dist/index.js"]

Uruchamiasz na VPS?

Zobacz Hetzner (Docker VPS) oraz Docker VM Runtime, aby poznać wspólne kroki wdrożenia na maszynie wirtualnej, w tym wbudowywanie plików binarnych, trwałość danych i aktualizacje.

Piaskownica agenta

Gdy agents.defaults.sandbox jest włączone z backendem Docker, gateway uruchamia wykonywanie narzędzi agenta (powłoka, odczyt/zapis plików itd.) w izolowanych kontenerach Docker, podczas gdy sam gateway pozostaje na hoście. Daje to twardą granicę wokół niezaufanych lub wielodzierżawnych sesji agentów bez konteneryzowania całego gateway.

Zakres piaskownicy może być per agent (domyślnie), per sesja albo współdzielony. Każdy zakres otrzymuje własny obszar roboczy zamontowany w /workspace. Możesz też skonfigurować zasady zezwalania/odmawiania dla narzędzi, izolację sieci, limity zasobów oraz kontenery przeglądarek.

Pełną konfigurację, obrazy, uwagi dotyczące bezpieczeństwa i profile wieloagentowe znajdziesz tutaj:

• Piaskownica -- pełna dokumentacja piaskownicy
• OpenShell -- interaktywny dostęp powłoki do kontenerów piaskownicy
• Piaskownica i narzędzia dla wielu agentów -- nadpisania per agent

Szybkie włączenie

{  agents: {    defaults: {      sandbox: {        mode: "non-main", // off | non-main | all        scope: "agent", // session | agent | shared      },    },  },}

Zbuduj domyślny obraz piaskownicy (z checkoutu źródeł):

scripts/sandbox-setup.sh

W przypadku instalacji npm bez checkoutu źródeł zobacz Piaskownica § Obrazy i konfiguracja, aby uzyskać wbudowane polecenia docker build.

Rozwiązywanie problemów

docker compose run --rm openclaw-cli dashboard --no-opendocker compose run --rm openclaw-cli devices listdocker compose run --rm openclaw-cli devices approve <requestId>

docker compose run --rm openclaw-cli config set --batch-json '[{"path":"gateway.mode","value":"local"},{"path":"gateway.bind","value":"lan"}]'docker compose run --rm openclaw-cli devices list --url ws://127.0.0.1:18789

Powiązane

• Przegląd instalacji — wszystkie metody instalacji
• Podman — alternatywa Podman dla Docker
• ClawDock — społecznościowa konfiguracja Docker Compose
• Aktualizacja — utrzymywanie OpenClaw w aktualnej wersji
• Konfiguracja — konfiguracja gateway po instalacji