Przejdź do głównej treści

​
Docker (opcjonalnie)

Docker jest opcjonalny. Używaj go tylko wtedy, gdy chcesz konteneryzowaną bramę lub zweryfikować przepływ pracy z Dockerem.

​
Czy Docker jest dla mnie?

  • Tak: chcesz odizolowane, tymczasowe środowisko bramy albo uruchamiać OpenClaw na hoście bez instalacji lokalnych.
  • Nie: pracujesz na własnym komputerze i zależy Ci na najszybszej pętli developerskiej. Zamiast tego użyj standardowego procesu instalacji.
  • Uwaga dotycząca sandboxingu: sandboxing agentów również używa Dockera, ale nie wymaga uruchamiania całej bramy w Dockerze. Zobacz Sandboxing.
Ten przewodnik obejmuje:
  • Konteneryzowaną bramę (pełny OpenClaw w Dockerze)
  • Sandbox agenta na sesję (host bramy + narzędzia agentów izolowane w Dockerze)
Szczegóły sandboxingu: Sandboxing

​
Wymagania

  • Docker Desktop (lub Docker Engine) + Docker Compose v2
  • Wystarczająca ilość miejsca na dysku na obrazy + logi

​
Konteneryzowana brama (Docker Compose)

​
Szybki start (zalecane)

Z repozytorium: 
./docker-setup.sh
Ten skrypt:
  • buduje obraz bramy
  • uruchamia kreator onboardingu
  • wyświetla opcjonalne wskazówki konfiguracji dostawców
  • uruchamia bramę przez Docker Compose
  • generuje token bramy i zapisuje go do .env
Opcjonalne zmienne środowiskowe:
  • OPENCLAW_DOCKER_APT_PACKAGES — instaluj dodatkowe pakiety apt podczas budowania
  • OPENCLAW_EXTRA_MOUNTS — dodaj dodatkowe bind mounty hosta
  • OPENCLAW_HOME_VOLUME — utrwal /home/node w nazwanym wolumenie
Po zakończeniu:
  • Otwórz http://127.0.0.1:18789/ w przeglądarce.
  • Wklej token w interfejsie Control UI (Ustawienia → token).
  • Potrzebujesz ponownie adresu URL? Uruchom docker compose run --rm openclaw-cli dashboard --no-open.
Konfiguracja/obszar roboczy są zapisywane na hoście:
  • ~/.openclaw/
  • ~/.openclaw/workspace
Uruchamiasz na VPS? Zobacz Hetzner (Docker VPS).

​
Pomocnicze funkcje powłoki (opcjonalnie)

Aby ułatwić codzienne zarządzanie Dockerem, zainstaluj ClawDock: 
mkdir -p ~/.clawdock && curl -sL https://raw.githubusercontent.com/openclaw/openclaw/main/scripts/shell-helpers/clawdock-helpers.sh -o ~/.clawdock/clawdock-helpers.sh
Dodaj do konfiguracji swojej powłoki (zsh): 
echo 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc && source ~/.zshrc
Następnie używaj clawdock-start, clawdock-stop, clawdock-dashboard itd. Uruchom clawdock-help, aby zobaczyć wszystkie polecenia. Szczegóły znajdziesz w ClawDock Helper README.

​
Ręczny przepływ (compose)

docker build -t openclaw:local -f Dockerfile .
docker compose run --rm openclaw-cli onboard
docker compose up -d openclaw-gateway
Uwaga: uruchom docker compose ... z katalogu głównego repozytorium. Jeśli włączyłeś OPENCLAW_EXTRA_MOUNTS lub OPENCLAW_HOME_VOLUME, skrypt konfiguracji zapisze docker-compose.extra.yml; dołącz go podczas uruchamiania Compose w innym miejscu: 
docker compose -f docker-compose.yml -f docker-compose.extra.yml <command>

​
Token Control UI + parowanie (Docker)

Jeśli widzisz „unauthorized” lub „disconnected (1008): pairing required”, pobierz świeży link do panelu i zatwierdź urządzenie przeglądarki: 
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>
Więcej informacji: Dashboard, Devices.

​
Dodatkowe mounty (opcjonalnie)

Jeśli chcesz zamontować dodatkowe katalogi hosta do kontenerów, ustaw OPENCLAW_EXTRA_MOUNTS przed uruchomieniem docker-setup.sh. Akceptuje to rozdzielaną przecinkami listę bind mountów Dockera i stosuje je do openclaw-gateway oraz openclaw-cli, generując docker-compose.extra.yml. Przykład: 
export OPENCLAW_EXTRA_MOUNTS="$HOME/.codex:/home/node/.codex:ro,$HOME/github:/home/node/github:rw"
./docker-setup.sh
Uwagi:
  • Ścieżki muszą być udostępnione Docker Desktop na macOS/Windows.
  • Jeśli edytujesz OPENCLAW_EXTRA_MOUNTS, uruchom ponownie docker-setup.sh, aby wygenerować dodatkowy plik compose.
  • docker-compose.extra.yml jest generowany. Nie edytuj go ręcznie.

​
Utrwalenie całego katalogu domowego kontenera (opcjonalnie)

Jeśli chcesz, aby /home/node przetrwał ponowne tworzenie kontenera, ustaw nazwany wolumen przez OPENCLAW_HOME_VOLUME. Spowoduje to utworzenie wolumenu Dockera i zamontowanie go w /home/node, przy jednoczesnym zachowaniu standardowych bind mountów konfiguracji/obszaru roboczego. Użyj tutaj nazwanego wolumenu (nie ścieżki bind); dla bind mountów użyj OPENCLAW_EXTRA_MOUNTS. Przykład: 
export OPENCLAW_HOME_VOLUME="openclaw_home"
./docker-setup.sh
Możesz to połączyć z dodatkowymi mountami: 
export OPENCLAW_HOME_VOLUME="openclaw_home"
export OPENCLAW_EXTRA_MOUNTS="$HOME/.codex:/home/node/.codex:ro,$HOME/github:/home/node/github:rw"
./docker-setup.sh
Uwagi:
  • Jeśli zmienisz OPENCLAW_HOME_VOLUME, uruchom ponownie docker-setup.sh, aby wygenerować dodatkowy plik compose.
  • Nazwany wolumen pozostaje do czasu usunięcia poleceniem docker volume rm <name>.

​
Instalacja dodatkowych pakietów apt (opcjonalnie)

Jeśli potrzebujesz pakietów systemowych w obrazie (np. narzędzi do budowania lub bibliotek multimedialnych), ustaw OPENCLAW_DOCKER_APT_PACKAGES przed uruchomieniem docker-setup.sh. Pakiety są instalowane podczas budowania obrazu, więc pozostają nawet po usunięciu kontenera. Przykład: 
export OPENCLAW_DOCKER_APT_PACKAGES="ffmpeg build-essential"
./docker-setup.sh
Uwagi:
  • Akceptowana jest lista nazw pakietów apt rozdzielona spacjami.
  • Jeśli zmienisz OPENCLAW_DOCKER_APT_PACKAGES, uruchom ponownie docker-setup.sh, aby przebudować obraz.

​
Tryb zaawansowany / pełnofunkcyjny kontener (opt-in)

Domyślny obraz Dockera jest nastawiony na bezpieczeństwo i działa jako nie-rootowy użytkownik node. Zmniejsza to powierzchnię ataku, ale oznacza:
  • brak instalacji pakietów systemowych w czasie działania
  • brak Homebrew domyślnie
  • brak dołączonych przeglądarek Chromium/Playwright
Jeśli chcesz bardziej pełnofunkcyjny kontener, użyj tych opcji opt-in:
  1. Utrwal /home/node, aby pobrania przeglądarek i cache narzędzi przetrwały:
export OPENCLAW_HOME_VOLUME="openclaw_home"
./docker-setup.sh
  1. Wypiecz zależności systemowe w obrazie (powtarzalne + trwałe):
export OPENCLAW_DOCKER_APT_PACKAGES="git curl jq"
./docker-setup.sh
  1. Zainstaluj przeglądarki Playwright bez npx (unika konfliktów nadpisywania npm):
docker compose run --rm openclaw-cli \
  node /app/node_modules/playwright-core/cli.js install chromium
Jeśli potrzebujesz, aby Playwright instalował zależności systemowe, przebuduj obraz z OPENCLAW_DOCKER_APT_PACKAGES zamiast używać --with-deps w czasie działania.
  1. Utrwal pobrania przeglądarek Playwright:
  • Ustaw PLAYWRIGHT_BROWSERS_PATH=/home/node/.cache/ms-playwright w docker-compose.yml.
  • Upewnij się, że /home/node jest utrwalone przez OPENCLAW_HOME_VOLUME, albo zamontuj /home/node/.cache/ms-playwright przez OPENCLAW_EXTRA_MOUNTS.

​
Uprawnienia + EACCES

Obraz działa jako node (uid 1000). Jeśli widzisz błędy uprawnień na /home/node/.openclaw, upewnij się, że bind mounty hosta należą do uid 1000. Przykład (host Linux): 
sudo chown -R 1000:1000 /path/to/openclaw-config /path/to/openclaw-workspace
Jeśli zdecydujesz się uruchamiać jako root dla wygody, akceptujesz kompromis bezpieczeństwa.

​
Szybsze przebudowy (zalecane)

Aby przyspieszyć przebudowy, uporządkuj Dockerfile tak, aby warstwy zależności były buforowane. Pozwala to uniknąć ponownego uruchamiania pnpm install, o ile nie zmienią się pliki lock: 
FROM node:22-bookworm

# Install Bun (required for build scripts)
RUN curl -fsSL https://bun.sh/install | bash
ENV PATH="/root/.bun/bin:${PATH}"

RUN corepack enable

WORKDIR /app

# Cache dependencies unless package metadata changes
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"]

​
Konfiguracja kanałów (opcjonalnie)

Użyj kontenera CLI do skonfigurowania kanałów, a następnie w razie potrzeby zrestartuj bramę. WhatsApp (QR): 
docker compose run --rm openclaw-cli channels login
Telegram (token bota): 
docker compose run --rm openclaw-cli channels add --channel telegram --token "<token>"
Discord (token bota): 
docker compose run --rm openclaw-cli channels add --channel discord --token "<token>"
Dokumentacja: WhatsApp, Telegram, Discord

​
OpenAI Codex OAuth (Docker bez interfejsu)

Jeśli w kreatorze wybierzesz OpenAI Codex OAuth, otworzy on adres URL w przeglądarce i spróbuje przechwycić callback na http://127.0.0.1:1455/auth/callback. W Dockerze lub konfiguracjach bez interfejsu callback może wyświetlić błąd przeglądarki. Skopiuj pełny adres URL przekierowania, na którym wylądujesz, i wklej go z powrotem do kreatora, aby zakończyć uwierzytelnianie.

​
Kontrola zdrowia

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

​
Test dymny E2E (Docker)

scripts/e2e/onboard-docker.sh

​
Test dymny importu QR (Docker)

pnpm test:docker:qr

​
Uwagi

  • Bind bramy domyślnie wiąże się z lan do użycia w kontenerze.
  • CMD w Dockerfile używa --allow-unconfigured; zamontowana konfiguracja z gateway.mode, a nie local, nadal się uruchomi. Nadpisz CMD, aby wymusić strażnika.
  • Kontener bramy jest źródłem prawdy dla sesji (~/.openclaw/agents/<agentId>/sessions/).

​
Sandbox agenta (host bramy + narzędzia Docker)

Dogłębnie: Sandboxing

​
Co to robi

Gdy włączone jest agents.defaults.sandbox, sesje inne niż główna uruchamiają narzędzia wewnątrz kontenera Dockera. Brama pozostaje na hoście, ale wykonanie narzędzi jest izolowane:
  • zakres: "agent" domyślnie (jeden kontener + obszar roboczy na agenta)
  • zakres: "session" dla izolacji na sesję
  • katalog obszaru roboczego na zakres montowany w /workspace
  • opcjonalny dostęp do obszaru roboczego agenta (agents.defaults.sandbox.workspaceAccess)
  • polityka narzędzi allow/deny (deny ma pierwszeństwo)
  • media przychodzące są kopiowane do aktywnego obszaru roboczego sandboxa (media/inbound/*), aby narzędzia mogły je czytać (z workspaceAccess: "rw" trafia to do obszaru roboczego agenta)
Ostrzeżenie: scope: "shared" wyłącza izolację między sesjami. Wszystkie sesje współdzielą jeden kontener i jeden obszar roboczy.

​
Profile sandboxa na agenta (wiele agentów)

Jeśli używasz routingu wielu agentów, każdy agent może nadpisać ustawienia sandboxa + narzędzi: agents.list[].sandbox i agents.list[].tools (oraz agents.list[].tools.sandbox.tools). Pozwala to uruchamiać mieszane poziomy dostępu w jednej bramie:
  • Pełny dostęp (agent osobisty)
  • Narzędzia tylko do odczytu + obszar roboczy tylko do odczytu (agent rodzinny/roboczy)
  • Brak narzędzi systemu plików/powłoki (agent publiczny)
Zobacz Multi-Agent Sandbox & Tools po przykłady, priorytety i rozwiązywanie problemów.

​
Zachowanie domyślne

  • Obraz: openclaw-sandbox:bookworm-slim
  • Jeden kontener na agenta
  • Dostęp do obszaru roboczego agenta: workspaceAccess: "none" (domyślnie) używa ~/.openclaw/sandboxes
    • "ro" utrzymuje obszar roboczy sandboxa w /workspace i montuje obszar roboczy agenta tylko do odczytu w /agent (wyłącza write/edit/apply_patch)
    • "rw" montuje obszar roboczy agenta do odczytu/zapisu w /workspace
  • Auto-pruning: bezczynność > 24 h LUB wiek > 7 dni
  • Sieć: none domyślnie (jawnie włącz, jeśli potrzebujesz wyjścia)
  • Domyślnie dozwolone: exec, process, read, write, edit, sessions_list, sessions_history, sessions_send, sessions_spawn, session_status
  • Domyślnie zabronione: browser, canvas, nodes, cron, discord, gateway

​
Włącz sandboxing

Jeśli planujesz instalować pakiety w setupCommand, zwróć uwagę:
  • Domyślne docker.network to "none" (brak wyjścia).
  • readOnlyRoot: true blokuje instalację pakietów.
  • user musi być rootem dla apt-get (pomiń user lub ustaw user: "0:0"). OpenClaw automatycznie odtwarza kontenery, gdy zmienia się setupCommand (lub konfiguracja Dockera), chyba że kontener był niedawno używany (w ciągu ~5 minut). Gorące kontenery logują ostrzeżenie z dokładnym poleceniem openclaw sandbox recreate ....
{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main", // off | non-main | all
        scope: "agent", // session | agent | shared (agent is default)
        workspaceAccess: "none", // none | ro | rw
        workspaceRoot: "~/.openclaw/sandboxes",
        docker: {
          image: "openclaw-sandbox:bookworm-slim",
          workdir: "/workspace",
          readOnlyRoot: true,
          tmpfs: ["/tmp", "/var/tmp", "/run"],
          network: "none",
          user: "1000:1000",
          capDrop: ["ALL"],
          env: { LANG: "C.UTF-8" },
          setupCommand: "apt-get update && apt-get install -y git curl jq",
          pidsLimit: 256,
          memory: "1g",
          memorySwap: "2g",
          cpus: 1,
          ulimits: {
            nofile: { soft: 1024, hard: 2048 },
            nproc: 256,
          },
          seccompProfile: "/path/to/seccomp.json",
          apparmorProfile: "openclaw-sandbox",
          dns: ["1.1.1.1", "8.8.8.8"],
          extraHosts: ["internal.service:10.0.0.5"],
        },
        prune: {
          idleHours: 24, // 0 disables idle pruning
          maxAgeDays: 7, // 0 disables max-age pruning
        },
      },
    },
  },
  tools: {
    sandbox: {
      tools: {
        allow: [
          "exec",
          "process",
          "read",
          "write",
          "edit",
          "sessions_list",
          "sessions_history",
          "sessions_send",
          "sessions_spawn",
          "session_status",
        ],
        deny: ["browser", "canvas", "nodes", "cron", "discord", "gateway"],
      },
    },
  },
}
Ustawienia utwardzania znajdują się pod agents.defaults.sandbox.docker: network, user, pidsLimit, memory, memorySwap, cpus, ulimits, seccompProfile, apparmorProfile, dns, extraHosts. Wiele agentów: nadpisz agents.defaults.sandbox.{docker,browser,prune}.* na agenta przez agents.list[].sandbox.{docker,browser,prune}.* (ignorowane, gdy agents.defaults.sandbox.scope / agents.list[].sandbox.scope to "shared").

​
Zbuduj domyślny obraz sandboxa

scripts/sandbox-setup.sh
To buduje openclaw-sandbox:bookworm-slim przy użyciu Dockerfile.sandbox.

​
Wspólny obraz sandboxa (opcjonalnie)

Jeśli chcesz obraz sandboxa z typowymi narzędziami do budowania (Node, Go, Rust itd.), zbuduj wspólny obraz: 
scripts/sandbox-common-setup.sh
To buduje openclaw-sandbox-common:bookworm-slim. Aby go użyć: 
{
  agents: {
    defaults: {
      sandbox: { docker: { image: "openclaw-sandbox-common:bookworm-slim" } },
    },
  },
}

​
Obraz przeglądarki sandboxa

Aby uruchomić narzędzie przeglądarki w sandboxie, zbuduj obraz przeglądarki: 
scripts/sandbox-browser-setup.sh
To buduje openclaw-sandbox-browser:bookworm-slim przy użyciu Dockerfile.sandbox-browser. Kontener uruchamia Chromium z włączonym CDP oraz opcjonalnym obserwatorem noVNC (tryb graficzny przez Xvfb). Uwagi:
  • Tryb graficzny (Xvfb) zmniejsza blokowanie botów w porównaniu do headless.
  • Headless nadal można użyć, ustawiając agents.defaults.sandbox.browser.headless=true.
  • Pełne środowisko desktopowe (GNOME) nie jest wymagane; Xvfb zapewnia wyświetlacz.
Użyj konfiguracji: 
{
  agents: {
    defaults: {
      sandbox: {
        browser: { enabled: true },
      },
    },
  },
}
Niestandardowy obraz przeglądarki: 
{
  agents: {
    defaults: {
      sandbox: { browser: { image: "my-openclaw-browser" } },
    },
  },
}
Po włączeniu agent otrzymuje:
  • adres URL sterowania przeglądarką sandboxa (dla narzędzia browser)
  • adres URL noVNC (jeśli włączone i headless=false)
Pamiętaj: jeśli używasz listy dozwolonych narzędzi, dodaj browser (i usuń z deny), w przeciwnym razie narzędzie pozostanie zablokowane. Zasady czyszczenia (agents.defaults.sandbox.prune) dotyczą także kontenerów przeglądarki.

​
Niestandardowy obraz sandboxa

Zbuduj własny obraz i wskaż go w konfiguracji: 
docker build -t my-openclaw-sbx -f Dockerfile.sandbox .

{
  agents: {
    defaults: {
      sandbox: { docker: { image: "my-openclaw-sbx" } },
    },
  },
}

​
Polityka narzędzi (allow/deny)

  • deny ma pierwszeństwo nad allow.
  • Jeśli allow jest puste: wszystkie narzędzia (poza deny) są dostępne.
  • Jeśli allow nie jest puste: dostępne są tylko narzędzia z allow (minus deny).

​
Strategia czyszczenia

Dwa parametry:
  • prune.idleHours: usuń kontenery nieużywane przez X godzin (0 = wyłącz)
  • prune.maxAgeDays: usuń kontenery starsze niż X dni (0 = wyłącz)
Przykład:
  • Zachowaj aktywne sesje, ale ogranicz czas życia: idleHours: 24, maxAgeDays: 7
  • Nigdy nie czyść: idleHours: 0, maxAgeDays: 0

​
Uwagi dotyczące bezpieczeństwa

  • Twarda izolacja dotyczy wyłącznie narzędzi (exec/read/write/edit/apply_patch).
  • Narzędzia tylko-hostowe, takie jak browser/camera/canvas, są domyślnie zablokowane.
  • Zezwolenie na browser w sandboxie łamie izolację (przeglądarka działa na hoście).

​
Rozwiązywanie problemów

  • Brak obrazu: zbuduj przy użyciu scripts/sandbox-setup.sh lub ustaw agents.defaults.sandbox.docker.image.
  • Kontener nie działa: zostanie automatycznie utworzony na żądanie dla sesji.
  • Błędy uprawnień w sandboxie: ustaw docker.user na UID:GID odpowiadające własności zamontowanego obszaru roboczego (lub wykonaj chown na katalogu obszaru roboczego).
  • Nie znaleziono narzędzi niestandardowych: OpenClaw uruchamia polecenia z sh -lc (powłoka logowania), która źródłuje /etc/profile i może resetować PATH. Ustaw docker.env.PATH, aby poprzedzić własne ścieżki narzędzi (np. /custom/bin:/usr/local/share/npm-global/bin), albo dodaj skrypt w /etc/profile.d/ w swoim Dockerfile.