Docker

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

# Czy Docker jest dla mnie odpowiedni?

• Tak: chcesz odizolowane, jednorazowe środowisko Gateway albo uruchomić OpenClaw na hoście bez lokalnych instalacji.
• Nie: uruchamiasz na własnym komputerze i chcesz po prostu najszybszej pętli deweloperskiej. Zamiast tego użyj standardowego przepływu instalacji.
• Uwaga o piaskownicy: domyślny backend piaskownicy używa Docker, gdy piaskownica jest włączona, ale piaskownica jest domyślnie wyłączona i nie wymaga uruchamiania całego Gateway w Docker. Dostępne są też backendy piaskownicy SSH i OpenShell. Zobacz Piaskownica.

# Wymagania wstępne

• Docker Desktop (albo Docker Engine) + Docker Compose v2
• Co najmniej 2 GB RAM na budowanie obrazu (pnpm install może zostać ubite przez OOM na hostach z 1 GB z kodem wyjścia 137)
• Wystarczająca ilość miejsca na dysku na obrazy i logi
• Jeśli uruchamiasz na VPS/publicznym hoście, przejrzyj Wzmocnienie bezpieczeństwa dla ekspozycji sieciowej, szczególnie politykę zapory Docker DOCKER-USER.

# Gateway w kontenerze

./scripts/docker/setup.sh

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

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

# WhatsApp (QR)
docker compose run --rm openclaw-cli channels login

# Telegram
docker compose run --rm openclaw-cli channels add --channel telegram --token "<token>"

# Discord
docker compose run --rm openclaw-cli channels add --channel discord --token "<token>"

# Przepływ ręczny

Jeśli wolisz wykonać 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-daemon
docker 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:

Maintainerzy mogą testować źródła dołączonych Plugin względem obrazu pakietowego, montując jeden katalog źródeł Plugin na jego pakietowej ścieżce źródłowej, na przykład OPENCLAW_EXTRA_MOUNTS=/path/to/fork/extensions/synology-chat:/app/extensions/synology-chat:ro. Ten zamontowany katalog źródłowy zastępuje pasujący skompilowany pakiet /app/dist/extensions/synology-chat dla tego samego identyfikatora Plugin.

# 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, dołącz 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 pakietowych instalacjach Docker przed włączeniem eksportu. Niestandardowe obrazy budowane ze źródeł mogą nadal dołączać lokalne źródła Plugin za pomocą OPENCLAW_EXTENSIONS=diagnostics-otel. Aby włączyć eksport, zezwól na Plugin diagnostics-otel w konfiguracji i włącz go, 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 przez uwierzytelnianie Gateway. Nie wystawiaj osobnego publicznego portu /metrics ani nieuwierzytelnionej ścieżki reverse proxy. Zobacz Metryki Prometheus.

# Kontrole zdrowia

Endpointy sond kontenera (uwierzytelnianie nie jest wymagane):

curl -fsS http://127.0.0.1:18789/healthz   # liveness
curl -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ć albo zastąpić.

Uwierzytelniona dogłębna migawka zdrowia:

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

# LAN vs loopback

scripts/docker/setup.sh domyślnie ustawia OPENCLAW_GATEWAY_BIND=lan, aby 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ą sięgnąć do opublikowanego portu Gateway.
• loopback: tylko procesy wewnątrz przestrzeni nazw sieci kontenera mogą sięgać bezpośrednio do Gateway.

# Lokalni dostawcy hosta

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

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

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

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

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

# Bonjour / mDNS

Sieć mostkowa Docker 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.

Użyj opublikowanego URL-a Gateway, Tailscale albo wide-area DNS-SD dla hostów Docker. Ustaw OPENCLAW_DISABLE_BONJOUR=0 tylko wtedy, gdy uruchamiasz z siecią hosta, macvlan albo inną siecią, w której wiadomo, że multicast mDNS działa.

Pułapki i rozwiązywanie problemów opisuje Wykrywanie Bonjour.

# Pamięć masowa i trwałość

Docker Compose montuje bind OPENCLAW_CONFIG_DIR do /home/node/.openclaw oraz OPENCLAW_WORKSPACE_DIR do /home/node/.openclaw/workspace, więc te ścieżki przetrwają zastąpienie kontenera. Gdy którakolwiek zmienna nie jest ustawiona, dołączony docker-compose.yml wraca do ${HOME}/.openclaw (oraz ${HOME}/.openclaw/workspace dla montowania workspace) albo do /tmp/.openclaw, gdy brakuje też samego HOME. Dzięki temu docker compose up nie emituje specyfikacji wolumenu z pustym źródłem w minimalistycznych środowiskach.

Ten zamontowany katalog konfiguracji jest miejscem, w którym OpenClaw przechowuje:

• openclaw.json dla konfiguracji zachowania
• agents/<agentId>/agent/auth-profiles.json dla zapisanych danych uwierzytelniania OAuth/kluczy API dostawców
• .env dla sekretów runtime opartych na zmiennych środowiskowych, takich jak OPENCLAW_GATEWAY_TOKEN

Zainstalowane pobieralne Plugin przechowują stan swoich pakietów pod zamontowanym katalogiem domowym OpenClaw, więc rekordy instalacji Plugin i katalogi główne pakietów przetrwają zastąpienie kontenera. Start Gateway nie generuje drzew zależności dołączonych Plugin.

Pełne szczegóły trwałości przy wdrożeniach VM znajdziesz w Docker VM Runtime - Co jest utrwalane i gdzie.

Miejsca szybkiego wzrostu użycia dysku: obserwuj media/, pliki JSONL sesji, cron/runs/*.jsonl, katalogi główne zainstalowanych pakietów Plugin oraz rotacyjne logi plikowe w /tmp/openclaw/.

# Pomocniki 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.sh
echo '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 pomocnika ś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 pomocniku znajdziesz w ClawDock.

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

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

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

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

FROM node:24-bookworm
RUN curl -fsSL https://bun.sh/install | bash
ENV PATH="/root/.bun/bin:${PATH}"
RUN corepack enable
WORKDIR /app
COPY package.json pnpm-lock.yaml pnpm-workspace.yaml .npmrc ./
COPY ui/package.json ./ui/package.json
COPY scripts ./scripts
RUN pnpm install --frozen-lockfile
COPY . .
RUN pnpm build
RUN pnpm ui:install
RUN pnpm ui:build
ENV NODE_ENV=production
CMD ["node","dist/index.js"]

# Uruchamiasz na VPS?

Zobacz Hetzner (Docker VPS) oraz Docker VM Runtime, aby poznać kroki wdrażania na współdzielonej maszynie VM, w tym wbudowywanie plików binarnych, trwałość 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ą barierę wokół niezaufanych lub wielodzierżawczych 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 i kontenery przeglądarki.

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łączanie

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

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

scripts/sandbox-setup.sh

Dla instalacji npm bez checkoutu źródłowego zobacz Piaskownica § Obrazy i konfiguracja, aby uzyskać wbudowane polecenia docker build.

# Rozwiązywanie problemów

docker compose run --rm openclaw-cli dashboard --no-open
docker compose run --rm openclaw-cli devices list
docker 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 Dockera
• ClawDock — społecznościowa konfiguracja Docker Compose
• Aktualizowanie — utrzymywanie OpenClaw w aktualnej wersji
• Konfiguracja — konfiguracja gateway po instalacji