O rede Docker é a razão pela qual eu quase desisti da minha configuração OpenClaw contêinerizada. Tudo funcionava localmente — o agente conseguia acessar o banco de dados, conectar-se à API, servir webhooks. Então eu coloquei no Docker e nada conseguia se comunicar.
Se você já viu um erro “conexão recusada” de dentro de um contêiner Docker e pensou “mas funciona no host”, este artigo é para você. Eu cometi todos os erros possíveis em relação à rede Docker para que você não precise fazê-lo.
O erro que me pegou
Minha configuração OpenClaw estava com a conexão ao banco de dados definida como localhost:5432. Na máquina host, isso funcionava perfeitamente — o PostgreSQL escutava no localhost. Dentro do contêiner Docker, localhost se refere ao próprio contêiner, não ao host. O PostgreSQL não está rodando dentro do contêiner, portanto a conexão falha.
Isso é o básico da rede Docker, e mesmo assim caí na armadilha. A solução: use host.docker.internal (no Docker Desktop) ou o endereço IP real do host em vez de localhost.
Armadilhas comuns
Armadilha 1: comunicação entre contêineres. Se OpenClaw e PostgreSQL estão em contêineres separados, eles não conseguem se comunicar a menos que estejam na mesma rede Docker. A rede padrão “bridge” oferece isolamento — ótimo para segurança, péssimo quando você realmente precisa que os serviços se comuniquem.
Solução: crie uma rede “bridge” definida pelo usuário e anexe os dois contêineres. Contêineres na mesma rede definida pelo usuário podem se conectar pelo nome do contêiner. Assim, OpenClaw se conecta a postgres:5432 em vez de localhost:5432.
Armadilha 2: confusão sobre o mapeamento de portas. Você mapeou a porta 3000 no contêiner para a porta 8080 no host com -p 8080:3000. De fora do contêiner, você acessa via porta 8080. De dentro de outro contêiner na mesma rede, você acessa via porta 3000. Essas são duas coisas diferentes e confundi-las causa erros “conexão recusada” que são confusos enquanto você não entender o mapeamento.
Armadilha 3: resolução de DNS dentro dos contêineres. Os contêineres usam por padrão o DNS interno do Docker. Se sua configuração OpenClaw faz referência a um serviço externo pelo seu nome de host, certifique-se de que a resolução de DNS funcione dentro do contêiner. Tive contêineres capazes de atingir 8.8.8.8 (o IP funciona) mas não api.openai.com (a resolução de DNS falha). Solução: defina explicitamente os servidores DNS no comando Docker run ou no arquivo docker-compose.
Armadilha 4: ingress de webhook. Seu ponto de extremidade de webhook funciona no host em http://localhost:3000/webhook. Serviços externos não conseguem alcançar localhost — é sua máquina, não a internet. Você precisa expor uma URL pública (via redirecionamento de porta, um reverse proxy ou um serviço de túnel), ou usar um serviço de retransmissão de webhook.
Armadilha 5: vazamento de variáveis de ambiente. O Docker passa explicitamente as variáveis de ambiente para os contêineres. Se sua configuração OpenClaw depende de variáveis de ambiente do shell (chaves API, caminhos), elas não existem automaticamente dentro do contêiner. Você deve passá-las com as flags -e ou um arquivo env.
Minha configuração Docker Compose
Depois de lutar com a rede por uma semana, escolhi uma configuração docker-compose que gerencia todas as armadilhas:
O arquivo compose define três serviços: OpenClaw, PostgreSQL e um reverse proxy (Caddy). Os três estão em uma rede “bridge” personalizada chamada agent-net.
Decisões-chave:
– OpenClaw se conecta ao banco de dados usando o nome de serviço db como nome de host
– Caddy gerencia a terminação SSL e direciona o tráfego de webhook externo para o OpenClaw
– Apenas Caddy expõe portas ao host (80 e 443)
– As chaves API são carregadas a partir de um arquivo env, não codificadas
– Os volumes persistem os dados entre reinicializações dos contêineres (dados do banco de dados, configuração do OpenClaw, logs)
Depuração de problemas de rede Docker
“`html
Quando algo não se conecta, aqui está minha sequência de depuração:
1. O contêiner pode acessar a internet? docker exec openclaw ping 8.8.8.8. Se não: problema de modo de rede ou problema de firewall.
2. O contêiner pode resolver DNS? docker exec openclaw nslookup api.openai.com. Se não: problema de configuração DNS.
3. O contêiner pode acessar o outro serviço? docker exec openclaw ping db. Se não: os contêineres não estão na mesma rede.
4. O contêiner pode acessar a porta do serviço? docker exec openclaw nc -z db 5432. Se não: o serviço não está escutando, ou está em uma porta diferente da esperada.
5. O serviço aceita conexões? Tente se conectar com a ferramenta cliente real (psql, curl) de dentro do contêiner. Se o ping funcionar, mas o aplicativo não funcionar, é um problema de autenticação ou configuração, não de rede.
Essa sequência elimina as possibilidades sistematicamente. A maioria dos problemas de rede é resolvida na etapa 3.
Considerações de desempenho
Docker adiciona uma fina camada de sobrecarga nas operações de rede. Para a maioria das cargas de trabalho do OpenClaw, isso é indetectável — a chamada da API AI leva 2 segundos, e a sobrecarga de rede do Docker está em microssegundos.
Onde isso é importante: se você estiver realizando operações pesadas em arquivos locais através de volumes Docker, o desempenho pode ser notavelmente mais lento no macOS (Docker Desktop usa uma VM, e as montagens de volumes passam pela camada da VM). No Linux, os volumes Docker nativos têm uma sobrecarga negligenciável.
Para a maioria dos usuários: a sobrecarga de rede do Docker não é uma razão para evitar a conteinerização. A isolação, reprodutibilidade e facilidade de implantação superam o custo marginal de desempenho.
“`
🕒 Published: