Docker

Docker ist optional. Verwenden Sie es nur, wenn Sie ein containerisiertes Gateway möchten oder den Docker-Ablauf validieren wollen.

# 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 arbeiten auf Ihrem eigenen Rechner und möchten nur den schnellsten Entwicklungsablauf. Verwenden Sie stattdessen den normalen Installationsablauf.
• Hinweis zum Sandboxing: Das standardmäßige Sandbox-Backend verwendet Docker, wenn Sandboxing aktiviert ist, aber Sandboxing ist standardmäßig deaktiviert und erfordert nicht, dass das 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 RAM per OOM mit Exit 137 beendet werden)
• Ausreichend Speicherplatz für Images und Logs
• Wenn Sie auf einem VPS/öffentlichen Host arbeiten, lesen Sie Sicherheitshärtung für Netzwerkexposition, insbesondere die Docker-Firewall-Richtlinie DOCKER-USER.

# Containerisiertes Gateway

./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>"

# Manueller Ablauf

Wenn Sie jeden Schritt lieber selbst ausführen möchten, anstatt 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-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

# Umgebungsvariablen

Das Setup-Skript akzeptiert diese optionalen Umgebungsvariablen:

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

# Observability

Der OpenTelemetry-Export erfolgt ausgehend vom Gateway-Container zu Ihrem OTLP- Collector. Er erfordert keinen veröffentlichten Docker-Port. Wenn Sie das Image lokal erstellen und den gebündelten OpenTelemetry-Exporter im Image verfügbar haben möchten, binden Sie seine Laufzeitabhä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 Plugin @openclaw/diagnostics-otel aus ClawHub in paketierten Docker-Installationen, bevor Sie den Export aktivieren. Benutzerdefinierte aus dem Quellcode erstellte Images können die lokale Plugin-Quelle weiterhin mit OPENCLAW_EXTENSIONS=diagnostics-otel einbinden. Um den Export zu aktivieren, erlauben und aktivieren Sie das Plugin diagnostics-otel in der Konfiguration, und setzen Sie dann diagnostics.otel.enabled=true oder verwenden Sie das Konfigurationsbeispiel in 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 Plugin diagnostics-prometheus, und scrapen Sie dann:

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

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

# Health Checks

Container-Probe-Endpunkte (keine Authentifizierung erforderlich):

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

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

Authentifizierter Deep-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-Veröffentlichung funktioniert.

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

# Host Local Providers

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

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

Host-Dienste müssen außerdem auf einer aus Docker erreichbaren Adresse lauschen:

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

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

# Bonjour / mDNS

Docker-Bridge-Networking leitet Bonjour-/mDNS-Multicast (224.0.0.251:5353) normalerweise nicht zuverlässig weiter. Das gebündelte Compose-Setup setzt daher standardmäßig OPENCLAW_DISABLE_BONJOUR=1, damit das Gateway keine Crash-Loop ausführt oder die Ankündigung wiederholt 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.

Gotchas und Fehlerbehebung finden Sie unter Bonjour-Erkennung.

# Speicher und Persistenz

Docker Compose bind-mountet OPENCLAW_CONFIG_DIR nach /home/node/.openclaw und OPENCLAW_WORKSPACE_DIR nach /home/node/.openclaw/workspace, sodass diese Pfade Container-Ersetzungen überdauern. Wenn eine der Variablen nicht gesetzt ist, fällt das gebündelte docker-compose.yml auf ${HOME}/.openclaw (und ${HOME}/.openclaw/workspace für den Workspace-Mount) zurück, oder auf /tmp/.openclaw, wenn HOME selbst ebenfalls fehlt. Dadurch wird verhindert, dass docker compose up in leeren Umgebungen eine Volume-Spezifikation mit leerer Quelle ausgibt.

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 Laufzeitgeheimnisse wie OPENCLAW_GATEWAY_TOKEN

Installierte herunterladbare Plugins speichern ihren Paketstatus im gemounteten OpenClaw-Home, sodass Plugin-Installationsdatensätze und Paket-Roots Container- Ersetzungen überdauern. Der Gateway-Start erzeugt keine Abhängigkeitsbäume für gebündelte Plugins.

Vollständige Persistenzdetails zu VM-Bereitstellungen finden Sie unter Docker VM Runtime - Was wo persistiert.

Hotspots für Festplattenwachstum: beobachten Sie media/, Sitzungs-JSONL-Dateien, cron/runs/*.jsonl, installierte Plugin-Paket-Roots und rollierende 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.sh
echo '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 obigen Installationsbefehl erneut aus, damit Ihre lokale Helferdatei den neuen Speicherort nachverfolgt.

Verwenden Sie dann clawdock-start, clawdock-stop, clawdock-dashboard usw. Führen Sie clawdock-help aus, um alle Befehle anzuzeigen. Siehe ClawDock für die vollständige Helferanleitung.

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

# Ausführung auf einem VPS?

Siehe Hetzner (Docker-VPS) und Docker-VM-Runtime für Bereitstellungsschritte auf gemeinsam genutzten VMs einschließlich Einbacken von Binärdateien, Persistenz und Updates.

# Agent-Sandbox

Wenn agents.defaults.sandbox mit dem Docker-Backend aktiviert ist, führt das Gateway die Ausführung von Agent-Tools (Shell, Lesen/Schreiben von Dateien usw.) innerhalb isolierter Docker- Container aus, während das Gateway selbst auf dem Host bleibt. Dadurch erhalten Sie eine feste Trennung um nicht vertrauenswürdige oder mandantenfähige Agent-Sitzungen, ohne das gesamte Gateway zu containerisieren.

Der Sandbox-Geltungsbereich kann pro Agent (Standard), pro Sitzung oder gemeinsam sein. Jeder Geltungsbereich erhält einen eigenen Workspace, der unter /workspace eingebunden wird. Sie können außerdem Tool-Richtlinien für Zulassen/Verweigern, Netzwerkisolierung, Ressourcenlimits und Browser- Container konfigurieren.

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 -- agentenspezifische Overrides

# 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 siehe Sandboxing § Images und Einrichtung für Inline-docker build-Befehle.

# Fehlerbehebung

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

# Verwandte Themen

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