Docker networking is the reason I almost abandoned my containerized OpenClaw setup. Everything worked locally — the agent could reach the database, connect to the API, serve webhooks. Then I put it in Docker and nothing could talk to anything.
If you’ve ever stared at a “connection refused” error from inside a Docker container and thought “but it works on the host,” this article is for you. I made every Docker networking mistake possible so you don’t have to.
The Mistake That Got Me
My OpenClaw config had the database connection set to localhost:5432. On the host machine, this worked perfectly — PostgreSQL was listening on localhost. Inside the Docker container, localhost refers to the container itself, not the host. PostgreSQL isn’t running inside the container, so the connection fails.
This is Docker Networking 101, and I still fell for it. The fix: use host.docker.internal (on Docker Desktop) or the host’s actual IP address instead of localhost.
The Common Pitfalls
Pitfall 1: Container-to-container communication. If OpenClaw and PostgreSQL are in separate containers, they can’t talk to each other unless they’re on the same Docker network. The default bridge network provides isolation — great for security, terrible when you actually need services to communicate.
Fix: create a user-defined bridge network and attach both containers to it. Containers on the same user-defined network can reach each other by container name. So OpenClaw connects to postgres:5432 instead of localhost:5432.
Pitfall 2: Port mapping confusion. You mapped port 3000 in the container to port 8080 on the host with -p 8080:3000. From outside the container, you access it at port 8080. From inside another container on the same network, you access it at port 3000. These are different and mixing them up causes “connection refused” errors that are mystifying until you understand the mapping.
Pitfall 3: DNS resolution inside containers. Containers use Docker’s internal DNS by default. If your OpenClaw config references an external service by hostname, make sure DNS resolution works inside the container. I’ve had containers that could reach 8.8.8.8 (IP works) but not api.openai.com (DNS fails). Fix: explicitly set DNS servers in the Docker run command or docker-compose file.
Pitfall 4: Webhook ingress. Your webhook endpoint works on the host at http://localhost:3000/webhook. External services can’t reach localhost — that’s your machine, not the internet. You need to either expose a public URL (through port forwarding, a reverse proxy, or a tunnel service) or use a webhook relay service.
Pitfall 5: Environment variable leakage. Docker passes environment variables to containers explicitly. If your OpenClaw config relies on shell environment variables (API keys, paths), those don’t automatically exist inside the container. You need to pass them with -e flags or an env file.
My Docker Compose Setup
After fighting with networking for a week, I settled on a docker-compose setup that handles all the pitfalls:
The compose file defines three services: OpenClaw, PostgreSQL, and a reverse proxy (Caddy). All three are on a custom bridge network called agent-net.
Key decisions:
– OpenClaw connects to the database using the service name db as the hostname
– Caddy handles SSL termination and routes external webhook traffic to OpenClaw
– Only Caddy exposes ports to the host (80 and 443)
– API keys are loaded from an env file, not hardcoded
– Volumes persist data across container restarts (database data, OpenClaw config, logs)
Debugging Docker Network Issues
When something doesn’t connect, here’s my debugging sequence:
1. Can the container reach the internet? docker exec openclaw ping 8.8.8.8. If no: network mode problem or firewall issue.
2. Can the container resolve DNS? docker exec openclaw nslookup api.openai.com. If no: DNS configuration issue.
3. Can the container reach the other service? docker exec openclaw ping db. If no: containers aren’t on the same network.
4. Can the container reach the service’s port? docker exec openclaw nc -z db 5432. If no: the service isn’t listening, or it’s on a different port than expected.
5. Is the service accepting connections? Try connecting with the actual client tool (psql, curl) from inside the container. If the ping works but the application doesn’t, it’s an authentication or configuration issue, not networking.
This sequence eliminates possibilities systematically. Most networking issues are resolved by step 3.
Performance Considerations
Docker adds a thin layer of overhead to network operations. For most OpenClaw workloads, this is undetectable — the AI API call takes 2 seconds, and Docker’s network overhead is microseconds.
Where it matters: if you’re doing heavy local file I/O through Docker volumes, the performance can be notably slower on macOS (Docker Desktop uses a VM, and volume mounts pass through the VM layer). On Linux, native Docker volumes have negligible overhead.
For most users: Docker’s networking overhead is not a reason to avoid containerization. The isolation, reproducibility, and ease of deployment benefits outweigh the marginal performance cost.
🕒 Last updated: · Originally published: January 16, 2026