Le réseau Docker est la raison pour laquelle j’ai presque abandonné ma configuration OpenClaw containerisée. Tout fonctionnait localement — l’agent pouvait accéder à la base de données, se connecter à l’API, servir les webhooks. Puis je l’ai mis dans Docker et rien ne pouvait communiquer avec rien d’autre.
Si vous avez déjà regardé une erreur « connexion refusée » depuis l’intérieur d’un conteneur Docker en pensant « mais ça fonctionne sur l’hôte », cet article est pour vous. J’ai fait toutes les erreurs de mise en réseau Docker possibles pour que vous n’ayez pas à le faire.
L’erreur qui m’a piégé
Ma configuration OpenClaw avait la connexion à la base de données réglée sur localhost:5432. Sur la machine hôte, cela fonctionnait parfaitement — PostgreSQL écoutait sur localhost. À l’intérieur du conteneur Docker, localhost fait référence au conteneur lui-même, et non à l’hôte. PostgreSQL ne s’exécute pas à l’intérieur du conteneur, donc la connexion échoue.
C’est le niveau 101 de la mise en réseau Docker, et j’y suis tombé quand même. La solution : utiliser host.docker.internal (sur Docker Desktop) ou l’adresse IP réelle de l’hôte à la place de localhost.
Les pièges courants
Piège 1 : Communication entre conteneurs. Si OpenClaw et PostgreSQL sont dans des conteneurs séparés, ils ne peuvent pas communiquer entre eux à moins qu’ils ne soient sur le même réseau Docker. Le réseau de bridge par défaut offre une isolation — excellent pour la sécurité, horrible quand vous avez vraiment besoin que les services communiquent.
Solution : créez un réseau de bridge défini par l’utilisateur et attachez les deux conteneurs à celui-ci. Les conteneurs sur le même réseau défini par l’utilisateur peuvent se rejoindre par le nom du conteneur. Ainsi, OpenClaw se connecte à postgres:5432 au lieu de localhost:5432.
Piège 2 : Confusion sur le mappage des ports. Vous avez mappé le port 3000 dans le conteneur au port 8080 sur l’hôte avec -p 8080:3000. De l’extérieur du conteneur, vous y accédez au port 8080. De l’intérieur d’un autre conteneur sur le même réseau, vous y accédez au port 3000. Ce sont des ports différents et les confondre provoque des erreurs « connexion refusée » qui sont déconcertantes jusqu’à ce que vous compreniez le mappage.
Piège 3 : Résolution DNS à l’intérieur des conteneurs. Les conteneurs utilisent par défaut le DNS interne de Docker. Si votre configuration OpenClaw fait référence à un service externe par son nom d’hôte, assurez-vous que la résolution DNS fonctionne à l’intérieur du conteneur. J’ai eu des conteneurs qui pouvaient atteindre 8.8.8.8 (l’IP fonctionne) mais pas api.openai.com (la résolution DNS échoue). Solution : définissez explicitement les serveurs DNS dans la commande de démarrage Docker ou le fichier docker-compose.
Piège 4 : Ingress de webhook. Votre point de terminaison de webhook fonctionne sur l’hôte à http://localhost:3000/webhook. Les services externes ne peuvent pas atteindre localhost — c’est votre machine, pas Internet. Vous devez soit exposer une URL publique (via le transfert de port, un proxy inverse ou un service de tunnel), soit utiliser un service de relais de webhook.
Piège 5 : Fuite de variables d’environnement. Docker transmet explicitement les variables d’environnement aux conteneurs. Si votre configuration OpenClaw dépend des variables d’environnement du shell (clés API, chemins), celles-ci n’existent pas automatiquement à l’intérieur du conteneur. Vous devez les passer avec des indicateurs -e ou un fichier env.
Ma configuration Docker Compose
Après avoir lutté avec le réseau pendant une semaine, j’ai opté pour une configuration docker-compose qui gère tous les pièges :
Le fichier compose définit trois services : OpenClaw, PostgreSQL et un proxy inverse (Caddy). Les trois sont sur un réseau de bridge personnalisé appelé agent-net.
Décisions clés :
– OpenClaw se connecte à la base de données en utilisant le nom du service db comme nom d’hôte
– Caddy gère la terminaison SSL et route le trafic de webhook externe vers OpenClaw
– Seul Caddy expose des ports à l’hôte (80 et 443)
– Les clés API sont chargées à partir d’un fichier env, pas codées en dur
– Les volumes persistent les données entre les redémarrages de conteneurs (données de la base de données, configuration OpenClaw, journaux)
Débogage des problèmes de réseau Docker
Quand quelque chose ne se connecte pas, voici ma séquence de débogage :
1. Le conteneur peut-il atteindre Internet ? docker exec openclaw ping 8.8.8.8. Si non : problème de mode réseau ou problème de pare-feu.
2. Le conteneur peut-il résoudre le DNS ? docker exec openclaw nslookup api.openai.com. Si non : problème de configuration DNS.
3. Le conteneur peut-il atteindre l’autre service ? docker exec openclaw ping db. Si non : les conteneurs ne sont pas sur le même réseau.
4. Le conteneur peut-il atteindre le port du service ? docker exec openclaw nc -z db 5432. Si non : le service n’écoute pas, ou il est sur un port différent de celui attendu.
5. Le service accepte-t-il des connexions ? Essayez de vous connecter avec l’outil client réel (psql, curl) depuis l’intérieur du conteneur. Si le ping fonctionne mais que l’application ne fonctionne pas, c’est un problème d’authentification ou de configuration, et non de réseau.
Cette séquence élimine systématiquement les possibilités. La plupart des problèmes de réseau sont résolus par l’étape 3.
Considérations de performance
Docker ajoute une fine couche de surcharge aux opérations réseau. Pour la plupart des charges de travail OpenClaw, cela est indétectable — l’appel API de l’IA prend 2 secondes, et la surcharge réseau de Docker est de microsecondes.
Là où cela compte : si vous effectuez des opérations de lecture/écriture de fichiers lourdes via des volumes Docker, les performances peuvent être nettement plus lentes sur macOS (Docker Desktop utilise une VM, et les montages de volumes passent par la couche VM). Sur Linux, les volumes Docker natifs ont une surcharge négligeable.
Pour la plupart des utilisateurs : la surcharge réseau de Docker n’est pas une raison pour éviter la containerisation. L’isolement, la capacité de réplication et la facilité de déploiement l’emportent sur le coût de performance marginal.
🕒 Published: