Containers
Docker
Docker ist optional. Verwenden Sie es für eine isolierte, temporäre Gateway-Umgebung oder einen 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? Unter Mandantenfähiges Hosting finden Sie das Modell mit einer Zelle pro Mandant.
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 wegen Speichermangels mit Exit-Code 137 beendet werden) - Ausreichend Speicherplatz für Images und Protokolle
- Prüfen Sie auf einem VPS/öffentlichen Host die Sicherheitshärtung bei Netzwerkexposition, 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, fest angeheftete Bereitstellungen und Herkunftsprüfungen. Dasselbe Release veröffentlicht unter openclaw/openclaw einen Spiegel auf Docker Hub:
export OPENCLAW_IMAGE="openclaw/openclaw:latest"./scripts/docker/setup.shVerwenden Sie ghcr.io/openclaw/openclaw oder openclaw/openclaw und vermeiden Sie inoffizielle Spiegel, da diese weder den Release-Zeitplan noch die Aufbewahrungsrichtlinie von OpenClaw übernehmen. Versionsspezifische Tags umfassen Releases wie 2026.2.26 und Vorabversionen wie 2026.2.26-beta.1. Stabile Releases aktualisieren latest und main; nachlaufende monatliche Gateway-Releases aktualisieren nur extended-stable. Zu den Varianten gehören slim, main-slim, extended-stable-slim, latest-browser, main-browser und extended-stable-browser. Die Standard-Images enthalten die Plugins codex und diagnostics-otel. Eine Variante -browser wird außerdem mit vorinstalliertem Chromium ausgeliefert. Dies ist für das Tool Browser in der Sandbox nützlich, da bei der ersten Ausführung 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-Pulls und -Builds und führt anschließend den normalen Ablauf aus: Synchronisierung von .env, Berechtigungskorrekturen, Onboarding, Synchronisierung der Gateway-Konfiguration und Start über Compose.
Bei OPENCLAW_SANDBOX=1 prüft die Offline-Einrichtung außerdem die konfigurierten standardmäßigen und agentenspezifischen 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, aber fehlerhaften Zustand zu melden.
Onboarding abschließen
Das Einrichtungsskript führt das Onboarding automatisch aus:
- fordert zur Eingabe der Provider-API-Schlüssel auf
- generiert ein Gateway-Token und schreibt es nach
.env - erstellt das Verzeichnis für den geheimen Schlüssel des Authentifizierungsprofils
- startet das Gateway über Docker Compose
Das Onboarding vor dem Start und das Schreiben der Konfiguration erfolgen direkt über openclaw-gateway (mit --no-deps --entrypoint node), da openclaw-cli den Netzwerk-Namespace des Gateways gemeinsam nutzt und erst funktioniert, sobald der Gateway-Container vorhanden ist.
Control UI öffnen
Öffnen Sie http://127.0.0.1:18789/ und fügen Sie das nach .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 die Plugin-Konvergenz aus. Routinemäßige Image-Upgrades 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 an, dass der Gateway-Container wiederholt neu gestartet wird. Behalten Sie das eingebundene Zustands-Volume bei und führen Sie dasselbe Image anschließend einmal mit openclaw doctor --fix als Container-Befehl 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 denselben Befehl in Kubernetes 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 ihre 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, ausschließlich für die Laufzeit vorgesehenen Image-Builds überspringen (Standard: 1) |
OPENCLAW_INSTALL_BROWSER |
Chromium und Xvfb zum Build-Zeitpunkt in das Image integrieren |
OPENCLAW_EXTRA_MOUNTS |
Zusätzliche Host-Bind-Mounts (durch Kommas getrennte 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 zum Docker-Socket überschreiben |
OPENCLAW_DISABLE_BONJOUR |
Bonjour-/mDNS-Ankündigung erzwingen: ein (0) oder aus (1); siehe Bonjour / mDNS |
OPENCLAW_DISABLE_BUNDLED_SOURCE_OVERLAYS |
Bind-Mount-Overlays für Quellen gebündelter Plugins 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 Installationsprogramme für reine brew-Abhängigkeiten von Skills aus. 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 python3 -m pip install --break-system-packages während des Builds aus; legen Sie daher Versionen fest und verwenden Sie nur vertrauenswürdige Paketindizes).
Wenn Docker ResourceExhausted oder cannot allocate memory meldet oder während tsdown abbricht, erhöhen Sie das Speicherlimit des Docker-Builders oder wiederholen Sie den Vorgang mit kleineren, explizit angegebenen Heaps:
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 Quell-Checkout aus;
vorhandene 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 vorgesehene Paketierung ändert den npm- oder ClawHub-
Artefaktvertrag des Plugins nicht. Unbekannte, ungültige oder mehrdeutige IDs lassen den Image-Build fehlschlagen.
Bekannte reine Abhängigkeits-/Quell-IDs behalten ihr bestehendes Quell- und Abhängigkeits-
Staging, ohne einen kompilierten Root-Distributionseintrag zu erhalten. Ein ausgewähltes Plugin mit
vereinheitlichten Build-Einträgen muss erfolgreich kompiliert werden; nicht ausgewählte externe Plugin-
Quellen und Runtime-Ausgaben 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 Root-Runtime von OpenClaw, daher wählt das ClickClack-Image nur
clickclack aus. Das explizit leere Browserargument 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 bewahrt. Prüfen
Sie nach dem Push das Manifest und stellen Sie den unveränderlichen Digest statt des
veränderlichen Source-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 vorgesehen. 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 derselben übernommenen OpenClaw-Quelle.
Um gebündelte Plugin-Quellen 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 passende kompilierte /app/dist/extensions/synology-chat-Bundle 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 enthalten 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 legen Sie anschließend diagnostics.otel.enabled=true fest (das vollständige Beispiel finden Sie unter OpenTelemetry-Export). Authentifizierungsheader 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 durch:
http://<gateway-host>:18789/api/diagnostics/prometheusDie Route ist durch die Gateway-Authentifizierung geschützt; stellen Sie keinen separaten öffentlichen Port /metrics und keinen nicht authentifizierten Reverse-Proxy-Pfad bereit. Siehe Prometheus-Metriken.
Zustandsprüfungen
Container-Prüfendpunkte (keine Authentifizierung erforderlich):
curl -fsS http://127.0.0.1:18789/healthz # Verfügbarkeitcurl -fsS http://127.0.0.1:18789/readyz # BereitschaftDas im Image integrierte HEALTHCHECK pingt /healthz; wiederholte Fehler markieren den Container als unhealthy, sodass Orchestratoren ihn neu starten oder ersetzen können.
Authentifizierte detaillierte Zustandsmomentaufnahme:
docker compose exec openclaw-gateway node dist/index.js health --token "$OPENCLAW_GATEWAY_TOKEN"LAN im Vergleich zu Loopback
scripts/docker/setup.sh verwendet standardmäßig OPENCLAW_GATEWAY_BIND=lan, sodass http://127.0.0.1:18789 auf dem Host mit der 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-Namensraums des Containers können das Gateway direkt erreichen.
Lokale Provider auf dem Host
Innerhalb des Containers ist 127.0.0.1 der Container selbst, nicht der Host. Verwenden Sie host.docker.internal für Provider, die auf dem Host ausgeführt werden:
| Provider | Standard-URL des Hosts | Docker-Einrichtungs-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 |
Die gebündelte Einrichtung 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 innerhalb des Container-Benutzers node an. Persistieren Sie anschließend das Home-Verzeichnis des Containers, damit Image-Upgrades weder die Binärdatei noch den Authentifizierungsstatus löschen.
Aktivieren Sie bei einer Neuinstallation ein persistentes /home/node-Volume, bevor Sie die Einrichtung ausführen:
export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"export OPENCLAW_HOME_VOLUME="openclaw_home"./scripts/docker/setup.shStoppen Sie bei einer vorhandenen Installation zunächst den Stack und laden Sie die aktuellen Werte aus .env neu. Das Einrichtungsskript schreibt .env stets 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, Bind-Modus, benutzerdefinierte Pfade, OPENCLAW_EXTRA_MOUNTS, Sandbox, Onboarding überspringen). Das erzeugte 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 eines 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. Das
OpenClaw-Image enthält /home/node/.local/bin in PATH, sodass das gebündelte
Anthropic-Plugin es ohne Überschreibung der Adapterkonfiguration auflöst.
Melden 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 OPENCLAW_EXTRA_MOUNTS statt eines Home-Volumes verwenden, mounten Sie alle diese Claude-Pfade in beide Dienste.
Bonjour / mDNS
Docker-Bridge-Netzwerke leiten Bonjour-/mDNS-Multicast (224.0.0.251:5353) üblicherweise nicht zuverlässig weiter. Wenn OPENCLAW_DISABLE_BONJOUR nicht festgelegt 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-Daten zu senden, die von der Bridge verworfen werden. Legen Sie OPENCLAW_DISABLE_BONJOUR=1 fest, um es unabhängig von der Erkennung zu deaktivieren, oder 0, um es zu aktivieren (nur bei Host-Netzwerken, macvlan oder einem anderen Netzwerk, in dem mDNS-Multicast nachweislich funktioniert).
Verwenden Sie andernfalls die veröffentlichte Gateway-URL, Tailscale oder Wide-Area-DNS-SD für Docker-Hosts. Hinweise zu Fallstricken und zur Fehlerbehebung finden Sie unter Bonjour-Erkennung.
Speicherung 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 einen Containeraustausch überdauern. Wenn eine Variable nicht festgelegt ist, greift docker-compose.yml ersatzweise auf einen Pfad unter ${HOME} zurück oder auf /tmp, falls HOME selbst fehlt, sodass docker compose up in einfachen Umgebungen niemals eine Volume-Spezifikation mit leerer Quelle erzeugt.
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 umgebungsbasierte Runtime-Geheimnisse wieOPENCLAW_GATEWAY_TOKEN
Das Geheimnisverzeichnis des Authentifizierungsprofils speichert den lokalen Verschlüsselungsschlüssel für das Tokenmaterial OAuth-basierter Authentifizierungsprofile. Bewahren Sie es zusammen mit dem Zustand Ihres Docker-Hosts auf, jedoch getrennt von OPENCLAW_CONFIG_DIR.
Installierte herunterladbare Plugins speichern ihren Paketzustand unter dem gemounteten OpenClaw-Home-Verzeichnis, sodass Installationsdatensätze und Paket-Roots einen Containeraustausch überdauern; beim Start des Gateways werden die Abhängigkeitsbäume gebündelter Plugins nicht neu erzeugt.
Ausführliche Informationen zur vollständigen VM-Persistenz finden Sie unter Docker-VM-Runtime – Wo welche Daten persistiert werden.
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 Ihre lokale Hilfsfunktion 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. rootless Docker):
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 den Docker-Socket des Hosts niemals in Agent-Sandbox-Container ein.
Automatisierung / CI (nicht interaktiv)
Deaktivieren Sie die Pseudo-TTY-Zuweisung von Compose 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 Sidecar openclaw-cli im gemeinsam genutzten Netzwerk fehl, nachdem NET_RAW entfernt wurde. Dies zeigt sich bei npm-gestützten 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 langlebigen Container openclaw-cli erstellt haben, erstellen Sie ihn mit derselben Überschreibung neu — docker compose exec/docker exec können die Linux-Capabilities eines bereits erstellten Containers nicht ändern.
Berechtigungen und EACCES
Das Image wird als node (UID 1000) ausgeführt. Wenn bei /home/node/.openclaw Berechtigungsfehler 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 OpenClaw vorzugsweise mit der standardmäßigen UID 1000 aus und korrigieren Sie die Eigentümerschaft des Bind-Mounts. Ändern Sie den Eigentümer von /path/to/openclaw-config/npm nur dann zu root:root, wenn Sie OpenClaw absichtlich dauerhaft als root ausführen.
Schnellere Neubuilds
Ordnen Sie Ihr Dockerfile so an, dass Abhängigkeits-Layer 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 Nicht-root-Benutzer node ausgeführt. Für einen umfangreicher ausgestatteten Container:
/home/nodedauerhaft 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 - Oder 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 dauerhaft 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 Benutzeroberfläche)
Wenn Sie im Assistenten OpenAI Codex OAuth auswählen, wird eine Browser-URL geöffnet. Kopieren Sie in Docker- oder Headless-Umgebungen 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 langlebigen 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 keinen separaten Distributions-Upgrade-Layer aus. Siehe OCI-Image-Annotationen.
Betrieb auf einem VPS?
Unter Hetzner (Docker-VPS) und Docker-VM-Laufzeit finden Sie Schritte für die Bereitstellung auf gemeinsam genutzten VMs, einschließlich der Integration von Binärdateien, Persistenz und Aktualisierungen.
Agent-Sandbox
Wenn agents.defaults.sandbox mit dem Docker-Backend aktiviert ist, führt das Gateway Agent-Tools (Shell, Lesen/Schreiben von Dateien usw.) in isolierten Docker-Containern 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 zu containerisieren.
Der Sandbox-Geltungsbereich kann pro Agent (Standard), pro Sitzung oder gemeinsam festgelegt werden; jeder Geltungsbereich erhält einen eigenen, unter /workspace eingebundenen Arbeitsbereich. Sie können außerdem Zulassungs-/Ablehnungsrichtlinien für Tools, Netzwerkisolierung, Ressourcenlimits 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 Tools -- Ü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 mit Inline-Befehlen für docker build.
Fehlerbehebung
Image fehlt oder Sandbox-Container startet nicht
Erstellen Sie das Sandbox-Image mit scripts/sandbox-setup.sh (Quellcode-Checkout) oder dem Inline-Befehl docker build 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 der Eigentümerschaft Ihres eingebundenen Arbeitsbereichs entspricht, oder ändern Sie den Eigentümer des Arbeitsbereichsordners.
Benutzerdefinierte Tools werden in der Sandbox nicht gefunden
OpenClaw führt Befehle mit sh -lc (Anmelde-Shell) aus, wodurch /etc/profile eingelesen und PATH möglicherweise zurückgesetzt wird. Setzen Sie docker.env.PATH, um Ihre benutzerdefinierten Tool-Pfade voranzustellen, oder fügen Sie in Ihrem Dockerfile unter /etc/profile.d/ ein Skript hinzu.
Während des Image-Builds wegen Speichermangels 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 Bind-Adresse 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 — Docker-Compose-Einrichtung der Community
- Aktualisierung — OpenClaw auf dem neuesten Stand halten
- Konfiguration — Gateway-Konfiguration nach der Installation