How to Fix OpenClaw 502 Bad Gateway Errors
A 502 Bad Gateway error means your reverse proxy (nginx, Caddy, Apache) can't communicate with the upstream OpenClaw service. This might be because OpenClaw crashed, is listening on the wrong port, the proxy configuration has errors, or timeouts are too aggressive for long LLM responses. This guide walks through each failure point.
Why This Is Hard to Do Yourself
These are the common pitfalls that trip people up.
Upstream timeout on long requests
LLM responses take 30+ seconds, proxy times out before completion
Misconfigured proxy settings
Wrong upstream port, incorrect headers, or missing websocket support
Upstream process crashed
OpenClaw isn't running but proxy expects it to be available
Port mismatch between proxy and app
Proxy forwards to :3000 but OpenClaw listens on :8080
Step-by-Step Guide
Verify OpenClaw process is running
Ensure the upstream service actually exists and is accepting connections.
# Check if OpenClaw is running:
systemctl status openclaw
ps aux | grep openclaw
# Test direct access (bypassing proxy):
curl http://localhost:3000/health
# If this fails, OpenClaw isn't running
# If this works, the problem is in the proxy configConfirm port configuration matches
Verify the proxy forwards to the port OpenClaw is actually listening on.
# Check which port OpenClaw is using:
netstat -tuln | grep LISTEN | grep openclaw
# Or:
lsof -i -P | grep openclaw
# Note the port (e.g., :3000)
# Check nginx config:
sudo nano /etc/nginx/sites-available/openclaw
# Verify this line matches OpenClaw port:
proxy_pass http://localhost:3000;
# Check Caddy config:
sudo nano /etc/caddy/Caddyfile
# Verify:
reverse_proxy localhost:3000Review proxy error logs
Examine nginx or Caddy logs to see the specific upstream error.
# Nginx error log:
sudo tail -f /var/log/nginx/error.log
# Look for:
# - "Connection refused" (wrong port or process down)
# - "upstream timed out" (timeout too short)
# - "no live upstreams" (all backends dead)
# Caddy error log:
sudo journalctl -u caddy -f --no-pager
# Apache error log:
sudo tail -f /var/log/apache2/error.logIncrease proxy timeout limits
Extend timeouts to accommodate slow LLM responses and long-running skills.
# For nginx, edit site config:
sudo nano /etc/nginx/sites-available/openclaw
# Add these to location block:
proxy_read_timeout 300s;
proxy_connect_timeout 75s;
proxy_send_timeout 300s;
# For Caddy, add to reverse_proxy directive:
reverse_proxy localhost:3000 {
transport http {
read_timeout 300s
write_timeout 300s
}
}
# Reload config:
sudo systemctl reload nginx
# or:
sudo systemctl reload caddyCheck SSL termination configuration
Ensure proxy properly handles HTTPS and forwards correct protocol headers.
# Nginx SSL proxy config should include:
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;
# For websockets (if OpenClaw uses them):
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
# Verify SSL cert is valid:
sudo certbot certificates
# Renew if expired:
sudo certbot renewTest bypassing the proxy
Access OpenClaw directly to isolate whether the issue is proxy or application.
# SSH tunnel to access OpenClaw directly:
ssh -L 3000:localhost:3000 user@your-server.com
# Then browse to http://localhost:3000
# Or temporarily allow direct access:
sudo ufw allow 3000/tcp
curl http://your-server-ip:3000/health
# If direct access works:
# - Problem is proxy config
# If direct access fails:
# - Problem is OpenClaw itself (see not-responding guide)
# Close firewall after testing:
sudo ufw delete allow 3000/tcpTired of 502 Errors?
Our reverse proxy experts configure nginx, Caddy, or Apache for optimal OpenClaw performance. Get SSL, websockets, load balancing, and health checks configured correctly the first time.
Get matched with a specialist who can help.
Sign Up for Expert Help →