Die Docker-Netzwerktechnologie war der Grund, warum ich fast meine containerisierte OpenClaw-Installation aufgegeben hätte. Alles funktionierte lokal – der Agent konnte auf die Datenbank zugreifen, sich mit der API verbinden und Webhooks bedienen. Dann habe ich es in Docker gesetzt und nichts konnte mit nichts kommunizieren.
Wenn du jemals auf einen “Verbindung verweigert”-Fehler von innerhalb eines Docker-Containers gestarrt hast und gedacht hast “aber es funktioniert auf dem Host,” dann ist dieser Artikel für dich. Ich habe jeden denkbaren Docker-Netzwerkfehler gemacht, damit du es nicht musst.
Der Fehler, der mich erwischte
Meine OpenClaw-Konfiguration hatte die Datenbankverbindung auf localhost:5432 gesetzt. Auf der Hostmaschine funktionierte das perfekt – PostgreSQL horchte auf localhost. Innerhalb des Docker-Containers bezieht sich localhost jedoch auf den Container selbst, nicht auf den Host. PostgreSQL läuft nicht im Container, daher schlägt die Verbindung fehl.
Das ist Docker Networking 101, und ich bin trotzdem darauf hereingefallen. Die Lösung: verwende host.docker.internal (auf Docker Desktop) oder die tatsächliche IP-Adresse des Hosts anstelle von localhost.
Die häufigsten Fallstricke
Fallstrick 1: Container-zu-Container-Kommunikation. Wenn OpenClaw und PostgreSQL in separaten Containern sind, können sie nicht miteinander kommunizieren, es sei denn, sie befinden sich im selben Docker-Netzwerk. Das standardmäßige Bridge-Netzwerk bietet Isolation – großartig für die Sicherheit, schrecklich, wenn du tatsächlich Dienstleistungen benötigst, die kommunizieren.
Lösung: Erstelle ein benutzerdefiniertes Bridge-Netzwerk und hänge beide Container daran. Container im selben benutzerdefinierten Netzwerk können sich über den Containernamen erreichen. So verbindet sich OpenClaw mit postgres:5432 anstelle von localhost:5432.
Fallstrick 2: Verwirrung bei der Port-Zuordnung. Du hast Port 3000 im Container auf Port 8080 auf dem Host mit -p 8080:3000 gemappt. Von außen auf den Container greifst du auf Port 8080 zu. Von innen in einem anderen Container im selben Netzwerk greifst du auf Port 3000 zu. Diese sind unterschiedlich und die Verwechslung führt zu “Verbindung verweigert”-Fehlern, die mysteriös sind, bis du die Zuordnung verstehst.
Fallstrick 3: DNS-Auflösung innerhalb von Containern. Container verwenden standardmäßig Dockers internes DNS. Wenn deine OpenClaw-Konfiguration einen externen Dienst über den Hostnamen referenziert, stelle sicher, dass die DNS-Auflösung innerhalb des Containers funktioniert. Ich hatte Container, die 8.8.8.8 (IP funktioniert) erreichen konnten, aber nicht api.openai.com (DNS schlägt fehl). Lösung: Setze die DNS-Server explizit im Docker-Run-Befehl oder in der docker-compose-Datei.
Fallstrick 4: Webhook-Eingang. Dein Webhook-Endpunkt funktioniert auf dem Host unter http://localhost:3000/webhook. Externe Dienste können localhost nicht erreichen – das ist deine Maschine, nicht das Internet. Du musst entweder eine öffentliche URL freigeben (durch Portweiterleitung, einen Reverse-Proxy oder einen Tunnel-Dienst) oder einen Webhook-Relay-Dienst verwenden.
Fallstrick 5: Leakage von Umgebungsvariablen. Docker übergibt Umgebungsvariablen explizit an Container. Wenn deine OpenClaw-Konfiguration auf Shell-Umgebungsvariablen (API-Schlüssel, Pfade) angewiesen ist, existieren diese nicht automatisch innerhalb des Containers. Du musst sie mit -e-Flags oder einer env-Datei übergeben.
Mein Docker-Compose-Setup
Nachdem ich eine Woche lang mit Netzwerkkonfigurationen gekämpft habe, habe ich mich für ein docker-compose-Setup entschieden, das alle Fallstricke berücksichtigt:
Die Compose-Datei definiert drei Dienste: OpenClaw, PostgreSQL und einen Reverse-Proxy (Caddy). Alle drei sind in einem benutzerdefinierten Bridge-Netzwerk namens agent-net.
Wichtige Entscheidungen:
– OpenClaw verbindet sich mit der Datenbank über den Servicenamen db als Hostnamen
– Caddy übernimmt die SSL-Terminierung und leitet externen Webhook-Verkehr an OpenClaw weiter
– Nur Caddy gibt Ports an den Host weiter (80 und 443)
– API-Schlüssel werden aus einer env-Datei geladen, nicht hartkodiert
– Volumes speichern Daten bei Container-Neustarts (Datenbankdaten, OpenClaw-Konfiguration, Protokolle)
Fehlerbehebung bei Docker-Netzwerkproblemen
Wenn etwas nicht verbindet, hier ist meine Fehlersuche-Reihenfolge:
1. Kann der Container das Internet erreichen? docker exec openclaw ping 8.8.8.8. Wenn nicht: Problem im Netzwerkmodus oder Firewall-Problem.
2. Kann der Container DNS auflösen? docker exec openclaw nslookup api.openai.com. Wenn nicht: Problem mit der DNS-Konfiguration.
3. Kann der Container den anderen Dienst erreichen? docker exec openclaw ping db. Wenn nicht: Container sind nicht im selben Netzwerk.
4. Kann der Container den Port des Dienstes erreichen? docker exec openclaw nc -z db 5432. Wenn nicht: Der Dienst hört nicht zu oder ist auf einem anderen Port als erwartet.
5. Akzeptiert der Dienst Verbindungen? Versuche es mit dem tatsächlichen Client-Tool (psql, curl) von innerhalb des Containers zu verbinden. Wenn der Ping funktioniert, die Anwendung jedoch nicht, liegt es an einem Authentifizierungs- oder Konfigurationsproblem, nicht am Netzwerk.
Diese Reihenfolge schließt Möglichkeiten systematisch aus. Die meisten Netzwerkprobleme werden durch Schritt 3 gelöst.
Leistungsüberlegungen
Docker fügt Netzwerkoperationen eine dünne Schicht von Overhead hinzu. Für die meisten OpenClaw-Workloads ist dies nicht spürbar – der AI-API-Aufruf benötigt 2 Sekunden und der Netzwerk-Overhead von Docker liegt im Mikrosekundenbereich.
Wo es wichtig ist: Wenn du intensive lokale Datei-I/O über Docker-Volumes machst, kann die Leistung auf macOS merklich langsamer sein (Docker Desktop verwendet eine VM und Volume-Mounts durchlaufen die VM-Schicht). Unter Linux haben native Docker-Volumes vernachlässigbaren Overhead.
Für die meisten Benutzer: Der Netzwerk-Overhead von Docker ist kein Grund, die Containerisierung zu vermeiden. Die Vorteile von Isolation, Reproduzierbarkeit und einfacher Bereitstellung überwiegen die marginalen Leistungskosten.
🕒 Published: