Domptage du réseau Docker OpenClaw : pièges courants

Le réseau Docker est la raison pour laquelle j’ai failli abandonner ma configuration OpenClaw conteneurisée. Tout fonctionnait localement — l’agent pouvait atteindre la base de données, se connecter à l’API, servir des webhooks. Puis je l’ai mis dans Docker et rien ne pouvait communiquer.

Si vous avez déjà regardé une erreur « connexion refusée » depuis l’intérieur d’un conteneur Docker et pensé « mais ça fonctionne sur l’hôte », cet article est pour vous. J’ai commis toutes les erreurs possibles en matière de réseau Docker 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 désigne le conteneur lui-même, pas l’hôte. PostgreSQL ne fonctionne pas à l’intérieur du conteneur, donc la connexion échoue.

C’est le réseau Docker 101, et je suis quand même tombé dans le piège. La solution : utilisez host.docker.internal (sur Docker Desktop) ou l’adresse IP réelle de l’hôte au lieu 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 à moins qu’ils ne soient sur le même réseau Docker. Le réseau par défaut « bridge » offre de l’isolation — excellent pour la sécurité, terrible lorsque vous avez réellement besoin que les services communiquent.

Solution : créez un réseau « bridge » défini par l’utilisateur et attachez-y les deux conteneurs. Les conteneurs sur le même réseau défini par l’utilisateur peuvent se joindre par le nom de 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 via le port 8080. De l’intérieur d’un autre conteneur sur le même réseau, vous y accédez via le port 3000. Ce sont deux choses différentes et les confondre provoque des erreurs « connexion refusée » qui sont déroutantes tant que vous ne comprenez pas 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 capables d’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 Docker run 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 reverse proxy ou un service de tunnel), soit utiliser un service de relais de webhook.

Piège 5 : fuite de variables d’environnement. Docker passe explicitement les variables d’environnement aux conteneurs. Si votre configuration OpenClaw dépend des variables d’environnement shell (clés API, chemins), celles-ci n’existent pas automatiquement à l’intérieur du conteneur. Vous devez les passer avec les drapeaux -e ou un fichier env.

Ma configuration Docker Compose

Après avoir lutté avec le réseau pendant une semaine, j’ai choisi une configuration docker-compose qui gère tous les pièges :

Le fichier compose définit trois services : OpenClaw, PostgreSQL et un reverse proxy (Caddy). Les trois sont sur un réseau « bridge » personnalisé appelé agent-net.

Décisions clés :
– OpenClaw se connecte à la base de données en utilisant le nom de service db comme nom d’hôte
– Caddy gère la terminaison SSL et dirige le trafic 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 à travers les redémarrages des conteneurs (données de 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 des 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, pas de réseau.

Cette séquence élimine les possibilités systématiquement. La plupart des problèmes de réseau sont résolus à l’étape 3.

Considérations sur la performance

Docker ajoute une fine couche de surcharge aux opérations réseau. Pour la plupart des charges de travail OpenClaw, c’est indétectable — l’appel API AI prend 2 secondes, et la surcharge réseau de Docker est en microsecondes.

Là où c’est important : si vous effectuez de lourdes opérations de fichiers locaux via des volumes Docker, la performance peut être notablement plus lente 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 d’éviter la conteneurisation. L’isolation, la reproductibilité et la facilité de déploiement l’emportent sur le coût de performance marginal.

🕒 Published: March 26, 2026