OpenClaw 502 Bad Gateway Error with Nginx/Caddy — How to Fix (2026)

Why You See 502 Bad Gateway

A 502 Bad Gateway error occurs when your reverse proxy (Nginx or Caddy) cannot get a valid response from the OpenClaw backend. This is the most common issue when self-hosting OpenClaw behind a reverse proxy.

Step-by-Step Diagnosis

1. Verify OpenClaw Is Running

# Check if OpenClaw process is alive
systemctl status openclaw
# Or check Docker
docker ps | grep openclaw

# Test direct connection (bypass proxy)
curl -v http://localhost:3000

2. Check Nginx Configuration

A correct Nginx config for OpenClaw looks like this:

server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # Important: increase timeouts for long-running AI requests
        proxy_read_timeout 300s;
        proxy_connect_timeout 60s;
        proxy_send_timeout 300s;
    }
}

3. Caddy Configuration (Alternative)

your-domain.com {
    reverse_proxy localhost:3000 {
        header_up X-Real-IP {remote_host}
        header_up X-Forwarded-Proto {scheme}
        transport http {
            read_timeout 300s
        }
    }
}

4. Common Mistakes to Avoid

Using http://localhost instead of http://127.0.0.1 (IPv6 issues)
Missing WebSocket upgrade headers
Firewall blocking localhost connections (SELinux on RHEL/CentOS)
Proxy timeouts too short for AI model responses
Wrong port number in upstream

5. Fix SELinux (CentOS/RHEL)

# Allow Nginx to connect to network services
setsebool -P httpd_can_network_connect 1

Frequently Asked Questions

What causes a 502 Bad Gateway with OpenClaw?

A 502 error means Nginx/Caddy received an invalid response from OpenClaw. Common causes: OpenClaw is not running, wrong upstream port, firewall blocking localhost connections, or OpenClaw crashed during the request.

How do I check if OpenClaw is running behind the proxy?

SSH into your server and run "curl http://localhost:3000" (or whatever port OpenClaw is on). If this returns a response, OpenClaw is running and the issue is in your proxy config. If it fails, OpenClaw is down.

Do I need WebSocket support for OpenClaw?

Yes, if you use real-time features like chat or live updates, your reverse proxy must support WebSocket upgrades. Add the Upgrade and Connection headers in your Nginx config.

Should I use Nginx or Caddy for OpenClaw?

Caddy is easier for beginners since it handles TLS automatically. Nginx offers more control and is better for high-traffic deployments. Both work well with OpenClaw.

Why do I get 504 Gateway Timeout instead of 502?

A 504 means Nginx/Caddy waited too long for a response from OpenClaw. AI model requests can take 30-60 seconds. Increase your proxy_read_timeout to at least 300 seconds to accommodate long-running AI generation requests.