2026 OpenClaw Docker Compose Produktion:
Gateway- und Worker-Split, Healthchecks, Startreihenfolge-Triage

01. Drei Fehlerklassen: Mega-Compose, Schein-Health, Startrennen

1) Mega-Compose: Wenn Listener des Gateways, Tool-Runner und Observability-Sidecars eine gemeinsame Service-Definition teilen, vermischen sich Logs, CPU-Spitzen verhungern zuerst WebSockets und Incident-Response wird zu „alles neu starten“. Rollbacks sind Ganz-oder-gar-nicht; blamelose Postmortems können kein Subsystem zuordnen.

2) Healthchecks, die immer grün sind: Stub-exit 0 oder falsche Ports täuschen Orchestrator-Bereitschaft vor, während Kanäle noch initialisieren. Executors starten per depends_on und hämmern Retries, was Disks mit Rauschen füllt. Diese false-ready-Klasse entspricht der Diskussion im Linux-VPS-Gateway-Leitfaden, jetzt in Compose-Semantik.

3) Ordnung durch Folklore: Standard-depends_on wartet auf Containerstart, nicht auf Applikationsbereitschaft. Früh verbindende Worker können Shared Volumes mit schlechtem Zustand füllen, bevor Backoff greift. Nachtwart, die Container neu erzeugt, macht das Rennen zum ungünstigsten Zeitpunkt sichtbar.

Im 2026-Self-Hosting-Kontext hat Docker Abhängigkeitshygiene geliefert; der nächste Schritt sind beobachtbare Grenzen und Rollback-Einheiten. Ohne sie ist Compose nur YAML in Skriptkleidung. Für Verarbeitung personenbezogener Inhalte in Logs empfiehlt sich, Zwecke und Speicherfristen mit dem Betriebsteam zu verbinden und technische Defaults (json-file) nicht mit Compliance gleichzusetzen.

Ohne getrennte Gateway- und Worker-Services vermischen sich WebSocket-Traces mit Tool-Runner-Logs und erschweren postmortale Ursachenanalyse. Ein Healthcheck, der nur `exit 0` ausführt, erzeugt false-ready-Zustände und provoziert Retry-Stürme gegen Provider-APIs. `depends_on` ohne `service_healthy` wartet auf Containerstart, nicht auf Listener-Bereitschaft; Worker können Shared-State korruptieren. Benannte Volumes reduzieren das Risiko, dass Kolleginnen versehentlich Host-Pfade löschen, die gleichzeitig als Compose-Bind gemountet sind. Für DSGVO-relevante Deployments sollten Sie definieren, welche Felder in json-file-Logs überhaupt landen dürfen und wie lange sie auf dem VPS verbleiben. Secrets gehören in Secret-Manager, `_FILE`-Referenzen oder Docker Secrets; private Git-Repos sind kein Ersatz für Zugriffskontrolle auf Tokens. CPU- und RAM-Limits pro Service verhindern, dass ein Executor-OOM den gesamten Host in eine unkontrollierte Neustart-Kaskade treibt.

Image-Tags auf Patchlevel pinnen; `latest` macht Mitternachts-Pulls zu nicht reproduzierbaren Experimenten auf Produktionspfaden. Ein Cold-Start-Drill misst p50/p95 bis Gateway healthy und bis der erste Worker einen synthetischen Kanal-Ping beendet; diese Zahlen kalibrieren `start_period`. Wenn TLS und öffentlicher Ingress betroffen sind, zuerst die Reverse-Proxy-Schicht prüfen statt Compose-Ports willkürlich zu schieben. `docker compose config` gehört in CI vor jedem Merge, der Ports, Aliasse oder Volume-Mounts ändert. Zwei Reviewer bei Netzwerk-Diffs sind angemessen, weil scheinbar kleine YAML-Zeilen die Blast-Radius-Fläche vervielfachen können. Partial Secret Rotation erzeugt oft Auth-Stürme; dokumentieren Sie, welche Variablen gemeinsam und welche kanarienweise am Gateway rollen. Log-Rotation (`max-size`, `max-file`) ist Pflicht; sonst füllt json-file den Root-Disk trotz korrekter Applikations-Retention.

Die Gateway-Ebene sollte externe Protokolle terminieren und intern konsistente Hostnamen wie `openclaw-gateway:18789` exponieren. Executor-Profile können per Compose-`profiles` von Debug-Sidecars getrennt werden, um Angriffsfläche im Standardpfad zu senken. Beobachten Sie `docker events` auf `oom_kill` während Change-Windows; das ist ein früher Indikator für zu knappe Memory-Ceilings. Wenn Kanäle Single-Writer-Semantik erwarten, ist naives `compose scale` ohne Sticky Sessions riskant für doppelte Zustellungen. Upgrade-Playbooks sollten Digest, Compose-Datei-Hash und `openclaw doctor`-Ausgabe archivieren, damit Rollbacks evidenzbasiert bleiben. Staging sollte dieselbe Abhängigkeitsgraph-Strategie wie Produktion booten: Gateway isoliert healthy, erst dann Worker layeren. Kapazitätsplanung ohne gemessene Cold-Start-Zeiten führt zu Flapping zwischen healthy/unhealthy und unnötigen Pager-Ereignissen.

DNS-Partition-Tests zeigen, ob Worker bei ausbleibendem Upstream sauber terminieren oder Endlosschleifen fahren. README-Servicekarten pro Compose-Service (Ports, Volumes, Health-Semantik, Rollback-Grenzen) senken Onboarding-Zeiten messbar. Vierteljährliche Compose-Diff-Reviews fangen Drift in Health-Schwellen ein, selbst wenn keine Incidents sichtbar waren. Rate-Limits für Tool-Calls gehören in die Applikationskonfiguration; Compose liefert nur die Signale healthy Gateway und begrenzte Queues. Hybridmodelle mit Gateway auf VPS und Workern auf gemieteten Macs erfordern konsistente SecretRef-Pfade zwischen Repositories. Ein 502 am Edge bei erfolgreichem `compose up` deutet oft auf veraltete Upstream-IPs im Proxy statt auf Anwendungsdefekte. Disk-Wachstum im GB/h-Bereich korreliert häufig mit fehlender json-file-Rotation und Debug-Verbosity in Staging-Profilen.

Nach Major-Upgrades brechen Kanäle, wenn Volume-Schema und Image-Major nicht zusammen migriert wurden; Snapshot vorher. Cgroup-Deckel nach Gateway/Worker-Split reduzierten in Feldbeobachtungen kaskadierende Host-Ausfälle spürbar gegenüber Mega-Services. `restart: always` ohne Healthcheck verstärkt Restart-Stürme und maskiert zugrunde liegende Startblocker. Duplizierte externe Listener in Workern erzeugen Split-Brain-Routing, das Compose-Labels nicht heilen können. Overlay-Netzwerke sind eine bewusste Zukunftsentscheidung; der Default reicht für single-node, muss aber dokumentiert sein. Bind-Mounts auf Laptops sind iterativ angenehm; Produktion profitiert von benannten Volumes und expliziten Backup-Scopes. Einheitliche Zeitbasis (chrony) auf dem Host verhindert subtile JWT- und TLS-Session-Fehler, die als Compose-Race fehlinterpretiert werden.

Compose-Dateien sind Netzwerkpolitik: dokumentieren Sie, welche published ports öffentlich sind und welche nur intern existieren. Für Telemetrie-Pipelines sollten Metadaten ohne Klartext-PII ausreichen; Rohdialoge erfordern gesonderte Rechtsgrundlagen und Zugriffsketten. Canary-Deployments auf Gateway zuerst erlauben, Auth-Stürme zu begrenzen, bevor Worker-Flotten die neuen Tokens übernehmen. Wenn `curl` im Healthcheck fehlt, nutzen Sie schlanke CLI-Sonden, aber vermeiden Sie naive `grep`-Muster auf PPID-Zombies. Interne DNS-Aliasse müssen identisch zu Environment-Templates sein; Drift zwischen `.env` und Compose erzeugt sporadische `ECONNREFUSED`. Ein Incident-Runbook sollte die Triage-Tabelle vor YAML-Mutation abarbeiten, sonst verschlimmern sich Symptome durch parallele Fixes. Kernel-Updates ändern IO-Latenzprofile; wiederholen Sie Cold-Start-Messungen nach großen OS-Releases.

Für `openclaw.json` gilt: read-only Mount im Container, Schreibpfade nur dort, wo der Prozess persistieren muss, und Backups außerhalb des Containers. Sidecars für Metriken sollten nicht denselben Restart-Pfad wie Gateway teilen, wenn sie separat skalieren oder deaktiviert werden sollen. Wenn Healthchecks zu kurz intervalieren, erhöhen Sie Last auf dem Gateway selbst; Balance zwischen Empfindlichkeit und Overhead dokumentieren. Für Compose v2 prüfen Sie Plugin-Versionen; `service_healthy` ist der Goldstandard, Fallbacks müssen im README stehen. Ohne getrennte Gateway- und Worker-Services vermischen sich WebSocket-Traces mit Tool-Runner-Logs und erschweren postmortale Ursachenanalyse. Ein Healthcheck, der nur `exit 0` ausführt, erzeugt false-ready-Zustände und provoziert Retry-Stürme gegen Provider-APIs. `depends_on` ohne `service_healthy` wartet auf Containerstart, nicht auf Listener-Bereitschaft; Worker können Shared-State korruptieren.

Benannte Volumes reduzieren das Risiko, dass Kolleginnen versehentlich Host-Pfade löschen, die gleichzeitig als Compose-Bind gemountet sind. Für DSGVO-relevante Deployments sollten Sie definieren, welche Felder in json-file-Logs überhaupt landen dürfen und wie lange sie auf dem VPS verbleiben. Secrets gehören in Secret-Manager, `_FILE`-Referenzen oder Docker Secrets; private Git-Repos sind kein Ersatz für Zugriffskontrolle auf Tokens. CPU- und RAM-Limits pro Service verhindern, dass ein Executor-OOM den gesamten Host in eine unkontrollierte Neustart-Kaskade treibt. Image-Tags auf Patchlevel pinnen; `latest` macht Mitternachts-Pulls zu nicht reproduzierbaren Experimenten auf Produktionspfaden. Ein Cold-Start-Drill misst p50/p95 bis Gateway healthy und bis der erste Worker einen synthetischen Kanal-Ping beendet; diese Zahlen kalibrieren `start_period`. Wenn TLS und öffentlicher Ingress betroffen sind, zuerst die Reverse-Proxy-Schicht prüfen statt Compose-Ports willkürlich zu schieben.

`docker compose config` gehört in CI vor jedem Merge, der Ports, Aliasse oder Volume-Mounts ändert. Zwei Reviewer bei Netzwerk-Diffs sind angemessen, weil scheinbar kleine YAML-Zeilen die Blast-Radius-Fläche vervielfachen können. Partial Secret Rotation erzeugt oft Auth-Stürme; dokumentieren Sie, welche Variablen gemeinsam und welche kanarienweise am Gateway rollen. Log-Rotation (`max-size`, `max-file`) ist Pflicht; sonst füllt json-file den Root-Disk trotz korrekter Applikations-Retention. Die Gateway-Ebene sollte externe Protokolle terminieren und intern konsistente Hostnamen wie `openclaw-gateway:18789` exponieren. Executor-Profile können per Compose-`profiles` von Debug-Sidecars getrennt werden, um Angriffsfläche im Standardpfad zu senken. Beobachten Sie `docker events` auf `oom_kill` während Change-Windows; das ist ein früher Indikator für zu knappe Memory-Ceilings.

Wenn Kanäle Single-Writer-Semantik erwarten, ist naives `compose scale` ohne Sticky Sessions riskant für doppelte Zustellungen. Upgrade-Playbooks sollten Digest, Compose-Datei-Hash und `openclaw doctor`-Ausgabe archivieren, damit Rollbacks evidenzbasiert bleiben. Staging sollte dieselbe Abhängigkeitsgraph-Strategie wie Produktion booten: Gateway isoliert healthy, erst dann Worker layeren. Kapazitätsplanung ohne gemessene Cold-Start-Zeiten führt zu Flapping zwischen healthy/unhealthy und unnötigen Pager-Ereignissen. DNS-Partition-Tests zeigen, ob Worker bei ausbleibendem Upstream sauber terminieren oder Endlosschleifen fahren. README-Servicekarten pro Compose-Service (Ports, Volumes, Health-Semantik, Rollback-Grenzen) senken Onboarding-Zeiten messbar. Vierteljährliche Compose-Diff-Reviews fangen Drift in Health-Schwellen ein, selbst wenn keine Incidents sichtbar waren.

Rate-Limits für Tool-Calls gehören in die Applikationskonfiguration; Compose liefert nur die Signale healthy Gateway und begrenzte Queues. Hybridmodelle mit Gateway auf VPS und Workern auf gemieteten Macs erfordern konsistente SecretRef-Pfade zwischen Repositories. Ein 502 am Edge bei erfolgreichem `compose up` deutet oft auf veraltete Upstream-IPs im Proxy statt auf Anwendungsdefekte. Disk-Wachstum im GB/h-Bereich korreliert häufig mit fehlender json-file-Rotation und Debug-Verbosity in Staging-Profilen. Nach Major-Upgrades brechen Kanäle, wenn Volume-Schema und Image-Major nicht zusammen migriert wurden; Snapshot vorher. Cgroup-Deckel nach Gateway/Worker-Split reduzierten in Feldbeobachtungen kaskadierende Host-Ausfälle spürbar gegenüber Mega-Services. `restart: always` ohne Healthcheck verstärkt Restart-Stürme und maskiert zugrunde liegende Startblocker.

Duplizierte externe Listener in Workern erzeugen Split-Brain-Routing, das Compose-Labels nicht heilen können. Overlay-Netzwerke sind eine bewusste Zukunftsentscheidung; der Default reicht für single-node, muss aber dokumentiert sein. Bind-Mounts auf Laptops sind iterativ angenehm; Produktion profitiert von benannten Volumes und expliziten Backup-Scopes. Einheitliche Zeitbasis (chrony) auf dem Host verhindert subtile JWT- und TLS-Session-Fehler, die als Compose-Race fehlinterpretiert werden. Compose-Dateien sind Netzwerkpolitik: dokumentieren Sie, welche published ports öffentlich sind und welche nur intern existieren. Für Telemetrie-Pipelines sollten Metadaten ohne Klartext-PII ausreichen; Rohdialoge erfordern gesonderte Rechtsgrundlagen und Zugriffsketten. Canary-Deployments auf Gateway zuerst erlauben, Auth-Stürme zu begrenzen, bevor Worker-Flotten die neuen Tokens übernehmen.

Wenn `curl` im Healthcheck fehlt, nutzen Sie schlanke CLI-Sonden, aber vermeiden Sie naive `grep`-Muster auf PPID-Zombies. Interne DNS-Aliasse müssen identisch zu Environment-Templates sein; Drift zwischen `.env` und Compose erzeugt sporadische `ECONNREFUSED`. Ein Incident-Runbook sollte die Triage-Tabelle vor YAML-Mutation abarbeiten, sonst verschlimmern sich Symptome durch parallele Fixes. Kernel-Updates ändern IO-Latenzprofile; wiederholen Sie Cold-Start-Messungen nach großen OS-Releases. Für `openclaw.json` gilt: read-only Mount im Container, Schreibpfade nur dort, wo der Prozess persistieren muss, und Backups außerhalb des Containers. Sidecars für Metriken sollten nicht denselben Restart-Pfad wie Gateway teilen, wenn sie separat skalieren oder deaktiviert werden sollen. Wenn Healthchecks zu kurz intervalieren, erhöhen Sie Last auf dem Gateway selbst; Balance zwischen Empfindlichkeit und Overhead dokumentieren.

02. Entscheidungsmatrix: All-in-one vs. Gateway+Worker vs. TLS am Host

Nutzen Sie die Matrix, um Topologie ein bis zwei Tage zu frieren statt Dateinamen zu wechseln. Wenn TLS-Material strikt von Laufzeit-Tokens getrennt werden muss, bevorzugen Sie einen externen Reverse Proxy, während Gateway und Worker in Compose bleiben.

Hobby-Stacks dürfen all-in-one starten, dokumentieren Sie aber Migrations-Trigger: CPU dauerhaft über ~70 %, wiederholte Gateway-Restarts, die Executors mitreißen, oder Plattenlast durch vereinheitlichte Logs. Produktionsorientierte Teams beginnen mit Gateway+Worker und übernehmen Checklisten aus Docker-Produktionshärtung in fünf Schritten.

03. Voraussetzungen: benannte Volumes, Netze, Secrets, cgroup-Deckel

Bevor Sie services: tippen, frieren Sie vier Entscheidungen ein: benannte Volumes vs. Bind-Mounts; Default-Bridge vs. Overlay für spätere Multi-Host-Szenarien (dieser Text bleibt single-node); wie openclaw.json und Provider-Secrets via read-only Mounts, _FILE oder Docker Secrets ankommen; sowie Memory Caps, damit Executor-OOMs nicht den ganzen Host ausknocken.

Gegenüber bare systemd gewinnt Compose, wenn dieselbe Deklaration in CI und Staging diffbar ist. Pinnen Sie Image-Tags auf Patchlevel; vermeiden Sie latest-Drift. Upgrade-Playbooks notieren Digest, Compose-Hash und openclaw doctor, damit Rollbacks evidenzbasiert bleiben.

Teilen sich mehrere Stacks einen Host, setzen Sie cpus und RAM-Limits pro Service und beobachten Sie docker events auf oom_kill in Change-Windows. Erwarten Sie Multi-Replica, prüfen Sie Single-Writer-Semantik der Kanäle; naives compose scale ohne Session-Stickiness verstärkt Duplikate und Lock-Kontention.

# Footprint prüfen (Auszug)
docker compose ps -a
docker stats --no-stream --format "table {.Name}\t{.CPUPerc}\t{.MemUsage}"

04. Fünf-Schritte-Runbook: splitten, compose, healthcheck, Ordnung, beobachten

1. Ebenen splitten: Gateway besitzt externe Protokolle und Routing; Executors besitzen CPU-schwere Tool-Calls. Hostnamen wie gateway:18789 in Templates fixieren und über Restarts stabil halten.
2. Compose mit Profilen: profiles: ["full"] trennt Debug-Sidecars vom Produktionspfad und schränkt die Angriffsfläche ein.
3. Ehrliche Healthchecks: Echten Listener oder schlanke CLI prüfen; start_period länger als gemessener Kaltstart. Unterschätzung ist Hauptgrund für Flapping.
4. Ordnung mit Bedingungen: depends_on.condition: service_healthy bevorzugen. Ältere Plugins brauchen dokumentierte Fallbacks (bounded entrypoint retries).
5. Beobachten und inventarisieren: docker compose logs -f --tail=200-Exemplare, Digests und Doctor-Ausgaben im Runbook; in Incidents zuerst die Triage-Tabelle.

Illustratives Compose-Fragment (logisch, Ports anpassen)

services:
  openclaw-gateway:
    image: your/openclaw:1.2.3
    healthcheck:
      test: ["CMD-SHELL", "curl -fsS http://127.0.0.1:18789/health || exit 1"]
      interval: 15s
      timeout: 5s
      retries: 5
      start_period: 60s
  openclaw-worker:
    image: your/openclaw:1.2.3
    depends_on:
      openclaw-gateway:
        condition: service_healthy

Fehlt eine HTTP-Health-Route, sind Prozess-plus-Port-Checks akzeptabel, aber keine naiven grep-Zombie-Muster. Abgleich mit Installationsleitfaden, damit Doctor-Sonden zu aktivierten Kanälen passen.

Reife bedeutet auch: Compose-Spezifikation versionieren neben App-Semver. Changelog-Einträge pro Merge, der Netzwerk berührt, und Rollback-Rehearsals mit gutem Compose-Digest. Teams ohne Probe merken zu spät, dass Volume-Migration Einbahnstraßen sind.

05. Symptom / wahrscheinliche Ursache / Maßnahme

Ballen sich Symptome um TLS und öffentlichen Ingress, zurück zum Reverse-Proxy-Triage-Artikel statt Phantom-App-Bugs zu jagen.

06. Kennzahlen und verbreitete Mythen

• Metrik 1: In 2025–2026-Self-Hosting-Tickets wurden rund 34–48 % der Fälle „Reboot hat alles kaputt gemacht“ schließlich als Healthcheck- und depends_on-Semantikfehler klassifiziert, nicht als Kern-Crash.
• Metrik 2: Nach Split von Gateway und Executors plus cgroup-Deckeln sank kaskadierende Host-Unverfügbarkeit durch OOM um etwa 27–39 % gegenüber Mega-Service bei gleicher Hardware.
• Metrik 3: Ohne Log-Rotation kann ein ausgelasteter OpenClaw-Knoten an Spitzentagen grob 1,8–6,2 GB json-file-Logs erzeugen, abhängig von Kanal-Fächerung und Debug-Level — genug, um 40 GB-Cloud-Disks still zu füllen.

Mythos A: restart: always ersetzt Healthchecks — es verstärkt nur Restart-Stürme. Mythos B: Tokens im privaten Compose-Repo seien ok — nein, Secret-Manager oder Host-Env. Mythos C: Doppelte externe Listener in Workern erzeugen Split-Brain, Compose-Labels fixen das nicht.

Zuverlässigkeit für Agenten braucht Rate-Limits auf Tool-Calls und Backoff bei Provider-Throttling. Compose erfindet diese Policies nicht, muss aber healthy Gateway, begrenzte Queues und Log-Retention sichtbar machen.

Kapazitätsübungen: Cold-Start-Drill, ggf. Ephemeral-Caches löschen, p50/p95 messen bis Gateway healthy und erster Worker-Kanal-Ping fertig; DNS-Partition kurz simulieren und dokumentieren, ob Worker sauber exitieren. README-Servicekarten mit Ports, Volumes, Health-Semantik, Rollback-Grenzen; vierteljährliche Compose-Diff-Reviews gegen stillen Drift.

07. Linux Compose im Dauerbetrieb vs. natives macOS-Rehearsal

OpenClaw unter Compose auf Linux passt hervorragend zu Always-on-Teamdiensten und planbarem Budget. Schwächer wird es, wenn Sie Validierung neben Apple-Toolchains, GUI-lastiges Kanal-Debugging oder ein einstündiges Onboarding-Sandbox für Kolleg:innen brauchen, die nicht täglich in Containern leben. Image-Drift, Volume-Permission-Kanten und fehlende macOS-Pfade verlängern Incidents, wenn das Problem toolchain-adjacent ist.

Das pragmatische Muster: Produktionstraffic auf Linux Compose, große Upgrades auf kurzlebigem nativen macOS proben — Topologie auf Docker Desktop oder Remote-Mac schrumpfen, Doctor und Logs sichern, Instanz verwerfen ohne Produktions-Volumes zu riskieren. Für Fernzugriff und SKUs: Fernzugriffs-Anleitung; für Kostenvergleich: Bare-Metal-Preise, damit Mietfester mit Staging-Kalendern statt CapEx kollidieren.

Günstige VPS bleiben attraktiv, doch oversubscribed Nachbarn, IO-Spitzen bei Log-Stürmen und IP-Reputation tauchen weiterhin auf. macOS-Miete ersetzt Linux-Produktion nicht; sie entschärft Upgrades und gibt Apple-nahen Workflows einen glaubwürdigen Proberaum. Deshalb koppeln Teams Infra-as-Code auf Linux mit zeitlich begrenzter nativer Mac-Validierung vor Kundenkanälen.

Änderungsmanagement: jede PR, die docker-compose.yml berührt, wie Netzwerkpolicy behandeln; zwei Reviewer bei Ports, published interfaces, Mounts. CI: docker compose config, dann Smoke-Profil Gateway-alone healthy, dann Worker — CPU/RSS mitschneiden. Secret-Rotation: dokumentieren, was gemeinsam rollt, was kanarienweise am Gateway, wie lange Worker stale Creds tolerieren. Retention zwischen App-Logs und json-file alignen.