2026 OpenClaw: Offizielles Docker Compose auf dem Remote-Mac—Image, Volumes, Port 18789 und VNC-Validierung der Konsole

Wenn Sie OpenClaw nicht nur kurz testen, sondern auf einem gemieteten Remote-Mac oder einer dedizierten Workstation über Wochen stabil betreiben, stellt sich schnell die Frage nach Reproduzierbarkeit: Welche Node-Version lag damals auf dem Host? Welche globalen Pakete haben ein Upgrade mitgezogen? Docker Compose mit dem offiziellen Image unter ghcr.io/openclaw/openclaw reduziert diese Unsicherheit: Sie deklarieren Image-Tag oder Digest, hängen Konfiguration und Arbeitsdaten an benannte Volumes oder Bind-Mounts und dokumentieren Port 18789 für die Weboberfläche so, wie es das Projektteam vorsieht. Dieser Leitfaden richtet sich an fortgeschrittene Betreiber: Sie erhalten eine Entscheidungsmatrix gegenüber npm-Installation, eine Liste typischer Container-Fallen auf macOS-Hosts, einen Schritt-für-Schritt-Pfad inklusive Beispiel-compose.yaml und Hinweise, warum die VNC-Sitzung für Browser- und Berechtigungsflows weiterhin die zuverlässigste Oberfläche bleibt. Ergänzend verweisen wir auf bestehende Artikel zu launchd und Daemonbetrieb, SecretRef und secrets-Audit, Mehrprojekt-Isolierung sowie häufige Fehler und Troubleshooting.

1. Docker versus npm: wann sich Container lohnen

Das OpenClaw-Ökosystem bietet 2026 mehrere Installationspfade: Shell-Skripte, npm install -g und OCI-konforme Images in der GitHub Container Registry. Für einen Entwickler, der täglich Branches wechselt und Debugger an den Prozess hängt, bleibt die native Installation oft der schnellste Weg: keine zusätzliche Schicht zwischen Kernel und Node, kurze Feedbackzyklen, direkter Zugriff auf lokale Tools. Sobald jedoch mehrere Umgebungen auf demselben Benutzerkonto koexistieren oder ein Provider-Remote-Mac zwischen Kundenaufträgen geteilt wird, wird der globale Node-Zustand zur Risikoquelle: ein verfrühtes npm update kann Plugin-Schnittstellen verschieben, und Rollbacks sind mühsam nachzuvollziehen.

Docker Compose adressiert genau diese Schnittstelle. Sie beschreiben den gewünschten Zustand deklarativ: welches Image (idealerweise mit festem Tag oder Digest), welche Umgebungsvariablen aus einer nicht versionierten .env, welche Verzeichnisse als Volume überleben Container-Neustarts. In regulierten Umgebungen ist es üblich, Image-Digests festzunageln und Änderungen nur nach Review des SBOM oder der Signatur in der Registry auszurollen—ein Muster, das bei Bare-Metal-Node-Stacks deutlich schwerer zu dokumentieren ist. Ein zweiter Vorteil ist Port- und Netzwerkisolation: Zwei Compose-Projekte mit unterschiedlichen Projektnamen können parallel laufen, sofern Sie Host-Ports und Volume-Namen sauber trennen—ein Muster, das unser Mehrprojekt-Leitfaden für Verzeichnis- und API-Key-Hygiene ergänzt.

Auf macOS als Docker-Host gelten einige Besonderheiten: Dateisystem-Performance bei Bind-Mounts über virtuelle Maschinen (Docker Desktop, Colima) kann von Linux-Deployments abweichen. Legen Sie datenintensive Artefakte deshalb lieber in benannte Docker-Volumes statt in langsame Netzlaufwerke. Prüfen Sie außerdem, ob Ihr Team Rosetta- oder ARM-Tags für Images benötigt—die offizielle Registry-Dokumentation sollte hier Maßstab sein. Wenn Sie Compose nur als „Verpackung“ für denselben Prozess nutzen, lohnt sich ein kurzer Abgleich mit dem Betriebsteam: Akzeptiert Monitoring denselben Metrikpfad wie bei nativer Installation? Wo landen Logs—stdout des Containers, Dateien im Volume oder beides? Ohne diese Klärung verlagern Sie lediglich die Komplexität, statt sie zu reduzieren.

Schließlich sollten Sie Upgrade- und Rollback-Playbooks parallel zu technischen Entscheidungen pflegen: Ein docker compose pull gefolgt von einem kontrollierten Neustart ist schnell getippt; die Frage, ob Konfigurationsschemas zwischen Minor-Versionen kompatibel bleiben, beantworten Release Notes und ggf. Migrationsleitfäden—nicht der bloße Container-Neustart. Wo SecretRef und Auditprozesse ins Spiel kommen, bleibt Docker ein Transportmittel; die Governance bleibt Aufgabe Ihrer Organisation und der in SecretRef-Artikel beschriebenen Workflows.

2. Fünf Stolperstellen nach dem Umstieg auf Compose

Selbst wenn der Container startet, erleben Teams häufig eine zweite Fehlerphase, sobald echte Workloads laufen. Die folgenden Punkte sind aus Support-Gesprächen und internen Checklisten abgeleitet und spiegeln keine spezifische Build-Nummer wider—validieren Sie Flags stets mit openclaw --help und dem Upstream-Changelog.

1. UID/GID und Schreibrechte auf Volumes: Wenn der Prozess im Container als nicht-root läuft, aber Ihr Bind-Mount dem Host-Benutzer gehört, schlagen Logrotation oder Konfigurationsschreibzugriffe fehl. Lösungen: konsistente user:-Mappings in Compose, oder ein initiales chown auf dem Host—dokumentiert im Runbook.
2. Loopback versus gebundene Schnittstelle: Die Dokumentation erwähnt häufig Port 18789 für die Weboberfläche. Wenn der Dienst nur auf 127.0.0.1 innerhalb des Containers lauscht und Sie die Portweiterleitung falsch setzen, wirkt von außen alles „tot“, während curl im Container erfolgreich ist. In einer VNC-Sitzung auf dem Remote-Mac öffnen Sie http://127.0.0.1:18789 im selben Netz-Namespace wie der Desktop-Benutzer—das reduziert Tunnel-Fehler gegenüber mehrstufigem SSH-Forwarding.
3. Interaktives onboard ohne TTY: Assistenten, die Eingaben oder Browser-Callbacks erwarten, brechen in nicht-interaktiven docker compose run-Sessions ab. Führen Sie die Ersteinrichtung in einem Terminal mit zugewiesenem TTY aus oder nutzen Sie Flags für nicht-interaktive Modi, falls verfügbar.
4. Doppelte Prozessführung mit launchd: Wenn bereits ein natives openclaw gateway per LaunchAgent läuft, konkurriert ein Compose-Container um dieselben Ports und Konfigurationspfade. Stoppen Sie den nativen Dienst bewusst, bevor Sie den Container hochziehen.
5. Geheimnisse in Image-Layern oder weltlesbar: API-Schlüssel gehören nicht in Dockerfile-ENV, die Sie committen. Nutzen Sie externe Secret-Stores oder die in OpenClaw 2026.3.x propagierten Mechanismen rund um SecretRef und openclaw secrets, und halten Sie Berechtigungen auf gemieteten Hosts restriktiv.

Ergänzend tauchen auf geteilten Remote-Macs organisatorische Fallen auf: Jemand startet einen zweiten Stack „nur kurz“ mit dem Standard-Projektnamen, überschreibt Host-Ports oder bindet dasselbe Hostverzeichnis. Dokumentieren Sie Projektnamen, erwartete Ports und Verantwortliche in einem internen Register—analog zu den Bucket-Regeln im Mehrprojekt-Artikel.

3. Entscheidungsmatrix: Bare Metal, ein Compose-Stack, mehrere Projekte

Die Matrix ist bewusst grob: In der Praxis kombinieren Teams häufig Compose für den Gateway-Dienst und lokale CLI-Aufrufe in CI. Wichtig ist, dass jede Umgebung ein einheitliches Protokoll für Version, Konfigurationspfad und Secrets führt—so lassen sich Vorfälle nach einem Provider-Snapshot oder einem Major-Upgrade schneller eingrenzen. Wenn Sie mehrere Stacks fahren, sollten Monitoring-Dashboards Container-ID, Image-Tag und Projektname anzeigen, damit Alarme nicht nur „CPU hoch“ melden, sondern zuordenbar bleiben.

4. Umsetzung: Verzeichnis, Compose-Datei, onboard, Dienstbetrieb

Im Folgenden skizzieren wir einen didaktischen Minimalaufbau. Produktive Umgebungen ergänzen Healthchecks, Ressourcelimits, Log-Treiber und ggf. ein Reverse-Proxy-Terminierung für TLS. Synchronisieren Sie die Feldnamen stets mit dem aktuellen offiziellen Repository; Release Notes erwähnen regelmäßig Änderungen an Umgebungsvariablen oder Standardpfaden. Vor dem ersten up empfiehlt sich ein docker compose config, um Tippfehler in YAML und Variablensubstitution früh zu sehen—besonders wenn mehrere .env-Dateien über env_file eingebunden werden.

services:
  openclaw:
    image: ghcr.io/openclaw/openclaw:latest
    ports:
      - "18789:18789"
    volumes:
      - openclaw_config:/root/.openclaw
      - ./workspace:/workspace
    restart: unless-stopped
volumes:
  openclaw_config:

Ergänzen Sie environment:-Blöcke oder eine .env-Datei nur außerhalb der Versionskontrolle. Prüfen Sie, ob Ihr Team statt :latest einen konkreten Tag für wiederholbare Builds verlangt. Für Air-Gap- oder Compliance-Umgebungen kann das Festhalten des Image-Digests in der Compose-Datei Pflicht sein. Nach dem ersten erfolgreichen Start sollten Sie docker compose ps und docker inspect auf den Container anwenden, um tatsächliche Port-Bindings und Mount-Pfade mit Ihrer Dokumentation abzugleichen—Diskrepanzen hier sind eine häufige Ursache für Support-Tickets.

5. Referenzwerte, Backups und Checkliste

• Compose-Projektname und Host-Ports kollidieren nicht mit anderen Mandanten auf demselben Mac.
• Volume-Schreibtests bestanden; Logs rotieren nicht vollständig ins Leere.
• Web-UI und API-Gateway zeigen konsistente Gesundheitszustände nach Neustart des Hosts.
• Secrets ausschließlich über kontrollierte Kanäle—keine Klartextduplikate in Shell-History oder weltlesbaren Dateien.
• Änderungen an Compose-Dateien sind reviewpflichtig; Drifts zwischen Repo und laufendem Stack werden erkannt.

6. FAQ und Verknüpfung mit dem restlichen OpenClaw-Korpus

Frage: Soll docker compose durch launchd beim Login starten? Das ist möglich, erfordert aber klare Trennung: Entweder startet launchd docker compose up -d in einem festen Arbeitsverzeichnis, oder Sie verlassen sich auf restart: unless-stopped und den Docker-Daemon beim Boot—beides will geplant werden, siehe launchd-Checkliste. Vermeiden Sie, denselben Konfigurationsbaum gleichzeitig von einem nativen Prozess und einem Container zu schreiben.

Frage: Wie vermeiden wir, dass zwei Projekte dieselben API-Schlüssel lesen? Verzeichnis- und Umgebungs-Trennung bleiben oberste Priorität; der Container ersetzt keine Policy. Nutzen Sie die Mehrprojekt-Anleitung für Buckets und Benennung, und kombinieren Sie sie mit SecretRef, sobald Literale aus Konfigurationen verschwinden sollen.

Frage: Der Container startet, aber Model-Calls schlagen fehl—wo beginnen Sie? Arbeiten Sie die häufigsten Ursachen in der Reihenfolge Netzwerk → Authentifizierung → Konfiguration ab; unser Troubleshooting-Artikel strukturiert typische Symptome. Dokumentieren Sie für jeden Vorfall Zeitstempel, Image-Tag und relevante Logauszüge—das beschleunigt Eskalationen an die Plattform oder den Upstream.

Frage: Brauchen wir überhaupt einen Mac, wenn alles containerisiert ist? Viele Schritte sind plattformagnostisch; dennoch unterscheidet sich macOS in Berechtigungen, Keychain-Integration und Pfadkonventionen von Linux-CI. Wenn Ihr Zielsystem ein Remote-Mac ist, sollte die Validierung dort erfolgen—nicht nur im Linux-Runner. VNCMac unterstützt genau dieses Szenario mit isolierten Mietinstanzen und dokumentierten Verbindungswegen.

Fazit: Reproduzierbarkeit im Container, Sichtbarkeit über VNC

Docker Compose liefert das „was läuft hier eigentlich?“ in maschinenlesbarer Form; VNC auf dem Remote-Mac liefert das „was sieht der Mensch am Bildschirm?“ für Browser-, Dialog- und Clipboard-Szenarien. Ein dedizierter Kaufrechner ist für viele Teams ökonomisch unsinnig, wenn der Bedarf projektgebunden ist; reines SSH ohne Desktop verschleiert hingegen oft die letzte Meile. VNCMac adressiert diese Lücke mit isolierten Mac-Instanzen und klaren Verbindungsleitfäden, sodass Sie Zeit in Automatisierung und Observability investieren können statt in Ad-hoc-Hardwarebeschaffung. Wenn Sie den Stack einmal stabil haben, wiederholen Sie die Übung nach jedem größeren Upgrade: kurzer Smoke-Test in VNC, Log-Stichprobe, dann Freigabe für das Team.