Docker (optional)

Docker ist optional. Nutze es nur, wenn du ein containerisiertes Gateway möchtest oder den Docker-Ablauf testen willst.

Ist Docker das Richtige für mich?

  • Ja: Du möchtest eine isolierte, wegwerfbare Gateway-Umgebung oder OpenClaw auf einem Host ohne lokale Installation betreiben.
  • Nein: Du arbeitest auf deinem eigenen Rechner und willst den schnellsten Entwicklungszyklus. Nutze stattdessen die normale Installation.
  • Hinweis zu Sandboxing: Agent-Sandboxing nutzt ebenfalls Docker, erfordert aber nicht, dass das komplette Gateway in Docker läuft. Siehe Sandboxing.

Diese Anleitung behandelt:

  • Containerisiertes Gateway (komplettes OpenClaw in Docker)
  • Per-Session Agent Sandbox (Host-Gateway + Docker-isolierte Agent-Tools)

Details zum Sandboxing: Sandboxing

Voraussetzungen

  • Docker Desktop (oder Docker Engine) + Docker Compose v2
  • Genügend Speicherplatz für Images + Logs

Containerisiertes Gateway (Docker Compose)

Schnellstart (empfohlen)

Vom Repo-Root aus:

./docker-setup.sh

Dieses Skript:

  • baut das Gateway-Image
  • führt den Onboarding-Wizard aus
  • zeigt optionale Provider-Setup-Hinweise
  • startet das Gateway via Docker Compose
  • generiert einen Gateway-Token und schreibt ihn in .env

Optionale Umgebungsvariablen:

  • OPENCLAW_DOCKER_APT_PACKAGES — installiert zusätzliche apt-Pakete beim Build
  • OPENCLAW_EXTRA_MOUNTS — fügt zusätzliche Host-Bind-Mounts hinzu
  • OPENCLAW_HOME_VOLUME — persistiert /home/node in einem benannten Volume

Nach Abschluss:

  • Öffne http://127.0.0.1:18789/ im Browser.
  • Füge den Token in der Control UI ein (Settings → token).

Konfiguration und Workspace werden auf dem Host gespeichert:

  • ~/.openclaw/
  • ~/.openclaw/workspace

Läuft auf einem VPS? Siehe Hetzner (Docker VPS).

Manueller Ablauf (Compose)

docker build -t openclaw:local -f Dockerfile .
docker compose run --rm openclaw-cli onboard
docker compose up -d openclaw-gateway

Zusätzliche Mounts (optional)

Wenn du weitere Host-Verzeichnisse in die Container mounten möchtest, setze OPENCLAW_EXTRA_MOUNTS vor dem Ausführen von docker-setup.sh. Das akzeptiert eine kommagetrennte Liste von Docker-Bind-Mounts und wendet sie auf beide Container openclaw-gateway und openclaw-cli an, indem docker-compose.extra.yml generiert wird.

Beispiel:

export OPENCLAW_EXTRA_MOUNTS="$HOME/.codex:/home/node/.codex:ro,$HOME/github:/home/node/github:rw"
./docker-setup.sh

Hinweise:

  • Pfade müssen mit Docker Desktop auf macOS/Windows geteilt sein.
  • Wenn du OPENCLAW_EXTRA_MOUNTS änderst, führe docker-setup.sh erneut aus, um die extra Compose-Datei neu zu generieren.
  • docker-compose.extra.yml wird generiert. Bearbeite sie nicht manuell.

Container-Home persistieren (optional)

Wenn du möchtest, dass /home/node über Container-Neuerstellungen hinweg erhalten bleibt, setze ein benanntes Volume via OPENCLAW_HOME_VOLUME. Das erstellt ein Docker-Volume und mountet es unter /home/node, während die Standard-Config/Workspace-Bind-Mounts erhalten bleiben. Nutze hier ein benanntes Volume (keinen Bind-Pfad); für Bind-Mounts nutze OPENCLAW_EXTRA_MOUNTS.

Beispiel:

export OPENCLAW_HOME_VOLUME="openclaw_home"
./docker-setup.sh

Du kannst das mit zusätzlichen Mounts kombinieren:

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

Hinweise:

  • Wenn du OPENCLAW_HOME_VOLUME änderst, führe docker-setup.sh erneut aus, um die extra Compose-Datei neu zu generieren.
  • Das benannte Volume bleibt bestehen, bis es mit docker volume rm <name> entfernt wird.

Zusätzliche apt-Pakete installieren (optional)

Wenn du Systempakete im Image brauchst (zum Beispiel Build-Tools oder Media- Bibliotheken), setze OPENCLAW_DOCKER_APT_PACKAGES vor dem Ausführen von docker-setup.sh. Das installiert die Pakete während des Image-Builds, sodass sie auch nach dem Löschen des Containers erhalten bleiben.

Beispiel:

export OPENCLAW_DOCKER_APT_PACKAGES="ffmpeg build-essential"
./docker-setup.sh

Hinweise:

  • Das akzeptiert eine leerzeichengetrennte Liste von apt-Paketnamen.
  • Wenn du OPENCLAW_DOCKER_APT_PACKAGES änderst, führe docker-setup.sh erneut aus, um das Image neu zu bauen.

Schnellere Rebuilds (empfohlen)

Um Rebuilds zu beschleunigen, ordne dein Dockerfile so an, dass Dependency-Layer gecacht werden. Das vermeidet erneutes Ausführen von pnpm install, solange sich die Lockfiles nicht ändern:

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"]

Channel-Setup (optional)

Nutze den CLI-Container, um Channels zu konfigurieren, und starte das Gateway bei Bedarf neu.

WhatsApp (QR):

docker compose run --rm openclaw-cli channels login

Telegram (Bot-Token):

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

Discord (Bot-Token):

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

Dokumentation: WhatsApp, Telegram, Discord

Health Check

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

E2E Smoke Test (Docker)

scripts/e2e/onboard-docker.sh

QR-Import Smoke Test (Docker)

pnpm test:docker:qr

Hinweise

  • Gateway-Bind ist standardmäßig auf lan für Container-Nutzung eingestellt.
  • Der Gateway-Container ist die Quelle der Wahrheit für Sessions (~/.openclaw/agents/<agentId>/sessions/).

Agent Sandbox (Host-Gateway + Docker-Tools)

Ausführliche Infos: Sandboxing

Was es macht

Wenn agents.defaults.sandbox aktiviert ist, laufen Nicht-Main-Sessions Tools in einem Docker- Container. Das Gateway bleibt auf deinem Host, aber die Tool-Ausführung ist isoliert:

  • scope: "agent" standardmäßig (ein Container + Workspace pro Agent)
  • scope: "session" für Per-Session-Isolation
  • Per-Scope-Workspace-Ordner gemountet unter /workspace
  • optionaler Agent-Workspace-Zugriff (agents.defaults.sandbox.workspaceAccess)
  • allow/deny Tool-Policy (deny gewinnt)
  • eingehende Medien werden in den aktiven Sandbox-Workspace kopiert (media/inbound/*), damit Tools sie lesen können (mit workspaceAccess: "rw" landet das im Agent-Workspace)

Warnung: scope: "shared" deaktiviert Cross-Session-Isolation. Alle Sessions teilen sich einen Container und einen Workspace.

Per-Agent Sandbox-Profile (Multi-Agent)

Wenn du Multi-Agent-Routing nutzt, kann jeder Agent Sandbox- und Tool-Einstellungen überschreiben: agents.list[].sandbox und agents.list[].tools (plus agents.list[].tools.sandbox.tools). Das ermöglicht verschiedene Zugriffsebenen in einem Gateway:

  • Voller Zugriff (persönlicher Agent)
  • Read-only Tools + Read-only Workspace (Familie/Arbeit Agent)
  • Keine Dateisystem/Shell-Tools (öffentlicher Agent)

Siehe Multi-Agent Sandbox & Tools für Beispiele, Prioritäten und Troubleshooting.

Standardverhalten

  • Image: openclaw-sandbox:bookworm-slim
  • Ein Container pro Agent
  • Agent-Workspace-Zugriff: workspaceAccess: "none" (Standard) nutzt ~/.openclaw/sandboxes
    • "ro" behält den Sandbox-Workspace unter /workspace und mountet den Agent-Workspace read-only unter /agent (deaktiviert write/edit/apply_patch)
    • "rw" mountet den Agent-Workspace read/write unter /workspace
  • Auto-Prune: idle > 24h ODER Alter > 7d
  • Netzwerk: standardmäßig none (explizit opt-in, wenn du Egress brauchst)
  • Standard-Allow: exec, process, read, write, edit, sessions_list, sessions_history, sessions_send, sessions_spawn, session_status
  • Standard-Deny: browser, canvas, nodes, cron, discord, gateway

Sandboxing aktivieren

Wenn du Pakete in setupCommand installieren möchtest, beachte:

  • Standard docker.network ist "none" (kein Egress).
  • readOnlyRoot: true blockiert Paketinstallationen.
  • user muss root sein für apt-get (lass user weg oder setze user: "0:0"). OpenClaw erstellt Container automatisch neu, wenn sich setupCommand (oder Docker-Config) ändert, es sei denn, der Container wurde kürzlich verwendet (innerhalb von ~5 Minuten). Hot Container loggen eine Warnung mit dem genauen openclaw sandbox recreate ... Befehl.
{
  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"],
      },
    },
  },
}

Hardening-Optionen befinden sich unter agents.defaults.sandbox.docker: network, user, pidsLimit, memory, memorySwap, cpus, ulimits, seccompProfile, apparmorProfile, dns, extraHosts.

Multi-Agent: Überschreibe agents.defaults.sandbox.{docker,browser,prune}.* pro Agent via agents.list[].sandbox.{docker,browser,prune}.* (wird ignoriert, wenn agents.defaults.sandbox.scope / agents.list[].sandbox.scope auf "shared" steht).

Standard-Sandbox-Image bauen

scripts/sandbox-setup.sh

Das baut openclaw-sandbox:bookworm-slim mit Dockerfile.sandbox.

Sandbox Common Image (optional)

Wenn du ein Sandbox-Image mit gängigen Build-Tools (Node, Go, Rust, etc.) möchtest, baue das Common Image:

scripts/sandbox-common-setup.sh

Das baut openclaw-sandbox-common:bookworm-slim. Um es zu nutzen:

{
  agents: {
    defaults: {
      sandbox: { docker: { image: "openclaw-sandbox-common:bookworm-slim" } },
    },
  },
}

Sandbox Browser Image

Um das Browser-Tool in der Sandbox auszuführen, baue das Browser-Image:

scripts/sandbox-browser-setup.sh

Das baut openclaw-sandbox-browser:bookworm-slim mit Dockerfile.sandbox-browser. Der Container führt Chromium mit aktiviertem CDP und einem optionalen noVNC-Observer aus (headful via Xvfb).

Hinweise:

  • Headful (Xvfb) reduziert Bot-Blocking im Vergleich zu Headless.
  • Headless kann weiterhin genutzt werden durch Setzen von agents.defaults.sandbox.browser.headless=true.
  • Keine vollständige Desktop-Umgebung (GNOME) nötig; Xvfb stellt das Display bereit.

Konfiguration:

{
  agents: {
    defaults: {
      sandbox: {
        browser: { enabled: true },
      },
    },
  },
}

Eigenes Browser-Image:

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

Wenn aktiviert, erhält der Agent:

  • eine Sandbox-Browser-Control-URL (für das browser-Tool)
  • eine noVNC-URL (wenn aktiviert und headless=false)

Beachte: Wenn du eine Allowlist für Tools nutzt, füge browser hinzu (und entferne es aus deny), sonst bleibt das Tool blockiert. Prune-Regeln (agents.defaults.sandbox.prune) gelten auch für Browser-Container.

Eigenes Sandbox-Image

Baue dein eigenes Image und verweise in der Config darauf:

docker build -t my-openclaw-sbx -f Dockerfile.sandbox .
{
  agents: {
    defaults: {
      sandbox: { docker: { image: "my-openclaw-sbx" } },
    },
  },
}

Tool-Policy (allow/deny)

  • deny gewinnt über allow.
  • Wenn allow leer ist: alle Tools (außer deny) sind verfügbar.
  • Wenn allow nicht leer ist: nur Tools in allow sind verfügbar (minus deny).

Pruning-Strategie

Zwei Einstellungen:

  • prune.idleHours: entfernt Container, die X Stunden nicht genutzt wurden (0 = deaktiviert)
  • prune.maxAgeDays: entfernt Container, die älter als X Tage sind (0 = deaktiviert)

Beispiel:

  • Aktive Sessions behalten, aber Lebensdauer begrenzen: idleHours: 24, maxAgeDays: 7
  • Nie prunen: idleHours: 0, maxAgeDays: 0

Sicherheitshinweise

  • Die harte Grenze gilt nur für Tools (exec/read/write/edit/apply_patch).
  • Host-only Tools wie browser/camera/canvas sind standardmäßig blockiert.
  • Das Erlauben von browser in der Sandbox bricht die Isolation (Browser läuft auf dem Host).

Troubleshooting

  • Image fehlt: baue mit scripts/sandbox-setup.sh oder setze agents.defaults.sandbox.docker.image.
  • Container läuft nicht: er wird automatisch pro Session bei Bedarf erstellt.
  • Berechtigungsfehler in der Sandbox: setze docker.user auf eine UID:GID, die zur Ownership deines gemounteten Workspace passt (oder chown den Workspace-Ordner).
  • Eigene Tools nicht gefunden: OpenClaw führt Befehle mit sh -lc (Login-Shell) aus, was /etc/profile sourced und PATH zurücksetzen kann. Setze docker.env.PATH, um deine eigenen Tool-Pfade voranzustellen (z.B. /custom/bin:/usr/local/share/npm-global/bin), oder füge ein Skript unter /etc/profile.d/ in deinem Dockerfile hinzu.