Containers
Docker
Docker ist optional. Verwenden Sie es für eine isolierte, kurzlebige Gateway-Umgebung oder auf einem Host ohne lokale Installationen. Wenn Sie bereits auf Ihrem eigenen Rechner entwickeln, verwenden Sie stattdessen den normalen Installationsablauf.
Das standardmäßige Sandbox-Backend verwendet Docker, wenn agents.defaults.sandbox aktiviert ist. Sandboxing ist jedoch standardmäßig deaktiviert und setzt nicht voraus, dass das Gateway selbst in Docker ausgeführt wird. SSH- und OpenShell-Sandbox-Backends sind ebenfalls verfügbar; siehe Sandboxing.
Hosten Sie mehrere Benutzer? Informationen zum Modell mit einer Zelle pro Mandant finden Sie unter Mehrmandanten-Hosting.
Voraussetzungen
- Docker Desktop (oder Docker Engine) + Docker Compose v2
- Mindestens 2 GB RAM für den Image-Build (
pnpm installkann auf Hosts mit 1 GB aufgrund von Speichermangel mit Exit-Code 137 beendet werden) - Ausreichend Speicherplatz für Images und Protokolle
- Prüfen Sie auf einem VPS/öffentlichen Host die Sicherheitshärtung für die Netzwerkfreigabe, insbesondere die Docker-Firewall-Kette
DOCKER-USER
Containerisiertes Gateway
Image erstellen
Aus dem Repository-Stammverzeichnis:
./scripts/docker/setup.shDadurch wird das Gateway-Image lokal als openclaw:local erstellt. So verwenden Sie stattdessen ein vorgefertigtes Image:
export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"./scripts/docker/setup.shVorgefertigte Images werden zuerst in der GitHub Container Registry veröffentlicht. GHCR ist die primäre Registry für Release-Automatisierung, fixierte Bereitstellungen und Herkunftsprüfungen. Dasselbe Release veröffentlicht einen Docker-Hub-Spiegel unter openclaw/openclaw:
export OPENCLAW_IMAGE="openclaw/openclaw:latest"./scripts/docker/setup.shVerwenden Sie ghcr.io/openclaw/openclaw oder openclaw/openclaw und vermeiden Sie inoffizielle Spiegel, deren Veröffentlichungszeitpunkte und Aufbewahrungsrichtlinien nicht denen von OpenClaw entsprechen. Offizielle Tags: main, latest, <version> (z. B. 2026.2.26) und Beta-Tags wie 2026.2.26-beta.1 (Betas verschieben niemals latest/main). Das standardmäßige main-/latest-/<version>-Image enthält die Plugins codex und diagnostics-otel. Eine -browser-Variante (z. B. latest-browser) wird zusätzlich mit integriertem Chromium ausgeliefert. Dies ist für das Tool Browser in der Sandbox nützlich, da beim ersten Start keine Playwright-Installation erforderlich ist.
Erneute Ausführung ohne Netzwerkzugang
Übertragen und laden Sie auf Offline-Hosts zunächst das Image:
docker load -i openclaw-image.tarexport OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"./scripts/docker/setup.sh --offline--offline prüft, ob OPENCLAW_IMAGE bereits lokal vorhanden ist, deaktiviert implizite Compose-Downloads und -Builds und führt anschließend den normalen Ablauf aus: Synchronisierung von .env, Berechtigungskorrekturen, Onboarding, Synchronisierung der Gateway-Konfiguration und Compose-Start.
Wenn OPENCLAW_SANDBOX=1 festgelegt ist, prüft die Offline-Einrichtung außerdem die konfigurierten standardmäßigen und agentspezifischen Sandbox-Images auf dem Daemon hinter OPENCLAW_DOCKER_SOCKET, einschließlich des Browser-Vertragslabels auf Docker-basierten Browser-Images. Wenn ein erforderliches Image fehlt oder veraltet ist, wird die Einrichtung beendet, ohne die Sandbox-Konfiguration zu ändern, statt fälschlicherweise einen erfolgreichen Abschluss zu melden.
Onboarding abschließen
Das Einrichtungsskript führt das Onboarding automatisch aus:
- fordert zur Eingabe der Provider-API-Schlüssel auf
- erzeugt ein Gateway-Token und schreibt es in
.env - erstellt das Verzeichnis für den geheimen Schlüssel des Authentifizierungsprofils
- startet das Gateway über Docker Compose
Das Onboarding vor dem Start und Schreibvorgänge an der Konfiguration werden direkt über openclaw-gateway ausgeführt (mit --no-deps --entrypoint node), da openclaw-cli den Netzwerk-Namespace des Gateways verwendet und erst funktioniert, wenn der Gateway-Container vorhanden ist.
Control UI öffnen
Öffnen Sie http://127.0.0.1:18789/ und fügen Sie das in .env geschriebene Token unter Settings ein. Wenn Sie den Container auf Passwortauthentifizierung umgestellt haben, verwenden Sie stattdessen dieses Passwort.
Benötigen Sie die URL erneut?
docker compose run --rm openclaw-cli dashboard --no-openKanäle konfigurieren (optional)
# 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
BUILD_GIT_COMMIT="$(git rev-parse HEAD)"BUILD_TIMESTAMP="$(date -u +%Y-%m-%dT%H:%M:%SZ)"docker build \ --build-arg "GIT_COMMIT=${BUILD_GIT_COMMIT}" \ --build-arg "OPENCLAW_BUILD_TIMESTAMP=${BUILD_TIMESTAMP}" \ -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-gatewayDer Docker-Kontext schließt .git aus. Übergeben Sie die Quellidentität wie oben gezeigt als Build-Argumente, damit der Info-Bildschirm des Images den ausgecheckten Commit und einen Build-Zeitstempel anzeigt. scripts/docker/setup.sh ermittelt und übergibt beide Werte automatisch.
Container-Images aktualisieren
Wenn Sie das OpenClaw-Image ersetzen, aber denselben eingebundenen Zustand und dieselbe Konfiguration beibehalten, führt das neue Gateway vor der Bereitschaft startkompatible Upgrade-Migrationen und eine Plugin-Konvergenz durch. Routinemäßige Image-Aktualisierungen sollten keinen separaten Durchlauf von openclaw doctor --fix erfordern.
Wenn diese Reparaturen beim Start nicht sicher abgeschlossen werden können, wird das Gateway beendet, statt einen fehlerfreien Zustand zu melden. Bei einer Neustartrichtlinie zeigen Docker, Podman oder Kubernetes möglicherweise einen wiederholt neu startenden Gateway-Container an. Behalten Sie das eingebundene Zustands-Volume bei und führen Sie dasselbe Image anschließend einmal mit openclaw doctor --fix als Containerbefehl aus. Verwenden Sie dabei dieselben Zustands- und Konfigurationseinbindungen wie das Gateway:
docker run --rm -v <openclaw-state>:/home/node/.openclaw <image> openclaw doctor --fixpodman run --rm -v <openclaw-state>:/home/node/.openclaw <image> openclaw doctor --fixStarten Sie den Gateway-Container nach Abschluss von Doctor mit seinem Standardbefehl neu. Führen Sie in Kubernetes denselben Befehl in einem einmaligen Job oder Debug-Pod aus, der dasselbe PVC eingebunden hat, und starten Sie anschließend das Deployment oder StatefulSet neu.
Umgebungsvariablen
Optionale Variablen, die von scripts/docker/setup.sh (und für den Gateway-Container direkt von docker-compose.yml) akzeptiert werden:
| Variable | Zweck |
|---|---|
OPENCLAW_IMAGE |
Ein Remote-Image verwenden, statt es lokal zu erstellen |
OPENCLAW_IMAGE_APT_PACKAGES |
Zusätzliche apt-Pakete während des Builds installieren (durch Leerzeichen getrennt). Veralteter Alias: OPENCLAW_DOCKER_APT_PACKAGES |
OPENCLAW_IMAGE_PIP_PACKAGES |
Zusätzliche Python-Pakete während des Builds installieren (durch Leerzeichen getrennt) |
OPENCLAW_EXTENSIONS |
Unterstützte ausgewählte Plugins kompilieren/paketieren und deren Laufzeitabhängigkeiten installieren (durch Kommas oder Leerzeichen getrennte IDs) |
OPENCLAW_DOCKER_BUILD_NODE_OPTIONS |
Node-Optionen für den lokalen Quell-Build überschreiben (Standard: --max-old-space-size=8192) |
OPENCLAW_DOCKER_BUILD_TSDOWN_MAX_OLD_SPACE_MB |
tsdown-Heap für den lokalen Quell-Build in MB überschreiben |
OPENCLAW_DOCKER_BUILD_SKIP_DTS |
Deklarationsausgabe bei lokalen Image-Builds nur für die Laufzeit überspringen (Standard: 1) |
OPENCLAW_INSTALL_BROWSER |
Chromium + Xvfb während des Builds in das Image integrieren |
OPENCLAW_EXTRA_MOUNTS |
Zusätzliche Bind-Mounts des Hosts (durch Kommas getrennt: source:target[:opts]) |
OPENCLAW_HOME_VOLUME |
/home/node in einem benannten Docker-Volume dauerhaft speichern |
OPENCLAW_SANDBOX |
Sandbox-Bootstrap aktivieren (1, true, yes, on) |
OPENCLAW_SKIP_ONBOARDING |
Interaktiven Onboarding-Schritt überspringen (1, true, yes, on) |
OPENCLAW_DOCKER_SOCKET |
Pfad des Docker-Sockets überschreiben |
OPENCLAW_DISABLE_BONJOUR |
Bonjour-/mDNS-Ankündigung erzwingend aktivieren (0) oder deaktivieren (1); siehe Bonjour / mDNS |
OPENCLAW_DISABLE_BUNDLED_SOURCE_OVERLAYS |
Bind-Mount-Overlays für mitgelieferte Plugin-Quellen deaktivieren |
OTEL_EXPORTER_OTLP_ENDPOINT |
Gemeinsamer OTLP-/HTTP-Collector-Endpunkt für den OpenTelemetry-Export |
OTEL_EXPORTER_OTLP_*_ENDPOINT |
Signalspezifische OTLP-Endpunkte für Traces, Metriken oder Protokolle |
OTEL_EXPORTER_OTLP_PROTOCOL |
OTLP-Protokoll überschreiben. Derzeit wird nur http/protobuf unterstützt |
OTEL_SERVICE_NAME |
Für OpenTelemetry-Ressourcen verwendeter Dienstname |
OTEL_SEMCONV_STABILITY_OPT_IN |
Neueste experimentelle semantische GenAI-Attribute aktivieren |
OPENCLAW_OTEL_PRELOADED |
Start eines zweiten OpenTelemetry SDK überspringen, wenn bereits eines vorgeladen ist |
Das offizielle Image enthält kein Homebrew. Während des Onboardings blendet OpenClaw in einem Linux-Container ohne brew Abhängigkeitsinstaller für Skills aus, die ausschließlich brew unterstützen; stellen Sie diese Abhängigkeiten über ein benutzerdefiniertes Image bereit oder installieren Sie sie manuell. Verwenden Sie OPENCLAW_IMAGE_APT_PACKAGES für als Debian-Pakete verfügbare Abhängigkeiten und OPENCLAW_IMAGE_PIP_PACKAGES für Python-Abhängigkeiten (führt während des Builds python3 -m pip install --break-system-packages aus; fixieren Sie daher Versionen und verwenden Sie nur Indizes, denen Sie vertrauen).
Wenn Docker ResourceExhausted oder cannot allocate memory meldet oder während tsdown abbricht, erhöhen Sie das Speicherlimit des Docker-Builders oder versuchen Sie es mit kleineren expliziten Heap-Größen erneut:
OPENCLAW_DOCKER_BUILD_NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_DOCKER_BUILD_TSDOWN_MAX_OLD_SPACE_MB=4096Aus dem Quellcode erstellte Images mit ausgewählten Plugins
OPENCLAW_EXTENSIONS wählt Plugin-Manifest-IDs aus dem Quellcode-Checkout aus;
bestehende Namen von Quellverzeichnissen werden ebenfalls akzeptiert, wenn sie abweichen. Der Docker-
Build löst die Auswahl einmalig in Quellverzeichnisse auf, installiert Produktions-
abhängigkeiten und kompiliert, wenn ein ausgewähltes Plugin separat mit
openclaw.build.bundledDist: false veröffentlicht wird, dessen Runtime in die gebündelte Root-
Distribution. Diese ausschließlich für Docker bestimmte Paketierung ändert nicht den npm- oder ClawHub-
Artefaktvertrag des Plugins. Unbekannte, ungültige oder mehrdeutige IDs lassen den Image-Build fehlschlagen.
Bekannte reine Abhängigkeits-/Quellcode-IDs behalten ihr bestehendes Quellcode- und Abhängigkeits-
Staging, ohne einen kompilierten Eintrag in der Root-Distribution zu erhalten. Ein ausgewähltes Plugin mit
vereinheitlichten Build-Einträgen muss erfolgreich kompiliert werden; nicht ausgewählter externer Plugin-
Quellcode und dessen Runtime-Ausgabe werden entfernt.
Diese Befehle erstellen beispielsweise separate, eigenständige Multi-Architektur-
Gateway-Images von FakeCo für ClickClack, Slack und Microsoft Teams. ClawRouter ist
bereits Teil der OpenClaw-Root-Runtime, daher wählt das ClickClack-Image nur
clickclack aus. Das explizit leere Browser-Argument hält das Standard-Image frei
von Chromium:
SOURCE_SHA="$(git rev-parse HEAD)"BUILD_TIMESTAMP="$(date -u +%Y-%m-%dT%H:%M:%SZ)"REGISTRY="registry.example.com/fakeco" build_gateway_image() { gateway="$1" selected_plugin="$2" docker buildx build \ --platform linux/amd64,linux/arm64 \ --build-arg "GIT_COMMIT=${SOURCE_SHA}" \ --build-arg "OPENCLAW_BUILD_TIMESTAMP=${BUILD_TIMESTAMP}" \ --build-arg "OPENCLAW_EXTENSIONS=${selected_plugin}" \ --build-arg OPENCLAW_INSTALL_BROWSER= \ --provenance=mode=max \ --sbom=true \ --tag "${REGISTRY}/openclaw-${gateway}:${SOURCE_SHA}" \ --push \ .} build_gateway_image clickclack clickclackbuild_gateway_image slack slackbuild_gateway_image teams msteamsVerwenden Sie --platform linux/arm64 --load oder --platform linux/amd64 --load für einen
einzelnen nativen lokalen Build. Multi-Plattform-Ausgaben und angehängte SBOM-/Provenienz-
Nachweise erfordern eine Registry oder eine andere Buildx-Ausgabe, die Attestierungen beibehält. Prüfen
Sie nach dem Push das Manifest und stellen Sie den unveränderlichen Digest statt des
veränderlichen Quell-SHA-Tags bereit:
docker buildx imagetools inspect \ "${REGISTRY}/openclaw-clickclack:${SOURCE_SHA}"# Bereitstellen: registry.example.com/fakeco/openclaw-clickclack@sha256:<manifest-digest>Diese Images sind für eigenständige OCI-basierte Gateways und allgemeine Docker-Benutzer bestimmt. Von Crabhelm verwaltete Gateways verwenden sie nicht: Dieser Bereitstellungspfad erstellt ein separates x86_64-Appliance-Archiv, das einen OpenClaw-npm-Tarball enthält, und fixiert die Digests von Node, Archiv und Manifest. Erstellen Sie diese Appliance unabhängig aus demselben übernommenen OpenClaw-Quellcode.
Um gebündelten Plugin-Quellcode mit einem paketierten Image zu testen, mounten Sie ein Plugin-Quellverzeichnis über dessen paketierten Quellpfad, z. B. OPENCLAW_EXTRA_MOUNTS=/path/to/fork/extensions/synology-chat:/app/extensions/synology-chat:ro. Dadurch wird das entsprechende kompilierte Bundle /app/dist/extensions/synology-chat für dieselbe Plugin-ID überschrieben.
Beobachtbarkeit
Der OpenTelemetry-Export erfolgt ausgehend vom Gateway-Container zu Ihrem OTLP-Collector; dafür muss kein Docker-Port veröffentlicht werden. So nehmen Sie den gebündelten Exporter in ein lokal erstelltes Image auf:
export OPENCLAW_EXTENSIONS="diagnostics-otel"export OTEL_EXPORTER_OTLP_ENDPOINT="http://otel-collector:4318"export OTEL_SERVICE_NAME="openclaw-gateway"./scripts/docker/setup.shOffizielle vorgefertigte Images bündeln diagnostics-otel bereits; installieren Sie clawhub:@openclaw/diagnostics-otel nur selbst, wenn Sie es entfernt haben. Um den Export zu aktivieren, erlauben und aktivieren Sie das Plugin diagnostics-otel in der Konfiguration und setzen Sie anschließend diagnostics.otel.enabled=true (das vollständige Beispiel finden Sie unter OpenTelemetry-Export). Authentifizierungs-Header des Collectors werden über diagnostics.otel.headers und nicht über Docker-Umgebungsvariablen übergeben.
Prometheus-Metriken verwenden den bereits veröffentlichten Gateway-Port. Installieren Sie clawhub:@openclaw/diagnostics-prometheus, aktivieren Sie das Plugin diagnostics-prometheus und führen Sie dann das Scraping aus:
http://<gateway-host>:18789/api/diagnostics/prometheusDie Route ist durch die Gateway-Authentifizierung geschützt; stellen Sie keinen separaten öffentlichen /metrics-Port oder einen nicht authentifizierten Reverse-Proxy-Pfad bereit. Siehe Prometheus-Metriken.
Integritätsprüfungen
Container-Prüfendpunkte (keine Authentifizierung erforderlich):
curl -fsS http://127.0.0.1:18789/healthz # Betriebsbereitschaftcurl -fsS http://127.0.0.1:18789/readyz # DienstbereitschaftDer integrierte HEALTHCHECK des Images fragt /healthz ab; wiederholte Fehler markieren den Container als unhealthy, sodass Orchestratoren ihn neu starten oder ersetzen können.
Authentifizierte detaillierte Integritätsaufnahme:
docker compose exec openclaw-gateway node dist/index.js health --token "$OPENCLAW_GATEWAY_TOKEN"LAN gegenüber Loopback
scripts/docker/setup.sh verwendet standardmäßig OPENCLAW_GATEWAY_BIND=lan, sodass http://127.0.0.1:18789 auf dem Host mit Docker-Portveröffentlichung funktioniert.
lan(Standard): Host-Browser und Host-CLI können den veröffentlichten Gateway-Port erreichen.loopback: Nur Prozesse innerhalb des Netzwerk-Namespace des Containers können das Gateway direkt erreichen.
Lokale Provider auf dem Host
Innerhalb des Containers bezeichnet 127.0.0.1 den Container selbst und nicht den Host. Verwenden Sie host.docker.internal für Provider, die auf dem Host ausgeführt werden:
| Provider | Standard-URL auf dem Host | Docker-Setup-URL |
|---|---|---|
| LM Studio | http://127.0.0.1:1234 |
http://host.docker.internal:1234 |
| Ollama | http://127.0.0.1:11434 |
http://host.docker.internal:11434 |
Das gebündelte Setup verwendet diese URLs als Onboarding-Standardwerte für LM Studio/Ollama, und docker-compose.yml ordnet host.docker.internal unter Linux Docker Engine dem Host-Gateway zu (Docker Desktop stellt denselben Alias unter macOS/Windows bereit). Host-Dienste müssen an einer Adresse lauschen, die Docker erreichen kann:
lms server start --port 1234 --bind 0.0.0.0OLLAMA_HOST=0.0.0.0:11434 ollama serveVerwenden Sie Ihre eigene Compose-Datei oder docker run? Fügen Sie dieselbe Zuordnung selbst hinzu, z. B. --add-host=host.docker.internal:host-gateway.
Claude-CLI-Backend in Docker
Das offizielle Image installiert Claude Code nicht vor. Installieren Sie es und melden Sie sich als Benutzer node im Container an. Persistieren Sie anschließend dieses Container-Home-Verzeichnis, damit Image-Upgrades weder die Binärdatei noch den Authentifizierungsstatus löschen.
Aktivieren Sie für eine neue Installation 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.shStoppen Sie bei einer bestehenden Installation zuerst den Stack und laden Sie die aktuellen Werte aus .env neu — das Setup-Skript schreibt .env immer anhand der aktuellen Shell und der Standardwerte neu; es liest die Datei nicht selbstständig:
set -a. ./.envset +aexport OPENCLAW_HOME_VOLUME="${OPENCLAW_HOME_VOLUME:-openclaw_home}"./scripts/docker/setup.shFalls .env Werte enthält, die Ihre Shell nicht einlesen kann, exportieren Sie zunächst manuell erneut, worauf Sie angewiesen sind (OPENCLAW_IMAGE, Ports, Bindungsmodus, benutzerdefinierte Pfade, OPENCLAW_EXTRA_MOUNTS, Sandbox, Überspringen des Onboardings). Das generierte Overlay mountet das Home-Volume sowohl für openclaw-gateway als auch für openclaw-cli; führen Sie die verbleibenden Befehle mit diesem Overlay aus (und zuerst mit docker-compose.override.yml, falls Sie eine solche Datei verwenden):
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'Das native Installationsprogramm schreibt claude nach /home/node/.local/bin/claude. Verweisen Sie OpenClaw auf diesen Pfad:
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/claudeMelden Sie sich an und überprüfen Sie die Installation aus demselben persistenten Home-Verzeichnis:
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 anthropicVerwenden Sie anschließend das gebündelte Backend claude-cli:
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 "Hallo von der Docker-Claude-CLI"OPENCLAW_HOME_VOLUME persistiert die native Installation unter /home/node/.local/bin und /home/node/.local/share/claude sowie die Einstellungen/Authentifizierung von Claude Code unter /home/node/.claude und /home/node/.claude.json. Nur /home/node/.openclaw zu persistieren reicht nicht aus; wenn Sie statt eines Home-Volumes OPENCLAW_EXTRA_MOUNTS verwenden, mounten Sie alle diese Claude-Pfade in beide Dienste.
Bonjour / mDNS
Docker-Bridge-Netzwerke leiten Bonjour-/mDNS-Multicast (224.0.0.251:5353) in der Regel nicht zuverlässig weiter. Wenn OPENCLAW_DISABLE_BONJOUR nicht gesetzt ist, deaktiviert das gebündelte Bonjour-Plugin die LAN-Ankündigung automatisch, sobald es erkennt, dass es in einem Container ausgeführt wird. Dadurch gerät es nicht in eine Absturzschleife, während es wiederholt versucht, Multicast-Pakete zu senden, die von der Bridge verworfen werden. Setzen Sie OPENCLAW_DISABLE_BONJOUR=1, um die Funktion unabhängig von der Erkennung zu deaktivieren, oder 0, um sie zu erzwingen (nur bei Host-Netzwerken, macvlan oder einem anderen Netzwerk, in dem mDNS-Multicast nachweislich funktioniert).
Verwenden Sie andernfalls für Docker-Hosts die veröffentlichte Gateway-URL, Tailscale oder Wide-Area-DNS-SD. Hinweise zu Fallstricken und zur 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 das Ersetzen von Containern überdauern. Wenn eine Variable nicht gesetzt ist, greift docker-compose.yml auf einen Pfad unter ${HOME} zurück oder auf /tmp, falls HOME selbst fehlt. Dadurch erzeugt docker compose up in minimalen Umgebungen niemals eine Volume-Spezifikation mit leerer Quelle.
Dieses gemountete Konfigurationsverzeichnis enthält:
openclaw.jsonfür die Verhaltenskonfigurationagents/<agentId>/agent/auth-profiles.jsonfür gespeicherte OAuth-/API-Schlüssel-Authentifizierung von Providern.envfür umgebungsvariablenbasierte Runtime-Geheimnisse wieOPENCLAW_GATEWAY_TOKEN
Das Verzeichnis für Authentifizierungsprofil-Geheimnisse speichert den lokalen Verschlüsselungsschlüssel für Token-Material OAuth-basierter Authentifizierungsprofile. Bewahren Sie es zusammen mit dem Zustand Ihres Docker-Hosts, aber getrennt von OPENCLAW_CONFIG_DIR auf.
Installierte herunterladbare Plugins speichern den Paketzustand unter dem gemounteten OpenClaw-Home-Verzeichnis, sodass Installationsdatensätze und Paket-Roots das Ersetzen von Containern überdauern; beim Start des Gateways werden die Abhängigkeitsbäume gebündelter Plugins nicht neu erzeugt.
Vollständige Details zur VM-Persistenz finden Sie unter Docker-VM-Runtime – Was wo persistiert wird.
Schwerpunkte des Speicherplatzwachstums: media/, agentenspezifische SQLite-Datenbanken, ältere JSONL-Transkripte von Sitzungen, die gemeinsam genutzte SQLite-Zustandsdatenbank, Paket-Roots installierter Plugins und rotierende Dateiprotokolle unter /tmp/openclaw/.
Shell-Hilfsfunktionen (optional)
Installieren Sie für kürzere alltägliche Befehle 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 ~/.zshrcWenn Sie die Installation über den älteren Pfad scripts/shell-helpers/clawdock-helpers.sh vorgenommen haben, führen Sie den obigen Befehl erneut aus, damit Ihr lokales Hilfsskript dem aktuellen Speicherort folgt. Verwenden Sie anschließend clawdock-start, clawdock-stop, clawdock-dashboard usw. (führen Sie clawdock-help aus, um die vollständige Liste anzuzeigen).
Agent-Sandbox für Docker-Gateway aktivieren
export OPENCLAW_SANDBOX=1./scripts/docker/setup.shBenutzerdefinierter Socket-Pfad (z. B. für Docker ohne Root-Rechte):
export OPENCLAW_SANDBOX=1export OPENCLAW_DOCKER_SOCKET=/run/user/1000/docker.sock./scripts/docker/setup.shDas Skript bindet docker.sock erst ein, nachdem die Sandbox-Voraussetzungen erfüllt sind. Wenn die Sandbox-Einrichtung nicht abgeschlossen werden kann, setzt es agents.defaults.sandbox.mode auf off zurück. Der Codex-Codemodus ist für Durchläufe deaktiviert, in denen die OpenClaw-Sandbox aktiv ist (siehe Sandboxing § Docker-Backend); binden Sie niemals den Docker-Socket des Hosts in Agent-Sandbox-Container ein.
Automatisierung / CI (nicht interaktiv)
Deaktivieren Sie die Compose-Pseudo-TTY-Zuweisung mit -T:
docker compose run -T --rm openclaw-cli gateway probedocker compose run -T --rm openclaw-cli devices list --jsonSicherheitshinweis zum gemeinsam genutzten Netzwerk
openclaw-cli verwendet network_mode: "service:openclaw-gateway", damit CLI-Befehle das Gateway über 127.0.0.1 erreichen können. Behandeln Sie dies als gemeinsame Vertrauensgrenze. Die Compose-Konfiguration entfernt NET_RAW/NET_ADMIN und aktiviert no-new-privileges sowohl für openclaw-gateway als auch für openclaw-cli.
Docker-Desktop-DNS-Fehler in openclaw-cli
Bei einigen Docker-Desktop-Konfigurationen schlagen DNS-Abfragen aus dem openclaw-cli-Sidecar im gemeinsam genutzten Netzwerk fehl, nachdem NET_RAW entfernt wurde. Dies äußert sich bei npm-basierten Befehlen wie openclaw plugins install als EAI_AGAIN. Verwenden Sie für den normalen Betrieb weiterhin die standardmäßige gehärtete Compose-Datei. Die folgende Überschreibung stellt die Standard-Capabilities nur für den Container openclaw-cli wieder her — verwenden Sie sie für den einmaligen Befehl, der Zugriff auf die Registry benötigt, nicht als Standardaufruf:
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>Wenn Sie bereits einen dauerhaft laufenden openclaw-cli-Container erstellt haben, erstellen Sie ihn mit derselben Überschreibung neu — docker compose exec/docker exec kann die Linux-Capabilities eines bereits erstellten Containers nicht ändern.
Berechtigungen und EACCES
Das Image wird als node (UID 1000) ausgeführt. Wenn Berechtigungsfehler für /home/node/.openclaw auftreten, stellen Sie sicher, dass Ihre Bind-Mounts auf dem Host der UID 1000 gehören:
sudo chown -R 1000:1000 /path/to/openclaw-config /path/to/openclaw-workspaceDieselbe Abweichung kann sich als blocked plugin candidate: suspicious ownership (... uid=1000, expected uid=0 or root) gefolgt von plugin present but blocked zeigen — die Prozess-UID und der Eigentümer des eingebundenen Plugin-Verzeichnisses stimmen nicht überein. Führen Sie den Prozess vorzugsweise mit der standardmäßigen UID 1000 aus und korrigieren Sie die Eigentümerschaft des Bind-Mounts. Ändern Sie die Eigentümerschaft von /path/to/openclaw-config/npm nur dann auf root:root, wenn Sie OpenClaw absichtlich dauerhaft als Root ausführen.
Schnellere Neuerstellungen
Ordnen Sie Ihr Dockerfile so an, dass Abhängigkeitsebenen zwischengespeichert werden und pnpm install nur erneut ausgeführt wird, wenn sich Lockfiles ändern:
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"]Container-Optionen für fortgeschrittene Benutzer
Das Standard-Image priorisiert Sicherheit und wird als node ohne Root-Rechte ausgeführt. Für einen umfangreicher ausgestatteten Container:
/home/nodepersistent speichern:export OPENCLAW_HOME_VOLUME="openclaw_home"- Systemabhängigkeiten in das Image integrieren:
export OPENCLAW_IMAGE_APT_PACKAGES="git curl jq" - Python-Abhängigkeiten in das Image integrieren:
export OPENCLAW_IMAGE_PIP_PACKAGES="requests==2.32.5 humanize==4.14.0" - Playwright Chromium in das Image integrieren:
export OPENCLAW_INSTALL_BROWSER=1, oder verwenden Sie das offizielle Image-Tag-browser - Alternativ Playwright-Browser in einem persistenten Volume installieren:
bash docker compose run --rm openclaw-cli \ node /app/node_modules/playwright-core/cli.js install chromium - Browser-Downloads persistent speichern: Verwenden Sie
OPENCLAW_HOME_VOLUMEoderOPENCLAW_EXTRA_MOUNTS. OpenClaw erkennt unter Linux automatisch das von Playwright verwaltete Chromium des Images.
OpenAI Codex OAuth (Docker ohne grafische Oberfläche)
Wenn Sie im Assistenten OpenAI Codex OAuth auswählen, wird eine Browser-URL geöffnet. Kopieren Sie bei Docker- oder Headless-Konfigurationen die vollständige Weiterleitungs-URL, auf der Sie landen, und fügen Sie sie wieder in den Assistenten ein, um die Authentifizierung abzuschließen.
Metadaten des Basis-Images
Das Laufzeit-Image verwendet node:24-bookworm-slim und führt tini als PID 1 aus, damit Zombie-Prozesse bereinigt und Signale in dauerhaft laufenden Containern korrekt verarbeitet werden. Es veröffentlicht OCI-Basis-Image-Annotationen einschließlich org.opencontainers.image.base.name und org.opencontainers.image.source. Dependabot aktualisiert den angehefteten Digest des Node-Basis-Images; Release-Builds führen keine separate Distributionsaktualisierungsebene aus. Siehe OCI-Image-Annotationen.
Ausführung auf einem VPS?
Informationen zu Bereitstellungsschritten für gemeinsam genutzte VMs einschließlich der Integration von Binärdateien, Persistenz und Aktualisierungen finden Sie unter Hetzner (Docker-VPS) und Docker-VM-Laufzeit.
Agent-Sandbox
Wenn agents.defaults.sandbox mit dem Docker-Backend aktiviert ist, führt das Gateway die Agent-Werkzeuge (Shell, Lesen/Schreiben von Dateien usw.) innerhalb isolierter Docker-Container aus, während das Gateway selbst auf dem Host verbleibt — eine feste Grenze um nicht vertrauenswürdige oder mandantenfähige Agent-Sitzungen, ohne das gesamte Gateway in einen Container zu verlagern.
Der Sandbox-Geltungsbereich kann pro Agent (Standard), pro Sitzung oder gemeinsam festgelegt werden; jeder Geltungsbereich erhält einen eigenen Arbeitsbereich, der unter /workspace eingebunden wird. Sie können außerdem Richtlinien zum Zulassen oder Verweigern von Werkzeugen, Netzwerkisolierung, Ressourcenbeschränkungen und Browser-Container konfigurieren.
Vollständige Informationen zu Konfiguration, Images, Sicherheitshinweisen und Multi-Agent-Profilen:
- Sandboxing -- vollständige Sandbox-Referenz
- OpenShell -- interaktiver Shell-Zugriff auf Sandbox-Container
- Multi-Agent-Sandbox und Werkzeuge -- Überschreibungen pro Agent
Schnellaktivierung
{ agents: { defaults: { sandbox: { mode: "non-main", // off | non-main | all scope: "agent", // session | agent | shared }, }, },}Erstellen Sie das standardmäßige Sandbox-Image (aus einem Quellcode-Checkout):
scripts/sandbox-setup.shInformationen zu npm-Installationen ohne Quellcode-Checkout finden Sie unter Sandboxing § Images und Einrichtung. Dort stehen direkte docker build-Befehle zur Verfügung.
Fehlerbehebung
Image fehlt oder Sandbox-Container startet nicht
Erstellen Sie das Sandbox-Image mit scripts/sandbox-setup.sh (Quellcode-Checkout) oder mit dem direkten docker build-Befehl aus Sandboxing § Images und Einrichtung (npm-Installation), oder setzen Sie agents.defaults.sandbox.docker.image auf Ihr benutzerdefiniertes Image. Container werden bei Bedarf automatisch pro Sitzung erstellt.
Berechtigungsfehler in der Sandbox
Setzen Sie docker.user auf eine UID:GID, die mit der Eigentümerschaft Ihres eingebundenen Arbeitsbereichs übereinstimmt, oder ändern Sie die Eigentümerschaft des Arbeitsbereichsordners.
Benutzerdefinierte Werkzeuge werden in der Sandbox nicht gefunden
OpenClaw führt Befehle mit sh -lc (Anmelde-Shell) aus, wodurch /etc/profile geladen und PATH möglicherweise zurückgesetzt wird. Setzen Sie docker.env.PATH, um Ihre benutzerdefinierten Werkzeugpfade voranzustellen, oder fügen Sie in Ihrem Dockerfile ein Skript unter /etc/profile.d/ hinzu.
Während des Image-Builds wegen OOM beendet (Exit 137)
Die VM benötigt mindestens 2 GB RAM. Verwenden Sie eine größere Maschinenklasse und versuchen Sie es erneut.
Nicht autorisiert oder Kopplung in der Control UI erforderlich
Rufen Sie einen neuen Dashboard-Link ab und genehmigen Sie das Browsergerät:
docker compose run --rm openclaw-cli dashboard --no-opendocker compose run --rm openclaw-cli devices listdocker compose run --rm openclaw-cli devices approve <requestId>Gateway-Ziel zeigt ws://172.x.x.x oder Kopplungsfehler über die Docker-CLI
Setzen Sie Gateway-Modus und Bindung zurück:
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:18789Verwandte Themen
- Installationsübersicht — alle Installationsmethoden
- Podman — Podman-Alternative zu Docker
- ClawDock — Community-Einrichtung mit Docker Compose
- Aktualisierung — OpenClaw auf dem neuesten Stand halten
- Konfiguration — Gateway-Konfiguration nach der Installation