2026 OpenClaw auf Mac-VPS mit Docker: Gateway-Token, CLI-Containernetzwerk und Pairing-Deadlock-Runbook

1. Schmerzpunkte: doppelte Tokens, Loopback, Pairing, Bind, UID

Offizielle Docker-Flows setzen voraus, dass ein Mensch im selben Netzwerk-Namespace wie die Skripte durch das Onboarding klickt. Auf unbeaufsichtigten Mac-VPS-Hosts buendeln sich typische Fehler in fuenf Eimer:

1. Stille Umgebungsvariable: Ist OPENCLAW_GATEWAY_TOKEN im Container gesetzt, kann er gateway.auth.token in openclaw.json uebersteuern; die UI zeigt dann ein Token, das das Gateway nie prueft.
2. CLI-Loopback bei getrennten Stacks: Die CLI spricht standardmaessig ws://127.0.0.1:18789 an – das ist der Loopback des CLI-Containers, nicht des Gateways; ECONNREFUSED oder harte 1006-Schliesse wirken wie Netzflaps.
3. Pairing-Deadlocks: Mit gateway.bind=lan warten Dashboard und CLI gegenseitig auf Freigabe; ohne dokumentierte Reihenfolge drehen Sie auf 1008.
4. Bind-Semantik vs. Bridge: loopback kollidiert mit Container-zu-Container-Zielen; nach Wechsel auf lan ohne CLI-URL-Update bleibt oft nur ein erfolgreicher Listen-Log, waehrend der WebSocket nicht fertig wird.
5. Volume-UID-Drift: Images laufen oft als UID 1000; vom Host als root angelegte Pfade brechen Persistenz – Token-Dateien scheinen zu speichern und sind nach Restart weg.

Auf einem kopflosen Mac-VPS tarnt kein lokaler Browser Fehlkonfiguration: jeder WebSocket-Retry steht in den Logs, launchd startet Container auch mitten im Pairing neu. Lesen Sie docker compose logs -f openclaw-gateway und CLI-Logs als eine gemeinsame Zeitleiste. Bei Digest-Pinning notieren Sie Digest und Token-Fingerprint (erste acht Zeichen) im Change-Ticket, damit Rollbacks kein altes Auth-Modell heimlich zurueckbringen. Wenn das Dashboard ueber Loopback hinaus erreichbar ist, lesen Sie zusaetzlich den Hardening-Text zur Gateway-Exponierung, damit Token-Drift nicht nur als Docker-Netzbug, sondern auch als Blast-Radius-Thema behandelt wird.

2. Triage-Tabelle: Symptom, Ursache, erster Befehl

Tabelle in die Incident-Vorlage kleben; fuer die Policy-Phase den Hardening-Artikel zur Exponierung parallel lesen.

„Beide Quellen grep“ woertlich nehmen: Repo nach OPENCLAW_GATEWAY_TOKEN durchsuchen, openclaw.json im laufenden Container per docker compose exec openclaw-gateway cat /pfad/zur/openclaw.json pruefen (Pfad anpassen) und mit der env-Sektion in Compose vergleichen. Bei Secret-Managern den zur Laufzeit aufgeloesten Wert pruefen, nicht nur das Git-Template. Bei 1008 festhalten, ob Dashboard und CLI unterschiedliche Pending-Zustaende zeigen – das deutet oft auf falsches GATEWAY_URL oder geteilte Cookies statt echte Auth-Fehler.

3. Fuenf-Schritte-Runbook bis On-Call-Checks

1. Secret einfrieren: Erste acht Zeichen des Tokens und geplanten Image-Digest im Change-Ticket festhalten.
2. Doppelte Quellen angleichen: Vor compose up gateway.auth.token und OPENCLAW_GATEWAY_TOKEN je Containerdefinition read-only vergleichen.
3. Namespaces reparieren: Fuer die CLI network_mode: service:openclaw-gateway bevorzugen; falls Bridge noetig, GATEWAY_URL=ws://openclaw-gateway:18789 setzen und DNS aus einem Wegwerf-docker compose run-Shell testen.
4. Pairing loesen: Im Gateway-Container openclaw dashboard --no-open, URL mit Token abschliessen, dann im CLI-Container devices approve mit im Ticket dokumentierter Befehlsfolge.
5. Probes und launchd: Vom Host /healthz und /readyz mit kurzen Timeouts per curl; dieselben Checks in einer plist-SuccessfulExit-Bedingung spiegeln, damit Neustarts nicht siegen, solange der WebSocket unten ist. Ressourcengrenzen siehe Compose-7x24-Artikel auf dieser Site.

Minimales Compose-Skizze (vor Produktion mit Upstream-Templates mergen):

Wenn network_mode: service:openclaw-gateway wegen eines Sidecars nicht geht, explizite interne URL setzen und aus einem Wegwerf-Container pruefen: docker compose run --rm busybox wget -qO- http://openclaw-gateway:18789/healthz (oder curl). Erwarteten Docker-DNS-Hostnamen dokumentieren; Tippfehler in Service-Namen erklaeren viele „ging auf dem Laptop“-Faelle. Geraetzeilen erst nach Log-Export loeschen, wenn klar ist, dass nicht der falsche Workspace betroffen ist.

4. Zitierfaehige Fakten: Port, UID, Probes

• Port: Standard-Listener 18789; Health-Skripte muessen den Listener treffen, nicht nur docker ps.
• UID: Node-User typischerweise 1000; Host-Binds angleichen, sonst leise Persistenzverluste.
• Probes: /healthz als Liveness, /readyz naeher an WebSocket-Readiness; Reihenfolge und Timeouts im Runbook festhalten.
• Zeitsync: Grosse Drift zwischen Host und Container stoert Zertifikats- und Log-Korrelation; NTP auf dem VPS gesund halten.
• Upgrade-Fenster: Bei Image-Bumps zuerst die fuenf Schritte; docker ps heisst nicht automatisch authentifizierte CLI-Session.

Operationalisieren Sie die Checks in Ihrem Chat-Ops-Playbook: jede Eskalation sollte Token-Fingerprint, Compose-Dateirevision und Digest in einer Zeile tragen, damit Postmortems nicht raten muessen. Wenn Sie Blue/Green fuer das Gateway erwaegen, dokumentieren Sie explizit, welcher Stack noch alte Pairing-Eintraege traegt, sonst genehmigen Teams versehentlich Geraete gegen die falsche URL. Fuer Lasttests empfiehlt es sich, Health-Endpunkte mit denselben Timeouts zu schlagen wie in Produktion; kuenzer im Test als in Prod verschleiert Flakes. Mac-VPS-Anbieter mit fest zugewiesener Bandbreite reduzieren zusaetzlich das Risiko, dass Remote-Steuerungskanäle waehrend langer WebSocket-Sessions gedrosselt werden. Wer mehrere Umgebungen betreibt, sollte Tokens niemals per Copy-Paste zwischen Staging und Prod teilen; stattdessen getrennte .env-Dateien mit klar benannten Suffixen verwenden. Schliesslich: halten Sie ein kurzes Architekturdiagramm bereit, das Gateway-, CLI- und Sidecar-Namespaces zeigt – On-Call-Ingenieure verlieren sonst im Bridge-Layout schnell den Ueberblick.

Ergaenzen Sie zusaetzlich eine kurze Checkliste fuer Rollenwechsel: wer darf devices approve ausfuehren, wer darf Token rotieren, und wie wird das in einem verschluesselten Ticket nachvollziehbar abgelegt. Ohne diese Rollenmarkierung landen Pairing-Freigaben oft bei Personen, die keinen Zugriff auf die VPS-Konsole haben, was die MTTR verlaengert. Wenn Sie Infrastructure-as-Code fuer Compose nutzen, validieren Sie Aenderungen mit einem statischen Diff gegen die laufende docker compose config-Ausgabe, damit versteckte env-Ueberlagerungen vor dem Merge auffallen. Bei laengeren Wartungsfenstern sollten Sie Healthchecks bewusst failen lassen, um zu pruefen, ob launchd wirklich stoppt und nicht nur den Container neu startet, waehrend Clients noch alte Verbindungen halten. Speichern Sie zudem die WebSocket-Upgrade-Header aus einem erfolgreichen Handshake als Referenz, damit Regressionen schneller erkannt werden.

5. Lesereihenfolge: Compose 7x24 und native Gateway-Guides

Wenn Restarts, Speicherdeckel und Digest-Pinning noch nicht standardisiert sind, zuerst Compose 7x24 Health, Upgrade, Rollback lesen. Wenn die Diskussion wandert, ob das Gateway-Binaer oder die CLI die Wahrheit besitzt, Gateway install / bind / auth Runbook fuer Native-vs-Docker-Grenzen oeffnen. Ad-hoc-docker run auf dem Laptop verbirgt Pairing- und Token-Probleme, die auf kopflosem Mac-VPS Pager-Laerm werden. Gegenueber reinem launchd fuegt Docker eine Abstraktionsschicht hinzu; Upgrades und Drills kosten mehr Wandzeit. Wer dediziertes Apple Silicon, stabilen Egress und planbare Parallelitaet fuer langlebige Agenten braucht, bucht VPSMAC M4 Mac-Cloud-Knoten, um Binds, plist-Richtlinien und Compose in einer Betriebsgeschichte zu halten. Automation schliessen Sie mit dem 90-Sekunden-Mac-Cloud-API-Leitfaden auf dieser Site.