Il networking di Docker è il motivo per cui ho quasi abbandonato la mia configurazione containerizzata di OpenClaw. Tutto funzionava localmente: l’agente poteva raggiungere il database, connettersi all’API, servire webhooks. Poi l’ho messo in Docker e niente riusciva a comunicare con nulla.
Se hai mai fissato un errore di “connessione rifiutata” all’interno di un container Docker e pensato “ma funziona sull’host,” questo articolo è per te. Ho commesso ogni possibile errore di networking con Docker così non dovrai farlo tu.
L’Errore Che Mi Ha Causato Problemi
La mia configurazione di OpenClaw aveva la connessione al database impostata su localhost:5432. Sulla macchina host, questo funzionava perfettamente: PostgreSQL stava ascoltando su localhost. All’interno del container Docker, localhost si riferisce al container stesso, non all’host. PostgreSQL non è in esecuzione all’interno del container, quindi la connessione fallisce.
Questo è il 101 del Networking Docker, eppure ci sono cascato. La soluzione: utilizzare host.docker.internal (su Docker Desktop) o l’indirizzo IP effettivo dell’host anziché localhost.
I Comuni Tranelli
Tranello 1: Comunicazione tra container. Se OpenClaw e PostgreSQL sono in container separati, non possono comunicare tra loro a meno che non siano sulla stessa rete Docker. La rete bridge predefinita fornisce isolamento: ottimo per la sicurezza, terribile quando hai effettivamente bisogno che i servizi comunichino.
Soluzione: crea una rete bridge definita dall’utente e collega entrambi i container ad essa. I container sulla stessa rete definita dall’utente possono raggiungersi usando il nome del container. Quindi OpenClaw si connette a postgres:5432 invece di localhost:5432.
Tranello 2: Confusione con il mapping delle porte. Hai mappato la porta 3000 nel container alla porta 8080 sull’host con -p 8080:3000. Dall’esterno del container, accedi a essa sulla porta 8080. All’interno di un altro container sulla stessa rete, accedi a essa sulla porta 3000. Queste sono diverse e confonderle provoca errori di “connessione rifiutata” che sono sconcertanti finché non capisci il mapping.
Tranello 3: Risoluzione DNS all’interno dei container. I container utilizzano il DNS interno di Docker per impostazione predefinita. Se la tua configurazione di OpenClaw fa riferimento a un servizio esterno tramite nome host, assicurati che la risoluzione DNS funzioni all’interno del container. Ho avuto container che potevano raggiungere 8.8.8.8 (l’IP funziona) ma non api.openai.com (il DNS fallisce). Soluzione: imposta esplicitamente i server DNS nel comando di esecuzione di Docker o nel file docker-compose.
Tranello 4: Ingress webhook. Il tuo endpoint webhook funziona sull’host a http://localhost:3000/webhook. I servizi esterni non possono raggiungere localhost — quello è il tuo computer, non internet. Devi o esporre un URL pubblico (tramite port forwarding, un reverse proxy o un servizio tunnel) o usare un servizio di relay webhook.
Tranello 5: Perdita di variabili d’ambiente. Docker passa esplicitamente le variabili d’ambiente ai container. Se la tua configurazione di OpenClaw si basa su variabili d’ambiente della shell (chiavi API, percorsi), queste non esistono automaticamente all’interno del container. Devi passarle con i flag -e o un file env.
La Mia Configurazione Docker Compose
Dopo aver combattuto con il networking 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 sulla rete bridge personalizzata chiamata agent-net.
Decisioni chiave:
– OpenClaw si connette al database usando il nome del servizio db come nome host
– Caddy gestisce la terminazione SSL e instrada il traffico webhook esterno a OpenClaw
– Solo Caddy espone porte all’host (80 e 443)
– Le chiavi API vengono caricate da un file env, non hardcoded
– I volumi persistono i dati attraverso i riavvii del container (dati del database, configurazione di OpenClaw, log)
Debugging dei Problemi di Rete Docker
Quando qualcosa non si connette, ecco la mia sequenza di debugging:
1. Il container può raggiungere internet? docker exec openclaw ping 8.8.8.8. Se no: problema di modalità rete o problema di firewall.
2. Il container può risolvere DNS? docker exec openclaw nslookup api.openai.com. Se no: problema di configurazione DNS.
3. Il container può raggiungere l’altro servizio? docker exec openclaw ping db. Se no: i container non sono sulla stessa rete.
4. Il container può raggiungere la porta del servizio? docker exec openclaw nc -z db 5432. Se no: il servizio non sta ascoltando, o è su una porta diversa da quella attesa.
5. Il servizio sta accettando connessioni? Prova a collegarti con l’effettivo strumento client (psql, curl) dall’interno del container. Se il ping funziona ma l’applicazione no, è un problema di autenticazione o di configurazione, non di networking.
Questa sequenza elimina sistematicamente le possibilità. La maggior parte dei problemi di networking viene risolta al passo 3.
Considerazioni sulle Prestazioni
Docker aggiunge un sottile strato di overhead alle operazioni di rete. Per la maggior parte dei carichi di lavoro di OpenClaw, questo è impercettibile: la chiamata all’API AI richiede 2 secondi, e l’overhead di rete di Docker è misurabile in microsecondi.
Dove è rilevante: se stai effettuando operazioni di I/O su file locali pesanti attraverso i volumi Docker, le prestazioni possono essere notevolmente più lente su macOS (Docker Desktop utilizza una VM e i mount dei volumi passano attraverso il livello della VM). Su Linux, i volumi Docker nativi hanno un overhead trascurabile.
Per la maggior parte degli utenti: l’overhead di networking di Docker non è un motivo per evitare la containerizzazione. L’isolamento, la riproducibilità e la facilità di distribuzione superano di gran lunga il costo prestazionale marginale.
🕒 Published: