La red de Docker es la razón por la que casi abandoné mi configuración de OpenClaw en contenedores. Todo funcionaba localmente: el agente podía alcanzar la base de datos, conectarse a la API y servir webhooks. Luego lo puse en Docker y nada podía comunicarse con nada.
Si alguna vez miraste un error de “conexión rechazada” desde dentro de un contenedor Docker y pensaste “pero funciona en el host,” este artículo es para ti. Cometí todos los errores posibles en la red de Docker para que tú no tengas que hacerlo.
El Error Que Me Atrapó
Mi configuración de OpenClaw tenía la conexión a la base de datos establecida en localhost:5432. En la máquina host, esto funcionaba a la perfección: PostgreSQL estaba escuchando en localhost. Dentro del contenedor Docker, localhost se refiere al contenedor mismo, no al host. PostgreSQL no se está ejecutando dentro del contenedor, por lo que la conexión falla.
Esto es Docker Networking 101, y aun así caí en la trampa. La solución: usa host.docker.internal (en Docker Desktop) o la dirección IP real del host en lugar de localhost.
Las Trampas Comunes
Trampa 1: Comunicación entre contenedores. Si OpenClaw y PostgreSQL están en contenedores separados, no pueden comunicarse entre sí a menos que estén en la misma red de Docker. La red de puente predeterminada proporciona aislamiento, lo cual es excelente para la seguridad, pero terrible cuando realmente necesitas que los servicios se comuniquen.
Solución: crea una red de puente definida por el usuario y conecta ambos contenedores a ella. Los contenedores en la misma red definida por el usuario pueden alcanzarse entre sí por el nombre del contenedor. Así que OpenClaw se conecta a postgres:5432 en lugar de localhost:5432.
Trampa 2: Confusión de mapeo de puertos. Mapeaste el puerto 3000 en el contenedor al puerto 8080 en el host con -p 8080:3000. Desde fuera del contenedor, accedes a él en el puerto 8080. Desde dentro de otro contenedor en la misma red, accedes a él en el puerto 3000. Estos son diferentes y confundirlos causa errores de “conexión rechazada” que son desconcertantes hasta que entiendes el mapeo.
Trampa 3: Resolución DNS dentro de los contenedores. Los contenedores utilizan el DNS interno de Docker por defecto. Si tu configuración de OpenClaw hace referencia a un servicio externo por nombre de host, asegúrate de que la resolución DNS funcione dentro del contenedor. He tenido contenedores que podían alcanzar 8.8.8.8 (IP funciona) pero no api.openai.com (fallo de DNS). Solución: establece explícitamente los servidores DNS en el comando de ejecución de Docker o en el archivo docker-compose.
Trampa 4: Ingreso de webhook. Tu endpoint de webhook funciona en el host en http://localhost:3000/webhook. Los servicios externos no pueden alcanzar localhost — esa es tu máquina, no Internet. Necesitas exponer una URL pública (a través de la reenvío de puertos, un proxy inverso o un servicio de túnel) o utilizar un servicio de retransmisión de webhook.
Trampa 5: Filtración de variables de entorno. Docker pasa variables de entorno a los contenedores de manera explícita. Si tu configuración de OpenClaw depende de variables de entorno del shell (claves API, rutas), esas no existen automáticamente dentro del contenedor. Necesitas pasarlas con las flags -e o un archivo env.
Mi Configuración de Docker Compose
Después de luchar con la red durante una semana, opté por una configuración de docker-compose que maneja todas las trampas:
El archivo compose define tres servicios: OpenClaw, PostgreSQL y un proxy inverso (Caddy). Los tres están en una red de puente personalizada llamada agent-net.
Decisiones clave:
– OpenClaw se conecta a la base de datos usando el nombre del servicio db como el nombre de host
– Caddy maneja la terminación SSL y enruta el tráfico de webhook externo a OpenClaw
– Solo Caddy expone puertos al host (80 y 443)
– Las claves API se cargan desde un archivo env, no están codificadas
– Los volúmenes persisten datos a través de reinicios de contenedores (datos de la base de datos, configuración de OpenClaw, registros)
Depuración de Problemas de Red en Docker
Cuando algo no se conecta, aquí está mi secuencia de depuración:
1. ¿Puede el contenedor alcanzar Internet? docker exec openclaw ping 8.8.8.8. Si no: problema en el modo de red o problema de firewall.
2. ¿Puede el contenedor resolver DNS? docker exec openclaw nslookup api.openai.com. Si no: problema de configuración de DNS.
3. ¿Puede el contenedor alcanzar el otro servicio? docker exec openclaw ping db. Si no: los contenedores no están en la misma red.
4. ¿Puede el contenedor alcanzar el puerto del servicio? docker exec openclaw nc -z db 5432. Si no: el servicio no está escuchando o está en un puerto diferente al esperado.
5. ¿Está el servicio aceptando conexiones? Intenta conectarte con la herramienta cliente real (psql, curl) desde dentro del contenedor. Si el ping funciona pero la aplicación no, es un problema de autenticación o configuración, no de red.
Esta secuencia elimina posibilidades de manera sistemática. La mayoría de los problemas de red se resuelven en el paso 3.
Consideraciones de Rendimiento
Docker añade una fina capa de sobrecarga a las operaciones de red. Para la mayoría de las cargas de trabajo de OpenClaw, esto es indetectable: la llamada API de IA toma 2 segundos, y la sobrecarga de red de Docker es en microsegundos.
Donde importa: si estás haciendo una I/O pesada de archivos locales a través de volúmenes de Docker, el rendimiento puede ser notablemente más lento en macOS (Docker Desktop usa una VM, y los puntos de montaje de volúmenes pasan a través de la capa de VM). En Linux, los volúmenes de Docker nativos tienen una sobrecarga negligible.
Para la mayoría de los usuarios: la sobrecarga de red de Docker no es una razón para evitar la contenedorización. Los beneficios de aislamiento, reproducibilidad y facilidad de despliegue superan el costo de rendimiento marginal.
🕒 Published: