Das Docker-Netzwerk ist der Grund, warum ich fast meine containerisierte OpenClaw-Konfiguration 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 gesteckt und nichts konnte kommunizieren.
Wenn Sie jemals einen Fehler „Verbindung abgelehnt“ von innen eines Docker-Containers gesehen haben und gedacht haben „aber es funktioniert auf dem Host“, dann ist dieser Artikel für Sie. Ich habe alle möglichen Fehler im Docker-Netzwerk gemacht, damit Sie es nicht tun müssen.
Der Fehler, der mich getäuscht hat
Meine OpenClaw-Konfiguration hatte die Datenbankverbindung auf localhost:5432 eingestellt. Auf der Hostmaschine funktionierte es einwandfrei – PostgreSQL hörte auf localhost. Innerhalb des Docker-Containers bezeichnet localhost den Container selbst, nicht den Host. PostgreSQL läuft nicht innerhalb des Containers, also schlägt die Verbindung fehl.
Das ist das Docker-Netzwerk 101, und ich bin trotzdem in die Falle getappt. Die Lösung: Verwenden Sie host.docker.internal (auf Docker Desktop) oder die echte IP-Adresse des Hosts anstelle von localhost.
Häufige Fallstricke
Fallstrick 1: Kommunikation zwischen Containern. Wenn OpenClaw und PostgreSQL in separaten Containern sind, können sie nicht kommunizieren, es sei denn, sie befinden sich im selben Docker-Netzwerk. Das Standardnetzwerk „bridge“ bietet Isolation – hervorragend für die Sicherheit, schrecklich, wenn Sie tatsächlich möchten, dass die Dienste kommunizieren.
Lösung: Erstellen Sie ein benutzerdefiniertes „bridge“-Netzwerk und fügen Sie beide Container hinzu. Container im selben benutzerdefinierten Netzwerk können sich über den Containernamen verbinden. So verbindet sich OpenClaw mit postgres:5432 anstelle von localhost:5432.
Fallstrick 2: Verwirrung über Port-Mapping. Sie haben den Port 3000 im Container auf den Port 8080 auf dem Host mit -p 8080:3000 gemappt. Von außerhalb des Containers greifen Sie über den Port 8080 zu. Von innen eines anderen Containers im selben Netzwerk greifen Sie über den Port 3000 zu. Das sind zwei verschiedene Dinge, und sie zu verwechseln führt zu „Verbindung abgelehnt“-Fehlern, die verwirrend sind, solange Sie das Mapping nicht verstehen.
Fallstrick 3: DNS-Resolution innerhalb von Containern. Container verwenden standardmäßig den internen Docker-DNS. Wenn Ihre OpenClaw-Konfiguration auf einen externen Dienst anhand seines Hostnamens verweist, stellen Sie sicher, dass die DNS-Auflösung innerhalb des Containers funktioniert. Ich hatte Container, die 8.8.8.8 erreichen konnten (die IP funktioniert), aber nicht api.openai.com (die DNS-Auflösung schlägt fehl). Lösung: Definieren Sie die DNS-Server explizit in dem Docker-Befehl oder der docker-compose-Datei.
Fallstrick 4: Webhook-Ingress. Ihr Webhook-Endpunkt funktioniert auf dem Host unter http://localhost:3000/webhook. Externe Dienste können localhost nicht erreichen – das ist Ihre Maschine, nicht das Internet. Sie müssen entweder eine öffentliche URL bereitstellen (über Portweiterleitung, einen Reverse Proxy oder einen Tunnelservice) oder einen Webhook-Relay-Service verwenden.
Fallstrick 5: Leckage von Umgebungsvariablen. Docker übergibt Umgebungsvariablen explizit an die Container. Wenn Ihre OpenClaw-Konfiguration von Shell-Umgebungsvariablen (API-Schlüssel, Pfade) abhängt, existieren diese nicht automatisch innerhalb des Containers. Sie müssen sie mit den -e-Flags oder einer env-Datei übergeben.
Meine Docker Compose-Konfiguration
Nach einer Woche des Kämpfens mit dem Netzwerk habe ich eine docker-compose-Konfiguration gewählt, die alle Fallstricke berücksichtigt:
Die Compose-Datei definiert drei Dienste: OpenClaw, PostgreSQL und einen Reverse Proxy (Caddy). Alle drei befinden sich in einem benutzerdefinierten „bridge“-Netzwerk namens agent-net.
Wichtige Entscheidungen:
– OpenClaw verbindet sich mit der Datenbank unter Verwendung des Servicenamens db als Hostnamen
– Caddy verwaltet die SSL-Termination und leitet den externen Webhook-Verkehr an OpenClaw weiter
– Nur Caddy exponiert Ports zum Host (80 und 443)
– API-Schlüssel werden aus einer env-Datei geladen, nicht fest codiert
– Die Volumes persistieren die Daten über Containerneustarts hinweg (Datenbankdaten, OpenClaw-Konfiguration, Logs)
Fehlerbehebung bei Docker-Netzwerkproblemen
Wenn etwas sich nicht verbindet, ist hier meine Fehlersuche-Sequenz:
1. Kann der Container das Internet erreichen? docker exec openclaw ping 8.8.8.8. Wenn nicht: Netzwerkmodusproblem oder Firewallproblem.
2. Kann der Container DNS auflösen? docker exec openclaw nslookup api.openai.com. Wenn nicht: DNS-Konfigurationsproblem.
3. Kann der Container den anderen Dienst erreichen? docker exec openclaw ping db. Wenn nicht: Die Container sind nicht im selben Netzwerk.
4. Kann der Container den Dienstport erreichen? docker exec openclaw nc -z db 5432. Wenn nicht: Der Dienst lauscht nicht oder er ist auf einem anderen als dem erwarteten Port.
5. Akzeptiert der Dienst Verbindungen? Versuchen Sie sich von innen im Container mit dem tatsächlichen Client-Tool (psql, curl) zu verbinden. Wenn der Ping funktioniert, die Anwendung aber nicht, ist das ein Authentifizierungs- oder Konfigurationsproblem, kein Netzwerkproblem.
Diese Sequenz schließt die Möglichkeiten systematisch aus. Die meisten Netzwerkprobleme werden in Schritt 3 gelöst.
Leistungsüberlegungen
Docker fügt den Netzwerkoperationen eine geringe Overhead-Schicht hinzu. Für die meisten OpenClaw-Workloads ist dies unmerklich – der API-Call dauert 2 Sekunden, und der Netzwerk-Overhead von Docker bewegt sich im Mikrosekundenbereich.
Wo es wichtig ist: Wenn Sie umfangreiche lokale Dateioperationen über Docker-Volumes durchführen, kann die Leistung auf macOS merklich langsamer sein (Docker Desktop verwendet eine VM, und die Volume-Mounts gehen durch die VM-Schicht). Auf Linux haben native Docker-Volumes eine vernachlässigbare Overhead.
Für die meisten Benutzer: Der Netzwerk-Overhead von Docker ist kein Grund, die Containerisierung zu vermeiden. Die Isolation, Reproduzierbarkeit und einfache Bereitstellung überwiegen die marginalen Leistungskosten.
🕒 Published: