How do I set a proxy for OpenClaw running in Docker?

Pass HTTP_PROXY, HTTPS_PROXY, and NO_PROXY as environment variables using docker run -e flags. For example: docker run -d -e HTTPS_PROXY=http://proxy.example.com:8080 -e NO_PROXY=localhost,127.0.0.1 ghcr.io/openclaw/openclaw:latest node openclaw.mjs gateway --allow-unconfigured. For SOCKS5 proxies use ALL_PROXY=socks5://proxy.example.com:1080.

Why does my proxy work on the host but not inside the OpenClaw container?

Docker containers have their own network namespace. A proxy running on the host at 127.0.0.1 is not reachable from inside a container using that address. On macOS and Windows use host.docker.internal instead. On Linux either use the host LAN IP or add --add-host=host.docker.internal:host-gateway to your docker run command.

How do I configure a global proxy for all Docker containers?

Edit /etc/docker/daemon.json to add a "proxies" block with "http-proxy", "https-proxy", and "no-proxy" keys, then run sudo systemctl restart docker. This applies the proxy to every container on the host automatically, so use it only if all containers should go through the same proxy.

I get a TLS certificate error when using a corporate proxy with OpenClaw. How do I fix it?

Corporate proxies often perform TLS inspection and replace the server certificate with one signed by their own CA. Node.js rejects these by default. The proper fix is to add the corporate CA certificate to the container trust store. As a temporary development-only workaround you can set NODE_TLS_REJECT_UNAUTHORIZED=0, but never use this in production as it disables all TLS certificate validation.

← Home

Network Setup

OpenClaw Proxy Setup — HTTP, HTTPS & SOCKS5 Configuration Guide

Running OpenClaw inside a corporate network, behind an egress firewall, or from a region with restricted API access? This guide covers every supported proxy method — environment variables, Docker run flags, Compose files, the Docker daemon global proxy, and SOCKS5 — plus the most common pitfalls.

Why You Might Need a Proxy

OpenClaw makes outbound HTTPS calls to AI model APIs (OpenAI, Anthropic, Google, OpenRouter, and others) and to ClawHub for skill downloads. There are three common reasons those calls need to go through a proxy:

Corporate or university networks that block direct internet egress and require all traffic to leave through an approved HTTP/HTTPS forward proxy.
Region-restricted API access where certain endpoints are unavailable from your hosting location and you route through a proxy in a permitted region.
Egress control and auditing setups where your security team wants all outbound traffic logged and filtered through a central gateway.

If none of those apply to you, skip to the Managed Hosting Alternative section — the easiest option is to let OpenClaw Launch host your agent on servers that already have unrestricted internet access, so you never touch proxy config at all.

How OpenClaw Reads Proxy Settings

OpenClaw runs as a Node.js process inside a Docker container. Node.js respects the standard POSIX proxy environment variables at startup. Set them before the process starts and every outbound HTTP/HTTPS request will automatically be tunneled through your proxy — no code changes required.

The four variables OpenClaw recognises are:

HTTP_PROXY — proxy for plain HTTP requests (rarely needed since all AI APIs use HTTPS, but used by some package managers during skill install).
HTTPS_PROXY — proxy for HTTPS requests. This is the critical one for API calls to OpenAI, Anthropic, Google, and ClawHub.
ALL_PROXY — fallback proxy for any protocol not covered by the above two. Required when using a SOCKS5 proxy.
NO_PROXY — comma-separated list of hosts or CIDRs that bypass the proxy entirely. Always include localhost,127.0.0.1 to prevent internal health-check traffic from going through the proxy.

Method 1: docker run -e (Recommended)

Pass proxy variables directly to the container at launch time using the -e flag. This is the most explicit and portable approach:

docker run -d \
  -e HTTP_PROXY=http://proxy.example.com:8080 \
  -e HTTPS_PROXY=http://proxy.example.com:8080 \
  -e NO_PROXY=localhost,127.0.0.1 \
  -v ~/.openclaw:/home/node/.openclaw \
  -p 18789:18789 \
  ghcr.io/openclaw/openclaw:latest \
  node openclaw.mjs gateway --allow-unconfigured

Replace proxy.example.com:8080 with your actual proxy host and port. If your proxy requires authentication, embed credentials in the URL:

-e HTTPS_PROXY=http://username:[email protected]:8080

Avoid committing credentials into shell scripts or Compose files. Pass them via environment files or secrets management instead.

Method 2: docker-compose environment Block

If you manage OpenClaw with a Compose file, add the proxy variables under the environment key:

version: '3'
services:
  openclaw:
    image: ghcr.io/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
    volumes:
      - ./openclaw-data:/home/node/.openclaw
    ports:
      - "18789:18789"
    command: node openclaw.mjs gateway --allow-unconfigured

You can also use an env_file to keep proxy credentials out of the Compose file itself:

services:
  openclaw:
    image: ghcr.io/openclaw/openclaw:latest
    env_file:
      - proxy.env
    ...

Where proxy.env contains the variable assignments one per line and is excluded from version control via .gitignore.

Method 3: Docker Daemon Global Proxy (daemon.json)

If you want every container on the host to inherit the proxy automatically — useful on a single-purpose proxy machine — configure the Docker daemon itself. Edit or create /etc/docker/daemon.json:

{
  "proxies": {
    "http-proxy": "http://proxy.example.com:8080",
    "https-proxy": "http://proxy.example.com:8080",
    "no-proxy": "localhost,127.0.0.1"
  }
}

Then restart the Docker daemon for the change to take effect:

sudo systemctl restart docker

Note that this affects every container on the host, including ones that should not go through a proxy. Prefer per-container -e flags when you need selective routing.

Method 4: SOCKS5 via ALL_PROXY

If your organisation uses a SOCKS5 proxy (common with SSH tunnels and corporate gateways), set ALL_PROXY with the socks5:// scheme. Because Node.js does not natively tunnel HTTPS over SOCKS5 viaHTTPS_PROXY alone, you must also set HTTP_PROXY andHTTPS_PROXY to the same SOCKS5 URL so that proxy-aware libraries pick it up:

docker run -d \
  -e ALL_PROXY=socks5://proxy.example.com:1080 \
  -e HTTP_PROXY=socks5://proxy.example.com:1080 \
  -e HTTPS_PROXY=socks5://proxy.example.com:1080 \
  -e NO_PROXY=localhost,127.0.0.1 \
  -v ~/.openclaw:/home/node/.openclaw \
  -p 18789:18789 \
  ghcr.io/openclaw/openclaw:latest \
  node openclaw.mjs gateway --allow-unconfigured

If you need SOCKS5 with a username and password, encode them in the URL:

ALL_PROXY=socks5://username:[email protected]:1080

The host.docker.internal Gotcha

A very common setup is running a local proxy client (like Clash, sing-box, or Squid) on the Docker host at 127.0.0.1:7890, then expecting containers to use it. This does not work with 127.0.0.1 inside a container because loopback addresses resolve to the container itself, not the host.

The fix depends on your platform:

macOS and Windows: Docker Desktop provides the magic hostname host.docker.internal that resolves to the host machine. Use http://host.docker.internal:7890 as your proxy URL.
Linux: host.docker.internal is not available by default. Use the host's LAN IP address (e.g. 192.168.1.100) or add --add-host=host.docker.internal:host-gateway to your docker run command to enable the hostname.

# Linux: enable host.docker.internal + use it for a host-side proxy
docker run -d \
  --add-host=host.docker.internal:host-gateway \
  -e HTTPS_PROXY=http://host.docker.internal:7890 \
  -e NO_PROXY=localhost,127.0.0.1 \
  -v ~/.openclaw:/home/node/.openclaw \
  -p 18789:18789 \
  ghcr.io/openclaw/openclaw:latest \
  node openclaw.mjs gateway --allow-unconfigured

DNS Leaks and TLS MITM

DNS Leaks

When you route HTTP/HTTPS traffic through a proxy, DNS resolution can still happen inside the container using the host's default resolver. On some networks the DNS resolver is poisoned or filtered, causing lookups for api.openai.com or similar to fail before the proxy even receives the connection. The fix is to configure your proxy to resolve DNS remotely (most SOCKS5 clients support this) or to set a reliable public DNS server in your Docker daemon or container network config.

TLS MITM (Corporate Certificate Inspection)

Some corporate proxies perform TLS inspection: they terminate the HTTPS connection, re-sign it with their own CA certificate, and forward the decrypted traffic. OpenClaw (and Node.js in general) will reject these re-signed certificates with an error like UNABLE_TO_VERIFY_LEAF_SIGNATURE or SELF_SIGNED_CERT_IN_CHAIN.

The proper fix is to add your corporate CA certificate to the container's trust store. As a temporary workaround during development only, you can disable TLS verification with NODE_TLS_REJECT_UNAUTHORIZED=0. Never set this in production — it removes all certificate validation and makes your agent vulnerable to real man-in-the-middle attacks.

# Development only — disables TLS certificate verification
docker run -d \
  -e HTTPS_PROXY=http://proxy.example.com:8080 \
  -e NODE_TLS_REJECT_UNAUTHORIZED=0 \
  ...

Verifying the Proxy Works

After starting the container, run a quick curl check from inside it to confirm outbound HTTPS is flowing through the proxy:

# Get the container ID
docker ps | grep openclaw

# Run curl inside the container to test connectivity
docker exec <container-id> curl -v https://api.openai.com/v1/models \
  -H "Authorization: Bearer sk-test" 2>&1 | head -30

If the proxy is working you will see the TLS handshake succeed (even if the API key is invalid, you will get a 401 response rather than a connection error). If the proxy is not working you will see ECONNREFUSED, ETIMEDOUT, or a TLS certificate error.

You can also check that OpenClaw itself is picking up the proxy variable:

docker exec <container-id> node -e "console.log(process.env.HTTPS_PROXY)"

Managed Hosting Alternative: No Proxy Needed

Configuring proxies, handling TLS certificate quirks, and maintaining host-side proxy clients is engineering overhead. If your goal is running OpenClaw reliably without network restrictions, OpenClaw Launch is the no-config alternative.

OpenClaw Launch deploys your agent as a managed Docker instance on servers in Europe and the US. Those servers have unrestricted internet access to all major AI APIs — OpenAI, Anthropic, Google, OpenRouter, DeepSeek, and others — with no proxy configuration required. You configure your model and skills in a browser UI, click deploy, and the agent is live in under a minute.

No proxy setup, no certificate issues, no egress firewall rules to manage.
Servers abroad with direct connectivity to all major AI API endpoints.
Managed Docker lifecycle: start, stop, restart, logs, all from the dashboard.
Supports Telegram, Discord, and web chat out of the box.