2026 OpenClaw offizielles Docker: docker-setup.sh, GHCR & Control UI (18789) Runbook

ca. 13 Min. Lesezeit · MACCOME

Zielgruppe: Ingenieure, die die offizielle Docker-Doku lesen, aber zwischen lokalen Build-Timeouts, fehlgeschlagenen GHCR-Pulls, Port-18789-Konflikten und Volume-Rechten, die Skills blockieren, pendeln—ohne klaren Pfad vom Clone zur Control UI. Ergebnis: Standard auf docker-setup.sh plus optionales OPENCLAW_IMAGE; Arbeit mit Docker-Produktion, Docker-Netzwerk und Volume/Berechtigungen aufteilen. Aufbau: sechs Fallen, Matrix, 6-Schritte-Runbook, Triage-Tabelle, drei KPIs, Schluss.

Warum „laut Doku“ auf dem Docker-Pfad trotzdem scheitert

Der offizielle Ablauf setzt konsistente Docker Engine, Compose, Platte und Ausgang voraus. Gemischt mit npm-global oder einem anderen Compose-Checkout wirkt alles wie „OpenClaw kaputt“. Sechs häufige Brecher 2025–2026:

  1. Quell-Builds und GHCR-Pulls nicht getrennt: docker build auf schwachen CI-Leitungen erzwingen statt auf OPENCLAW_IMAGE zu wechseln.
  2. Alte Container an 18789: frühere Compose-Versuche laufen nicht gestoppt—das neue docker-setup.sh kann die Control UI nicht binden.
  3. UID/GID-Mismatch auf Volumes: Container-User vs. Host-~/.openclaw—Skills/State schreiben fehl, die UI wirkt „tot“.
  4. Pairing als Image-Problem verwechseln: WebSocket/Token gehören in den Pairing/Token-Artikel—nicht endloses compose pull.
  5. Firmenproxy erlaubt npm, blockiert ghcr.io: Spiegel oder Allowlist; gleiche Diagnoseklasse wie das npm-Installations-Runbook.
  6. Mehrere Checkouts teilen Env/Volumes: vereinzelt alte Tokens aus gemischten Verzeichnissen.

Tabelle 1: Lokaler Build vs. OPENCLAW_IMAGE (GHCR)

Im Change-Ticket einen Hauptpfad wählen und Rollback auf dem anderen dokumentieren—kein mündliches Vermischen.

DimensionStandard-QuellbuildOPENCLAW_IMAGE zieht GHCR
Am besten fürEigene Dockerfile-Änderungen, Build-Cache-Debug, kein ghcr-EgressSchnellste Zeit bis UI, begrenzte Bandbreite, CI cached Images statt Repos
VoraussetzungenGenug CPU/RAM; GB-Cache für LayerErreichbares ghcr.io oder interner Mirror; Tags über bloßes latest hinaus pinnen
RisikenBuild-Timeouts, Cache-Bloat, CPU-KonkurrenzAuth/Rate-Limits, Tag-Drift, Config-Skew zur Binary
RollbackAuf vorgebautes Image wechseln, gleicher Daten-Volume-PfadZum vorherigen Digest oder zurück zum Quellbuild; Compose-Änderungen loggen
info

Hinweis: Upstream-Repos ändern sich; die Befehle setzen ein Checkout mit docker-setup.sh im Repo-Root voraus—bei Forks Commit und Skriptpfad notieren.

6-Schritte-Runbook: Clone bis Control UI auf 18789

  1. Docker-Preflight: docker version und Compose v2; Platz für Layer/Volumes (wie in der Ressourcentabelle der Produktion).
  2. Clone und Repo-Root: docker-setup.sh ausführbar (chmod +x bei Bedarf).
  3. (Optional) Vorgebautes Image: export OPENCLAW_IMAGE=ghcr.io/openclaw/openclaw:latest—in Produktion Digest oder stabile Tags pinnen, nicht nur Tags nachziehen.
  4. Skript ausführen: ./docker-setup.sh; Logs zeigen Pull/Build und Compose up ohne sofortigen Exit ≠ 0.
  5. Control UI öffnen: http://127.0.0.1:18789 (andere Revision → Port laut Build); Seite lädt, kein Connection refused.
  6. Kürzeste Validierung: dokumentierter Healthcheck in UI oder CLI; Pairing vor App-Config-Änderungen dem Pairing/Token-Artikel folgen.
bash
# GHCR-Vorbild bevorzugen (Tag nach Policy ersetzen)
export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"
./docker-setup.sh

# Bei Erfolg sollte die Control UI laden (Beispiel-Port 18789)
# open http://127.0.0.1:18789

Tabelle 2: Symptome → Checks (Triage-Reihenfolge)

Von oben nach unten; Image, Netzwerk und Volumes nicht gleichzeitig ändern.

SymptomZuerst prüfenAuch lesen
Build-Timeout / OOMAuf OPENCLAW_IMAGE wechseln; Buildkit-Parallelität begrenzen; Cache prunenDocker-Produktion (Ressourcen)
401/403/TLS beim PullProxy-Allowlist für ghcr.io; interner Mirror—nicht nur npm-RegistryNpm-Installations-Runbook (Proxy)
address already in use :18789docker ps auf alte Container; altes Compose stoppen oder Port laut DokuDocker-Netzwerk
Permission denied auf VolumesHost-UID/GID vs. Container-User; named vs. bind MountsVolume/Skills-Checkliste
UI lädt, Kanal stillModell/Kanal-Layer ausschließen; dann Token/WS-CodesPairing/Token

Drei KPIs für Tickets und Dashboards

  1. Image-Identität: Registry + Tag + Digest loggen—nicht nur „latest“; Rollback per Digest.
  2. Control UI erreichbar: HTTP 200 / Seitentitel / Healthcheck getrennt von „Containerprozess existiert“.
  3. Volume-Vertrag: Host-~/.openclaw (oder Team-Pfad) auf Compose-Mounts abbilden; Größe und Rechte vor/nach Upgrade snapshotten.

Widersprechen Upstream-Release-Notes, Upstream vertrauen; dieser Artikel liefert technische Checkpoints.

Warum ein Laptop-Test selten Produktions-Gateway wird

Standby, fragmentierte Platten und Docker-Desktop-Reste stehen dedizierter CPU, stabilem Egress, prüfbaren Volumes und Token-Grenzen entgegen. Ephemere Container ohne gepinnte Digests, Volume-Vertrag oder Healthchecks scheitern beim ersten echten Traffic.

Teams, die Gateway langfristig auf stabiler Apple Silicon hosten, profitieren nach dieser kürzesten Schleife von MACCOME Cloud-Macs mit Multi-Region und flexiblen Mietlaufzeiten—öffentliche Mietpreise und Hilfe/FAQ neben Docker-Produktion und Pairing-Texten lesen.

Pilot: alle sechs Schritte auf dediziertem Remote-Host, Digest und Volume-Snapshots eintragen, dann Monats-/Quartals-Monitoring festlegen.

FAQ

Zuerst diesen Artikel oder Docker-Produktion?

Dieses Runbook für den ersten erfolgreichen UI-Pfad; Produktion für Änderungsfenster, Rollback und Monitoring. Preise: Mac mini Mietpreise.

Kollidiert OPENCLAW_IMAGE mit npm-global-CLI?

Konflikte bei Ports, Env und Datenverzeichnissen; ein primäres Gateway pro Host. Migrationsreihenfolge: npm-Installations-Runbook.

Darf ich 18789 öffentlich exponieren?

Reverse Proxy und TLS davor—Sicherheitsabschnitte in Produktion/Reverse-Proxy-Artikeln statt blind 0.0.0.0. Hilfe: Mac mini Hilfe & FAQ.