OpenClaw in Docker: 5 Proxy Config Fixes

You run curl -x http://proxy.example.com:8080 https://httpbin.org/ip on the host and it works. You run the same command inside the OpenClaw container and it works too. Then you start an OpenClaw task and it fails with a connection timeout.

That is the shape of this problem. The proxy is not broken. The container can reach the network. OpenClaw itself is usually fine. The failure is in the gap between how Docker, your proxy, and OpenClaw read their configuration.

This article maps that gap. It is written for developers who already have OpenClaw running in Docker and are tired of guessing why outbound requests still fail.

The Real Problem: Three Config Sources, One Container

OpenClaw inside a Docker container can inherit proxy settings from at least three places:

1. Environment variables passed to the container (HTTP_PROXY, HTTPS_PROXY, NO_PROXY).

2. OpenClaw's own config.yaml or Docker setup files.

3. Docker Desktop's global or enterprise proxy settings.

When two of these disagree, the container obeys the wrong one. The result looks like OpenClaw is ignoring the proxy, but what is actually happening is that one configuration layer is overriding another.

The safest rule is: pick one source of truth. For most deployments, that source should be environment variables.

Five Failure Modes

1. Environment Variables Never Reached the Container

This is the most common mistake. You export HTTP_PROXY on the host, then run docker compose up, and assume the variable is inherited. It is not.

Docker does not pass host environment variables into containers unless you explicitly map them. Use the environment block in your compose file or -e flags with docker run.

services:
  openclaw:
    image: openclaw/openclaw:latest
    environment:
      - HTTP_PROXY=http://proxy.example.com:8080
      - HTTPS_PROXY=http://proxy.example.com:8080
      - NO_PROXY=localhost,127.0.0.1

Verify inside the container:

docker exec openclaw env | grep -i proxy

If the variables are missing, OpenClaw has no proxy to use.

2. YAML Configuration Conflicts with Environment Variables

OpenClaw can read proxy settings from a config.yaml file. If that file contains proxy keys while you also pass HTTP_PROXY as an environment variable, the behavior depends on OpenClaw's precedence rules, and those rules are easy to misread.

The reliable fix is to choose one. If you use environment variables, comment out or remove proxy settings in config.yaml:

# config.yaml
# proxy:
#   http: http://proxy.example.com:8080
#   https: http://proxy.example.com:8080

Then pass the values through the environment. This removes the ambiguity entirely.

3. Docker Desktop Is Injecting Its Own Proxy

Starting with Docker Desktop 4.29.0, Docker Desktop can inject proxy settings into every container through a containersProxy configuration. On managed or enterprise installs this is enforced through admin-settings.json, and it overrides the proxy values you pass in your compose file.

If you see proxy variables inside the container that you did not set, or if OpenClaw uses a different proxy than the one you configured, check these three places in order:

1. Docker Desktop UI: Settings → Resources → Proxies

2. admin-settings.json: the enterprise policy file that locks proxy values

3. containersProxy in admin-settings.json: this forces a specific proxy URL into all containers

A typical forced configuration looks like this:

{
  "containersProxy": {
    "http": "http://proxy.example.com:8080",
    "https": "http://proxy.example.com:8080",
    "noProxy": "localhost,127.0.0.1"
  }
}

Docker Desktop may also distribute this through a PAC file. If your environment uses PAC, the container inherits the resolved proxy from the host. In that case the proxy address seen inside the container may not match what you typed into environment.

When Docker Desktop enforces a proxy, you have two practical options:

• Align OpenClaw with the forced proxy address.

• Ask the administrator to add OpenClaw's target hosts to noProxy.

You cannot override a locked containersProxy from inside the compose file.

4. Network Mode Is Wrong

Using --network host feels like a quick fix for networking problems, but for proxy workflows it usually makes things worse. The host network mode bypasses Docker's port mapping and DNS behavior, which means OpenClaw may try to reach the proxy through a path that does not exist inside the host namespace.

The default bridge network is the right choice for almost every OpenClaw deployment. It keeps DNS predictable, keeps port mapping explicit, and makes proxy routing consistent.

A recent OpenClaw security advisory also notes that network=host can expose the container to unnecessary risk. Stick with bridge unless you have a specific reason not to.

5. DNS Cannot Resolve the Proxy Hostname

If your proxy URL uses a hostname instead of an IP address, the container must be able to resolve that hostname. Corporate DNS or split-horizon setups often fail inside containers even when they work on the host.

Test from inside the container:

docker exec openclaw nslookup proxy.example.com

If resolution fails, switch to the proxy's IP address or add a custom DNS server in your compose file:

services:
  openclaw:
    dns:
      - 8.8.8.8
      - 1.1.1.1

A Minimal Working docker-compose

Here is a configuration that follows the three rules: environment variables only, bridge network, no conflicting YAML proxy settings. It also includes a healthcheck so Docker can restart the container if the dashboard stops responding.

version: "3.8"

services:
  openclaw:
    image: openclaw/openclaw:latest
    container_name: openclaw
    restart: unless-stopped
    ports:
      - "18789:18789"
    environment:
      - HTTP_PROXY=http://proxy.example.com:8080
      - HTTPS_PROXY=http://proxy.example.com:8080
      - NO_PROXY=localhost,127.0.0.1
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:18789/", "||", "exit", "1"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s
    volumes:
      - openclaw_data:/root/.openclaw
      - openclaw_cache:/root/.cache

volumes:
  openclaw_data:
  openclaw_cache:

Replace proxy.example.com:8080 with your actual proxy. If your proxy requires authentication, include the credentials in the URL:

http://username:password@proxy.example.com:8080

Special Case: The Proxy Runs on the Host

If your proxy is running on the same machine as Docker, you cannot use 127.0.0.1 from inside the container because that points to the container itself, not the host.

Use the host-gateway address instead:

Use the port your host proxy actually listens on. If your proxy runs on a different port, replace 8080 accordingly.

Five-Minute Troubleshooting Checklist

Run these commands in order before changing anything else:

1. Check environment variables inside the container

   docker exec openclaw env | grep -i proxy
   

2. Test proxy connectivity with curl

   docker exec openclaw curl -x http://proxy.example.com:8080 https://httpbin.org/ip
   

3. Check DNS resolution

   docker exec openclaw nslookup proxy.example.com

4. Look for conflicting YAML proxy settings

   docker exec openclaw cat /root/.openclaw/config.yaml | grep -i proxy

5. Confirm Docker Desktop is not overriding

   • Check Settings → Resources → Proxies.

   • On managed installs, check admin-settings.json for containersProxy.

   • Ask your administrator whether a PAC file is forcing a proxy.

If the first three pass and OpenClaw still fails, the conflict is almost certainly in steps 4 or 5.

Three Rules That Prevent Most Proxy Problems

1. Use environment variables, not YAML, for proxy configuration.

2. Use bridge networking and avoid network_mode: host.

3. Maintain one source of truth for proxy settings.

OpenClaw is not special here. It reads the same HTTP_PROXY variables as every other tool. The reason it seems to break more often is that Docker adds two extra layers of configuration, and those layers are easy to forget.