A rede do Docker é a razão pela qual quase abandonei minha configuração containerizada do OpenClaw. Tudo funcionava localmente — o agente conseguia acessar o banco de dados, conectar à API, servir webhooks. Então coloquei na Docker e nada conseguia se comunicar.
Se você já encarou um erro de “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 de rede no Docker para que você não precise.
O Erro Que Me Pegou
Minha configuração do OpenClaw tinha a conexão do banco de dados definida como localhost:5432. No host, isso funcionava perfeitamente — o PostgreSQL estava ouvindo em localhost. Dentro do contêiner Docker, localhost refere-se ao próprio contêiner, e não ao host. O PostgreSQL não está rodando dentro do contêiner, então a conexão falha.
Isso é o básico da Rede do Docker, e eu ainda caí nessa. A solução: use host.docker.internal (no Docker Desktop) ou o endereço IP real do host em vez de localhost.
Os Erros Comuns
Erro 1: Comunicação entre contêineres. Se o OpenClaw e o PostgreSQL estão em contêineres separados, eles não conseguem se comunicar a menos que estejam na mesma rede Docker. A rede bridge padrão oferece isolamento — ótima para segurança, péssima quando você realmente precisa que os serviços se comuniquem.
Solução: crie uma rede bridge definida pelo usuário e anexe ambos os contêineres a ela. Contêineres na mesma rede definida pelo usuário podem se acessar pelo nome do contêiner. Assim, o OpenClaw se conecta a postgres:5432 em vez de localhost:5432.
Erro 2: Confusão de mapeamento de porta. Você mapeou a porta 3000 no contêiner para a porta 8080 no host com -p 8080:3000. De fora do contêiner, você a acessa na porta 8080. De dentro de outro contêiner na mesma rede, você a acessa na porta 3000. Essas são diferentes e confundi-las causa erros de “conexão recusada” que são desconcertantes até você entender o mapeamento.
Erro 3: Resolução de DNS dentro dos contêineres. Os contêineres usam o DNS interno do Docker por padrão. Se sua configuração do OpenClaw referencia um serviço externo pelo nome do host, certifique-se de que a resolução DNS funcione dentro do contêiner. Já tive contêineres que conseguiam acessar 8.8.8.8 (o IP funciona), mas não api.openai.com (DNS falha). Solução: defina explicitamente os servidores DNS no comando de execução do Docker ou no arquivo docker-compose.
Erro 4: Ingress de webhook. Seu endpoint de webhook funciona no host em http://localhost:3000/webhook. Serviços externos não conseguem acessar localhost — esse é o seu computador, não a internet. Você precisa либо expor uma URL pública (por meio de encaminhamento de porta, um proxy reverso ou um serviço de túnel) ou usar um serviço de retransmissão de webhook.
Erro 5: Vazamento de variáveis de ambiente. O Docker passa variáveis de ambiente para os contêineres explicitamente. Se sua configuração do OpenClaw depende de variáveis de ambiente do shell (chaves de API, caminhos), elas não existem automaticamente dentro do contêiner. Você precisa passá-las com flags -e ou um arquivo env.
Minha Configuração do Docker Compose
Depois de uma semana lutando com a rede, decidi por uma configuração docker-compose que lida com todas as armadilhas:
O arquivo de composição define três serviços: OpenClaw, PostgreSQL e um proxy reverso (Caddy). Todos 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 do serviço db como hostname
– Caddy lida com a terminação SSL e roteia o tráfego de webhook externo para o OpenClaw
– Apenas Caddy expõe portas para o host (80 e 443)
– As chaves da API são carregadas de um arquivo env, não codificadas
– Volumes persistem dados entre as reinicializações dos contêineres (dados do banco de dados, configuração do OpenClaw, logs)
Depurando Problemas de Rede no Docker
Quando algo não se conecta, aqui está a 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 com o modo de rede ou problema de firewall.
2. O contêiner consegue resolver DNS? docker exec openclaw nslookup api.openai.com. Se não: problema de configuração de 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á ouvindo, ou está em uma porta diferente da esperada.
5. O serviço está aceitando conexões? Tente conectar com a ferramenta de cliente real (psql, curl) de dentro do contêiner. Se o ping funciona, mas a aplicação não, é um problema de autenticação ou configuração, não de rede.
Essa sequência elimina possibilidades de forma sistemática. A maioria dos problemas de rede é resolvida na etapa 3.
Considerações de Desempenho
O Docker adiciona uma camada fina de sobrecarga nas operações de rede. Para a maioria das cargas de trabalho do OpenClaw, isso é indetectável — a chamada da API da IA leva 2 segundos, e a sobrecarga de rede do Docker é de microssegundos.
Onde isso importa: se você está fazendo operações intensivas de leitura/gravação de arquivos locais através de volumes do Docker, o desempenho pode ser notavelmente mais lento no macOS (Docker Desktop utiliza uma VM, e as montagens de volumes passam pela camada da VM). No Linux, volumes nativos do Docker têm sobrecarga negligenciável.
Para a maioria dos usuários: a sobrecarga de rede do Docker não é um motivo para evitar a contêinerização. Os benefícios de isolamento, reprodutibilidade e facilidade de implantação superam o custo marginal de desempenho.
🕒 Published: