La rete Docker è il motivo per cui ho quasi abbandonato la mia configurazione OpenClaw containerizzata. Tutto funzionava localmente: l’agente poteva raggiungere il database, connettersi all’API, servire webhook. Poi l’ho messo in Docker e niente poteva comunicare.
Se hai mai visto un errore “connessione rifiutata” dall’interno di un contenitore Docker e pensato “ma funziona sull’host”, questo articolo è per te. Ho commesso tutti gli errori possibili riguardo alla rete Docker affinché tu non debba farlo.
L’errore che mi ha intrappolato
La mia configurazione OpenClaw aveva la connessione al database impostata su localhost:5432. Sulla macchina host, funzionava perfettamente: PostgreSQL ascoltava su localhost. All’interno del contenitore Docker, localhost si riferisce al contenitore stesso, non all’host. PostgreSQL non gira all’interno del contenitore, quindi la connessione fallisce.
Questo è il Docker networking 101, eppure ci sono caduto. La soluzione: usa host.docker.internal (su Docker Desktop) o l’indirizzo IP reale dell’host invece di localhost.
I tranelli comuni
Tranello 1: comunicazione tra contenitori. Se OpenClaw e PostgreSQL sono in contenitori separati, non possono comunicare a meno che non siano sulla stessa rete Docker. La rete predefinita “bridge” offre isolamento — ottimo per la sicurezza, terribile quando hai realmente bisogno che i servizi comunichino.
Soluzione: crea una rete “bridge” definita dall’utente e collega entrambi i contenitori. I contenitori sulla stessa rete definita dall’utente possono comunicare usando il nome del contenitore. Così, OpenClaw si connette a postgres:5432 invece di localhost:5432.
Tranello 2: confusione sul mapping delle porte. Hai mappato la porta 3000 nel contenitore alla porta 8080 sull’host con -p 8080:3000. Dall’esterno del contenitore, accedi tramite la porta 8080. Dall’interno di un altro contenitore sulla stessa rete, accedi tramite la porta 3000. Queste sono due cose diverse e confonderle causa errori di “connessione rifiutata” che sono deraglianti finché non comprendi il mapping.
Tranello 3: risoluzione DNS all’interno dei contenitori. I contenitori utilizzano per default il DNS interno di Docker. Se la tua configurazione OpenClaw fa riferimento a un servizio esterno con il suo nome host, assicurati che la risoluzione DNS funzioni all’interno del contenitore. Ho avuto contenitori in grado di raggiungere 8.8.8.8 (l’IP funziona) ma non api.openai.com (la risoluzione DNS fallisce). Soluzione: definisci esplicitamente i server DNS nel comando Docker run o nel file docker-compose.
Tranello 4: ingress del webhook. Il tuo endpoint del webhook funziona sull’host a http://localhost:3000/webhook. I servizi esterni non possono raggiungere localhost — questa è la tua macchina, non internet. Devi o esporre un’URL pubblica (tramite port forwarding, un reverse proxy o un servizio di tunnel), o usare un servizio di relay per webhook.
Tranello 5: esposizione di variabili d’ambiente. Docker passa esplicitamente le variabili d’ambiente ai contenitori. Se la tua configurazione OpenClaw dipende da variabili d’ambiente shell (chiavi API, percorsi), queste non esistono automaticamente all’interno del contenitore. Devi passarle usando i flag -e o un file env.
La mia configurazione Docker Compose
Dopo aver lottato con la rete per una settimana, ho scelto una configurazione docker-compose che gestisce tutti i tranelli:
Il file compose definisce tre servizi: OpenClaw, PostgreSQL e un reverse proxy (Caddy). Tutti e tre sono su una rete “bridge” personalizzata chiamata agent-net.
Decisioni chiave:
– OpenClaw si connette al database utilizzando il nome di servizio db come nome host
– Caddy gestisce la terminazione SSL e indirizza il traffico webhook esterno verso OpenClaw
– Solo Caddy espone porte all’host (80 e 443)
– Le chiavi API sono caricate da un file env, non hardcoded
– I volumi persistono i dati attraverso i riavvii dei contenitori (dati del database, configurazione OpenClaw, log)
Debugging dei problemi di rete Docker
Quando qualcosa non si connette, ecco la mia sequenza di debugging:
1. Il contenitore può raggiungere internet? docker exec openclaw ping 8.8.8.8. Se no: problema di modalità rete o problema di firewall.
2. Il contenitore può risolvere DNS? docker exec openclaw nslookup api.openai.com. Se no: problema di configurazione DNS.
3. Il contenitore può raggiungere l’altro servizio? docker exec openclaw ping db. Se no: i contenitori non sono sulla stessa rete.
4. Il contenitore può raggiungere la porta del servizio? docker exec openclaw nc -z db 5432. Se no: il servizio non ascolta, o è su una porta diversa da quella attesa.
5. Il servizio accetta connessioni? Prova a connetterti con il reale strumento client (psql, curl) dall’interno del contenitore. Se il ping funziona ma l’applicazione non funziona, è un problema di autenticazione o configurazione, non di rete.
Questa sequenza elimina le possibilità in modo sistematico. La maggior parte dei problemi di rete vengono risolti al passo 3.
Considerazioni sulle performance
Docker aggiunge un sottile strato di sovraccarico alle operazioni di rete. Per la maggior parte dei carichi di lavoro OpenClaw, è impercettibile: la chiamata API AI impiega 2 secondi, e il sovraccarico di rete di Docker è in microsecondi.
Dove è importante: se stai effettuando pesanti operazioni su file locali tramite volumi Docker, la performance può essere notevolmente più lenta su macOS (Docker Desktop utilizza una VM, e i montaggi di volumi passano attraverso il layer VM). Su Linux, i volumi Docker nativi hanno un sovraccarico trascurabile.
Per la maggior parte degli utenti: il sovraccarico di rete di Docker non è un motivo per evitare la containerizzazione. L’isolamento, la riproducibilità e la facilità di distribuzione superano il costo marginale di performance.
🕒 Published: