Docker

Docker ist optional. Verwenden Sie es nur, wenn Sie einen containerisierten Gateway wünschen oder den Docker-Ablauf validieren möchten.

Ist Docker das Richtige für mich?

• Ja: Sie möchten eine isolierte, temporäre Gateway-Umgebung oder OpenClaw auf einem Host ohne lokale Installationen ausführen.
• Nein: Sie führen OpenClaw auf Ihrem eigenen Rechner aus und möchten nur die schnellste Entwicklungsschleife. Verwenden Sie stattdessen den normalen Installationsablauf.
• Sandboxing-Hinweis: Das Standard-Sandbox-Backend verwendet Docker, wenn Sandboxing aktiviert ist. Sandboxing ist jedoch standardmäßig deaktiviert und erfordert nicht, dass der gesamte Gateway in Docker ausgeführt wird. SSH- und OpenShell-Sandbox-Backends sind ebenfalls verfügbar. Siehe Sandboxing.

Voraussetzungen

• Docker Desktop (oder Docker Engine) + Docker Compose v2
• Mindestens 2 GB RAM für den Image-Build (pnpm install kann auf Hosts mit 1 GB wegen Speichermangels mit Exit 137 beendet werden)
• Ausreichend Speicherplatz für Images und Logs
• Wenn Sie OpenClaw auf einem VPS/öffentlichen Host ausführen, prüfen Sie Sicherheitshärtung für Netzwerkexposition, insbesondere die Docker-DOCKER-USER-Firewallrichtlinie.

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

Manueller Ablauf

Wenn Sie jeden Schritt lieber selbst ausführen möchten, statt das Setup-Skript zu verwenden:

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

Umgebungsvariablen

Das Setup-Skript akzeptiert diese optionalen Umgebungsvariablen:

Das offizielle Docker-Image enthält kein Homebrew. Während des Onboardings blendet OpenClaw Installationsprogramme für brew-only-Skill-Abhängigkeiten aus, wenn es in einem Linux- Container ohne brew läuft; diese Abhängigkeiten müssen durch ein benutzerdefiniertes Image bereitgestellt oder manuell installiert werden. Für Abhängigkeiten, die als Debian-Pakete verfügbar sind, verwenden Sie OPENCLAW_IMAGE_APT_PACKAGES während des Image-Builds. Der alte Name OPENCLAW_DOCKER_APT_PACKAGES wird weiterhin akzeptiert. Für Python-Abhängigkeiten verwenden Sie OPENCLAW_IMAGE_PIP_PACKAGES. Dies führt python3 -m pip install --break-system-packages während des Image-Builds aus; pinnen Sie daher Paketversionen und verwenden Sie nur Paketindizes, denen Sie vertrauen. Source-Builds setzen OPENCLAW_DOCKER_BUILD_NODE_OPTIONS standardmäßig auf --max-old-space-size=8192 und lassen OPENCLAW_DOCKER_BUILD_TSDOWN_MAX_OLD_SPACE_MB ungesetzt, damit der tsdown-Wrapper Container-Speicherlimits berücksichtigen kann. Außerdem setzen sie standardmäßig OPENCLAW_DOCKER_BUILD_SKIP_DTS=1, da Runtime-Images Deklarationsdateien nach dem Build entfernen. Wenn Docker ResourceExhausted, cannot allocate memory meldet oder während tsdown abbricht, erhöhen Sie das Speicherlimit des Docker-Builders oder versuchen Sie es erneut mit kleineren expliziten Heaps, zum Beispiel OPENCLAW_DOCKER_BUILD_NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_DOCKER_BUILD_TSDOWN_MAX_OLD_SPACE_MB=4096.

Maintainer können gebündelte Plugin-Quellen gegen ein paketiertes Image testen, indem sie ein Plugin-Source-Verzeichnis über dessen paketierten Source-Pfad mounten, zum Beispiel OPENCLAW_EXTRA_MOUNTS=/path/to/fork/extensions/synology-chat:/app/extensions/synology-chat:ro. Dieses gemountete Source-Verzeichnis überschreibt das passende kompilierte /app/dist/extensions/synology-chat-Bundle für dieselbe Plugin-ID.

Observability

OpenTelemetry-Export erfolgt ausgehend vom Gateway-Container zu Ihrem OTLP- Collector. Dafür ist kein veröffentlichter Docker-Port erforderlich. Wenn Sie das Image lokal bauen und möchten, dass der gebündelte OpenTelemetry-Exporter im Image verfügbar ist, schließen Sie seine Runtime-Abhängigkeiten ein:

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

Installieren Sie das offizielle @openclaw/diagnostics-otel-Plugin aus ClawHub in paketierten Docker-Installationen, bevor Sie den Export aktivieren. Benutzerdefinierte source-gebaute Images können die lokale Plugin-Quelle weiterhin mit OPENCLAW_EXTENSIONS=diagnostics-otel einbinden. Um den Export zu aktivieren, erlauben und aktivieren Sie das diagnostics-otel-Plugin in der Konfiguration und setzen Sie dann diagnostics.otel.enabled=true oder verwenden Sie das Konfigurationsbeispiel unter OpenTelemetry- Export. Collector-Auth-Header werden über diagnostics.otel.headers konfiguriert, nicht über Docker-Umgebungsvariablen.

Prometheus-Metriken verwenden den bereits veröffentlichten Gateway-Port. Installieren Sie clawhub:@openclaw/diagnostics-prometheus, aktivieren Sie das diagnostics-prometheus-Plugin und scrapen Sie dann:

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

Die Route ist durch Gateway-Authentifizierung geschützt. Legen Sie keinen separaten öffentlichen /metrics-Port und keinen nicht authentifizierten Reverse-Proxy-Pfad offen. Siehe Prometheus-Metriken.

Health Checks

Container-Probe-Endpunkte (keine Authentifizierung erforderlich):

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

Das Docker-Image enthält einen integrierten HEALTHCHECK, der /healthz anpingt. Wenn Prüfungen weiter fehlschlagen, markiert Docker den Container als unhealthy und Orchestrierungssysteme können ihn neu starten oder ersetzen.

Authentifizierter tiefer Health-Snapshot:

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

LAN vs loopback

scripts/docker/setup.sh setzt standardmäßig OPENCLAW_GATEWAY_BIND=lan, damit Host-Zugriff auf http://127.0.0.1:18789 mit Docker-Port-Publishing funktioniert.

• lan (Standard): Host-Browser und Host-CLI können den veröffentlichten Gateway-Port erreichen.
• loopback: Nur Prozesse innerhalb des Container-Network-Namespace können den Gateway direkt erreichen.

Lokale Host-Provider

Wenn OpenClaw in Docker läuft, ist 127.0.0.1 innerhalb des Containers der Container selbst, nicht Ihr Host-Rechner. Verwenden Sie host.docker.internal für KI-Provider, die auf dem Host laufen:

Das mitgelieferte Docker-Setup verwendet diese Host-URLs als Onboarding-Standardwerte für LM Studio und Ollama, und docker-compose.yml ordnet host.docker.internal dem Host-Gateway von Docker für Linux Docker Engine zu. Docker Desktop stellt denselben Hostnamen auf macOS und Windows bereits bereit.

Host-Dienste müssen außerdem an einer Adresse lauschen, die von Docker aus erreichbar ist:

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

Wenn Sie Ihre eigene Compose-Datei oder einen docker run-Befehl verwenden, fügen Sie dieselbe Host-Zuordnung selbst hinzu, zum Beispiel --add-host=host.docker.internal:host-gateway.

Claude-CLI-Backend in Docker

Das offizielle OpenClaw-Docker-Image installiert Claude Code nicht vor. Installieren Sie Claude Code im Container-Benutzer, der OpenClaw ausführt, melden Sie sich dort an und persistieren Sie anschließend dieses Container-Home, damit Image-Upgrades die Binärdatei oder den Claude-Auth- Status nicht löschen.

Aktivieren Sie bei neuen Docker-Installationen ein persistentes /home/node-Volume, bevor Sie das Setup ausführen:

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

Stoppen Sie bei einer bestehenden Docker-Installation zuerst den Stack und laden Sie die aktuellen Docker-.env-Werte neu, bevor Sie das Setup erneut ausführen. Das Setup-Skript liest .env nicht selbst; es schreibt .env aus der aktuellen Shell und den Standardwerten neu. Führen Sie für die generierte .env Folgendes aus:

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

Wenn Ihre .env Werte enthält, die Ihre Shell nicht sourcen kann, exportieren Sie die bestehenden Werte, auf die Sie angewiesen sind, zuerst manuell neu, zum Beispiel OPENCLAW_IMAGE, Ports, Bind-Modus, benutzerdefinierte Pfade, OPENCLAW_EXTRA_MOUNTS, Sandbox- und Skip-Onboarding-Einstellungen. Das generierte Overlay mountet das Home-Volume sowohl für openclaw-gateway als auch für openclaw-cli.

Führen Sie die übrigen Befehle mit dem generierten Compose-Overlay aus, damit beide Dienste das persistierte Home mounten. Wenn Ihr Setup auch docker-compose.override.yml verwendet, fügen Sie es vor docker-compose.extra.yml ein.

Installieren Sie Claude Code in diesem persistierten Home:

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'

Der native Installer schreibt die claude-Binärdatei unter /home/node/.local/bin/claude. Weisen Sie OpenClaw an, diesen Container-Pfad zu verwenden:

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

Melden Sie sich an und verifizieren Sie aus demselben persistierten Container-Home:

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

Danach können Sie das mitgelieferte claude-cli-Backend verwenden:

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 persistiert die native Claude-Code-Installation unter /home/node/.local/bin und /home/node/.local/share/claude sowie Claude-Code- Einstellungen und Auth-Status unter /home/node/.claude und /home/node/.claude.json. Nur /home/node/.openclaw zu persistieren, reicht für die Wiederverwendung der Claude CLI nicht aus. Wenn Sie OPENCLAW_EXTRA_MOUNTS statt eines Home-Volumes verwenden, mounten Sie alle diese Claude-Pfade in beide Docker-Dienste.

Bonjour / mDNS

Docker-Bridge-Networking leitet Bonjour/mDNS-Multicast (224.0.0.251:5353) in der Regel nicht zuverlässig weiter. Das mitgelieferte Compose-Setup setzt daher standardmäßig OPENCLAW_DISABLE_BONJOUR=1, damit der Gateway nicht in einer Crash-Schleife hängt oder wiederholt die Ankündigung neu startet, wenn die Bridge Multicast-Verkehr verwirft.

Verwenden Sie die veröffentlichte Gateway-URL, Tailscale oder Wide-Area-DNS-SD für Docker-Hosts. Setzen Sie OPENCLAW_DISABLE_BONJOUR=0 nur, wenn Sie mit Host-Networking, macvlan oder einem anderen Netzwerk arbeiten, in dem mDNS-Multicast bekanntermaßen funktioniert.

Fallstricke und Fehlerbehebung finden Sie unter Bonjour-Erkennung.

Speicher und Persistenz

Docker Compose bind-mountet OPENCLAW_CONFIG_DIR nach /home/node/.openclaw, OPENCLAW_WORKSPACE_DIR nach /home/node/.openclaw/workspace und OPENCLAW_AUTH_PROFILE_SECRET_DIR nach /home/node/.config/openclaw, sodass diese Pfade den Austausch von Containern überstehen. Wenn eine Variable nicht gesetzt ist, fällt die mitgelieferte docker-compose.yml unter ${HOME} zurück, oder auf /tmp, wenn auch HOME selbst fehlt. Dadurch gibt docker compose up in nackten Umgebungen keine Volume-Spezifikation mit leerer Quelle aus.

In diesem gemounteten Konfigurationsverzeichnis speichert OpenClaw:

• openclaw.json für Verhaltenskonfiguration
• agents/<agentId>/agent/auth-profiles.json für gespeicherte Provider-OAuth-/API-Key-Authentifizierung
• .env für env-gestützte Runtime-Secrets wie OPENCLAW_GATEWAY_TOKEN

Das Verzeichnis für den Auth-Profil-Geheimschlüssel speichert den lokalen Verschlüsselungsschlüssel, der für OAuth-gestütztes Auth-Profile-Tokenmaterial verwendet wird. Bewahren Sie es mit Ihrem Docker-Host-Status auf, aber getrennt von OPENCLAW_CONFIG_DIR.

Installierte herunterladbare Plugins speichern ihren Paketstatus unter dem gemounteten OpenClaw-Home, sodass Plugin-Installationsdatensätze und Paket-Roots den Austausch von Containern überstehen. Der Gateway-Start generiert keine Dependency-Trees für mitgelieferte Plugins.

Vollständige Persistenzdetails für VM-Deployments finden Sie unter Docker-VM-Runtime - Was wo persistiert.

Hotspots für Festplattenwachstum: Beobachten Sie media/, Sitzungs-JSONL-Dateien, die gemeinsam genutzte SQLite-Statusdatenbank, installierte Plugin-Paket-Roots und rotierende Datei-Logs unter /tmp/openclaw/.

Shell-Helfer (optional)

Installieren Sie für einfachere tägliche Docker-Verwaltung 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

Wenn Sie ClawDock über den älteren Raw-Pfad scripts/shell-helpers/clawdock-helpers.sh installiert haben, führen Sie den Installationsbefehl oben erneut aus, damit Ihre lokale Helferdatei den neuen Speicherort verfolgt.

Verwenden Sie dann clawdock-start, clawdock-stop, clawdock-dashboard usw. Führen Sie clawdock-help für alle Befehle aus. Die vollständige Helferanleitung finden Sie unter 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"]

Ausführung auf einem VPS?

Siehe Hetzner (Docker VPS) und Docker-VM-Runtime für gemeinsame VM-Deployment-Schritte einschließlich Binary-Baking, Persistenz und Updates.

Agent-Sandbox

Wenn agents.defaults.sandbox mit dem Docker-Backend aktiviert ist, führt der Gateway die Ausführung von Agent-Tools (Shell, Dateilesen/-schreiben usw.) in isolierten Docker- Containern aus, während der Gateway selbst auf dem Host bleibt. Dadurch erhalten Sie eine harte Grenze um nicht vertrauenswürdige oder mandantenfähige Agent-Sitzungen, ohne den gesamten Gateway zu containerisieren.

Der Sandbox-Umfang kann pro Agent (Standard), pro Sitzung oder gemeinsam sein. Jeder Umfang erhält einen eigenen Workspace, der unter /workspace gemountet wird. Sie können außerdem Tool-Richtlinien zum Erlauben/Verweigern, Netzwerkisolation, Ressourcenlimits und Browser- Container konfigurieren.

Die vollständige Konfiguration, Images, Sicherheitshinweise und Multi-Agent-Profile finden Sie unter:

• Sandboxing -- vollständige Sandbox-Referenz
• OpenShell -- interaktiver Shell-Zugriff auf Sandbox-Container
• Multi-Agent-Sandbox und Tools -- Überschreibungen pro Agent

Schnell aktivieren

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

Erstellen Sie das Standard-Sandbox-Image (aus einem Source-Checkout):

scripts/sandbox-setup.sh

Für npm-Installationen ohne Source-Checkout finden Sie unter Sandboxing § Images und Einrichtung Inline-Befehle für docker build.

Fehlerbehebung

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

Verwandte Themen

• Installationsübersicht — alle Installationsmethoden
• Podman — Podman-Alternative zu Docker
• ClawDock — Docker Compose-Community-Einrichtung
• Aktualisieren — OpenClaw aktuell halten
• Konfiguration — Gateway-Konfiguration nach der Installation