How to Fix OpenClaw Disconnected from Gateway: Complete Troubleshooting Guide
How to Fix OpenClaw Disconnected from Gateway: Complete Troubleshooting Guide
Getting a "disconnected from gateway" error when trying to access your OpenClaw instance can be frustrating. You've set everything up, your server is running, but the web interface just won't connect. This error typically appears as WebSocket error code 1006 (connection closed abnormally) or 1008 (pairing required), and it's one of the most common issues OpenClaw users face.
The good news? Most gateway disconnection issues stem from a handful of configuration problems that are straightforward to fix once you understand what's happening. Whether you're running OpenClaw locally, in Docker, or on a remote server, this guide walks you through every major cause and solution.
Quick Answer: OpenClaw gateway disconnection errors happen when the WebSocket connection between your browser and the OpenClaw gateway service fails. The most common causes are authentication problems (missing or incorrect gateway tokens), device pairing requirements not being met, reverse proxy misconfigurations that don't properly forward WebSocket connections, firewall rules blocking port 18789, or the gateway service not running properly.
What Does OpenClaw Disconnected from Gateway Mean?
When you see "disconnected from gateway" in OpenClaw, it means your web browser or client application can't establish or maintain a WebSocket connection to the OpenClaw gateway service. The gateway is OpenClaw's central communication hub that handles authentication, routes messages between components, and manages connections to AI models.
Think of the gateway like a telephone switchboard operator. Your browser is trying to place a call, but something's preventing the connection from going through. The error code tells you what went wrong:
Error 1006 means the connection closed unexpectedly without a proper goodbye. The gateway might have crashed, restarted, or lost connection suddenly. This is like having a phone call drop without warning.
Error 1008 indicates an authentication or policy violation. The gateway is actively rejecting your connection because you haven't proven you're authorized. This is like the switchboard operator asking for a password you don't have.
Both errors prevent you from using OpenClaw's web interface, but they have different root causes that need different fixes.
What WebSocket Connections Do in OpenClaw
OpenClaw uses WebSocket connections instead of regular HTTP requests because WebSockets allow real-time, two-way communication. When you send a message to an AI model through OpenClaw, the response streams back to you in real time. Regular HTTP requests can't do this efficiently.
The WebSocket connection stays open the entire time you're using OpenClaw. If that connection breaks, you lose access to all OpenClaw features until you reconnect. Understanding this helps explain why certain configuration problems (like reverse proxy settings) can break the gateway connection even when the web server itself works fine.
Why Does OpenClaw Show Error 1006 or 1008?
These two error codes have different meanings and different causes. Knowing which one you're seeing helps you narrow down the problem faster.
Error 1006: Connection Closed Abnormally
Error 1006 appears when the WebSocket connection terminates without following the proper closing handshake. Common scenarios include:
Gateway service crashes or restarts. If the OpenClaw gateway process dies or restarts while you're connected, your browser immediately sees error 1006. Check your gateway logs with openclaw logs --follow to see if there are crashes.
Reverse proxy doesn't support WebSockets. Many people run OpenClaw behind Nginx or another reverse proxy for HTTPS support. If your proxy configuration doesn't include WebSocket upgrade headers, connections fail with 1006. The proxy accepts the initial HTTP request but can't upgrade it to a WebSocket.
Network interruption. If you're on unstable WiFi or your VPN drops, the connection breaks without a clean close. Docker container networking issues can also cause this.
Firewall blocks the connection. Your firewall might allow the initial connection but then kill it when it realizes it's a long-lived WebSocket. Some overly aggressive firewalls treat persistent connections as suspicious.
Error 1008: Policy Violation
Error 1008 specifically indicates the gateway rejected your connection for policy reasons:
Device pairing required. OpenClaw's security model requires new devices to be explicitly approved before they can access the gateway. If you're connecting from a new browser or computer, you'll get 1008 until you approve the device.
Missing or incorrect gateway token. OpenClaw uses authentication tokens to verify connections. If your configuration doesn't include a token, or if the token doesn't match what the gateway expects, you'll see error 1008 with a message like "unauthorized" or "gateway token missing."
Token/password mismatch after restart. If you regenerate tokens or change authentication settings but don't update all your configuration files, you'll have a mismatch that causes 1008 errors.
Understanding the difference between these errors helps you jump directly to the right fix instead of trying solutions randomly.
How Do I Fix OpenClaw Gateway Connection Issues?
Here's a systematic approach to fixing gateway disconnection problems. Work through these steps in order for the fastest resolution.
Step 1: Verify the Gateway Is Running
Before diving into complex fixes, confirm the gateway service is actually running:
openclaw gateway status
You should see Runtime: running and RPC probe: ok. If the gateway isn't running, start it:
openclaw gateway start
If it won't start or crashes immediately, check the logs for errors:
openclaw logs --follow
Common startup failures include port conflicts (another service using port 18789), configuration syntax errors, or missing dependencies.
Step 2: Run OpenClaw Doctor for Diagnostics
OpenClaw includes a diagnostic tool that checks your configuration:
openclaw doctor
This command scans for common problems like missing authentication tokens, incorrect gateway URLs, and configuration inconsistencies. Fix any issues it reports before proceeding.
Step 3: Check Your Gateway URL and Port
Make sure you're connecting to the right address. If you're running OpenClaw locally, your gateway URL should be http://localhost:18789. For remote servers, it should be http://your-server-ip:18789 or https://your-domain.com if you're using a reverse proxy.
Verify your gateway binding address:
openclaw config get gateway.bind
If this returns 127.0.0.1:18789, the gateway only accepts local connections. For remote access, you need 0.0.0.0:18789 or a specific network interface IP.
Step 4: Fix Authentication Token Problems
Token mismatches are the most common cause of error 1008. Generate a fresh token:
openclaw doctor --generate-gateway-token
Copy the token it generates, then update your configuration:
openclaw config set gateway.auth.token "your-generated-token"
Restart the gateway for the change to take effect:
openclaw gateway restart
When connecting through the web UI, add the token to the URL: http://localhost:18789/?token=your-generated-token
Step 5: Check Firewall Rules
Your firewall must allow traffic on port 18789 for both TCP and UDP. On Linux with UFW:
sudo ufw allow 18789/tcp
sudo ufw allow 18789/udp
On systems using iptables directly:
sudo iptables -A INPUT -p tcp --dport 18789 -j ACCEPT
sudo iptables -A INPUT -p udp --dport 18789 -j ACCEPT
For cloud servers, also check your VPS provider's security group settings. Your hosting provider might have firewall rules separate from the server's internal firewall.
Step 6: Restart the Container (Docker Users)
If you're running OpenClaw in Docker, connection errors often clear after restarting the container:
docker restart openclaw
Docker networking can get into weird states where connections appear to work but WebSockets fail. A container restart rebuilds the network stack cleanly.
What Is OpenClaw Device Pairing and Why Is It Required?
Device pairing is OpenClaw's way of preventing unauthorized access to your gateway. When you connect from a new browser or device, OpenClaw creates a pairing request that sits in a pending state until you explicitly approve it.
This security layer prevents someone from accessing your OpenClaw instance just because they know your server's IP address. Even with the correct gateway token, new devices need explicit approval.
How Device Pairing Works
When you first connect to OpenClaw's web UI from a new browser:
- Your browser initiates a WebSocket connection
- The gateway generates a device identity challenge
- Your browser completes the challenge and creates a pairing request
- The connection shows as "disconnected (1008): pairing required"
- You approve the request using the CLI or another already-paired device
- Future connections from that browser work automatically
Approving Pending Devices
To see pending pairing requests:
openclaw devices list
Look for devices with status "pending." Approve them by ID:
openclaw devices approve <device-id>
After approval, refresh your browser and the connection should work.
Bypassing Device Pairing for Local Development
If you're running OpenClaw locally and don't need the extra security, you can disable device pairing requirements:
openclaw config set gateway.controlUi.allowInsecureAuth true
This lets token or password authentication work without device pairing. Only use this for local development or trusted networks, not for internet-exposed instances.
How Do I Set Up OpenClaw Gateway Authentication Correctly?
OpenClaw supports three authentication modes: token (recommended), password, and trusted-proxy. Each mode has different use cases and security implications.
Token Authentication (Recommended)
Token authentication uses a shared secret that both the gateway and connecting clients know. This is the most flexible option and works well for most deployments.
Set it up:
openclaw config set gateway.auth.mode "token"
openclaw config set gateway.auth.token "your-secure-random-token"
Generate a secure random token with:
openclaw doctor --generate-gateway-token
When connecting, add the token as a URL parameter: http://your-server:18789/?token=your-secure-random-token
Password Authentication
Password mode lets you authenticate with a simple password instead of a token. It's easier for human users to remember but less suitable for automation.
openclaw config set gateway.auth.mode "password"
openclaw config set gateway.auth.password "your-password"
The web UI will prompt you for the password when you connect.
Trusted Proxy Mode
Use this when running OpenClaw behind an identity-aware reverse proxy like Pomerium or Authelia that handles authentication before requests reach OpenClaw.
openclaw config set gateway.auth.mode "trusted-proxy"
In this mode, OpenClaw trusts authentication headers from the proxy and doesn't do its own authentication. Only use this when the proxy is properly configured and OpenClaw isn't directly accessible from the internet.
Choosing the Right Mode
For most self-hosted setups, token mode gives the best balance of security and convenience. Use password mode if you're the only user and prefer entering a password. Only use trusted-proxy mode if you already have an authentication proxy in your infrastructure and understand the security implications.
What Are the Best Practices for Running OpenClaw Behind a Reverse Proxy?
Running OpenClaw behind Nginx, Apache, or Caddy is common for adding HTTPS support and professional domain names. But reverse proxies need special configuration to properly handle WebSocket connections.
Nginx Configuration for WebSocket Support
The critical part of Nginx configuration is the WebSocket upgrade headers. Without these, your proxy accepts connections but can't upgrade them to WebSockets, causing error 1006.
Here's a complete working configuration:
server {
listen 443 ssl;
server_name openclaw.yourdomain.com;
ssl_certificate /path/to/cert.pem;
ssl_certificate_key /path/to/key.pem;
location / {
proxy_pass http://localhost:18789;
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 for WebSocket stability
proxy_read_timeout 86400;
proxy_send_timeout 86400;
}
}
The key lines are:
proxy_http_version 1.1;— WebSockets require HTTP 1.1proxy_set_header Upgrade $http_upgrade;— Passes the upgrade request to OpenClawproxy_set_header Connection "upgrade";— Tells the backend this is an upgrade requestproxy_read_timeout 86400;— Keeps long-lived connections from timing out
Apache Configuration
If you're using Apache, enable the proxy and proxy_wstunnel modules:
sudo a2enmod proxy
sudo a2enmod proxy_http
sudo a2enmod proxy_wstunnel
Then configure your virtual host:
<VirtualHost *:443>
ServerName openclaw.yourdomain.com
SSLEngine on
SSLCertificateFile /path/to/cert.pem
SSLCertificateKeyFile /path/to/key.pem
ProxyPreserveHost On
ProxyPass / ws://localhost:18789/
ProxyPassReverse / ws://localhost:18789/
RewriteEngine on
RewriteCond %{HTTP:Upgrade} websocket [NC]
RewriteRule /(.*) ws://localhost:18789/$1 [P,L]
</VirtualHost>
Caddy Configuration
Caddy handles WebSockets automatically, making it the simplest option:
openclaw.yourdomain.com {
reverse_proxy localhost:18789
}
That's it. Caddy automatically handles HTTPS certificates via Let's Encrypt and properly upgrades WebSocket connections.
Common Reverse Proxy Mistakes
Forgetting WebSocket upgrade headers is the most common issue. Regular HTTP proxying works fine, but WebSockets silently fail with error 1006.
Setting proxy timeouts too low causes disconnections during long AI responses. Set read and send timeouts to at least 86400 seconds (24 hours) or disable them entirely.
Not configuring HTTPS properly can cause mixed content warnings if your OpenClaw gateway uses HTTP but your reverse proxy uses HTTPS.
When setting up OpenClaw on cloud infrastructure, choosing the right hosting platform matters for performance and stability. If you're comparing cloud options, check out our guide on AWS EC2 vs Lightsail for OpenClaw deployments to understand which service better fits your needs.
How Do I Troubleshoot OpenClaw Gateway in Docker Containers?
Docker adds another layer of networking that can cause gateway connection problems. Here's how to diagnose and fix Docker-specific issues.
Check Container Network Connectivity
First, verify the container is running and healthy:
docker ps | grep openclaw
docker logs openclaw --tail 50
Check if you can reach the gateway from inside the container:
docker exec openclaw openclaw gateway status
If this works but external connections fail, the problem is with Docker networking, not OpenClaw itself.
Fix Docker Port Mapping
Make sure you're exposing port 18789 when running the container:
docker run -d \
--name openclaw \
-p 18789:18789 \
-v openclaw-data:/app/data \
openclaw/openclaw:latest
The -p 18789:18789 maps the container's port 18789 to your host's port 18789. Without this, external connections can't reach the gateway.
Docker Network Mode Issues
If you're using Docker's host network mode, the gateway binds directly to the host's network interfaces:
docker run -d \
--name openclaw \
--network host \
-v openclaw-data:/app/data \
openclaw/openclaw:latest
Host mode can solve connectivity issues but removes container network isolation. Use it carefully.
Environment Variable Configuration
When running in Docker, configure the gateway through environment variables:
docker run -d \
--name openclaw \
-p 18789:18789 \
-e OPENCLAW_GATEWAY_AUTH_MODE=token \
-e OPENCLAW_GATEWAY_AUTH_TOKEN=your-token-here \
-v openclaw-data:/app/data \
openclaw/openclaw:latest
Make sure your token matches what you're using in the web UI connection URL.
Container Restart Policies
Set a restart policy so the gateway automatically recovers from crashes:
docker run -d \
--name openclaw \
--restart unless-stopped \
-p 18789:18789 \
-v openclaw-data:/app/data \
openclaw/openclaw:latest
The unless-stopped policy restarts the container automatically if it crashes, but respects manual stops.
For heavy workloads that require more computing power, you might need a VPS with higher CPU allocation. Our roundup of top VPS providers for CPU-intensive OpenClaw instances covers the best options for performance-demanding deployments.
How Do I Prevent OpenClaw Gateway Disconnections?
Prevention is better than troubleshooting. Here are strategies to keep your gateway connection stable.
Set WebSocket Keep-Alive Properly
WebSocket connections can die silently if no data flows for too long. Configure keep-alive pings:
openclaw config set gateway.websocket.keepAlive 30
This sends a ping every 30 seconds to keep the connection alive through NAT gateways and firewalls.
Use Stable Network Infrastructure
Avoid running OpenClaw over unreliable WiFi or VPN connections for production use. Wired connections or stable cloud hosting provide much better reliability.
If you must use a VPN, prefer WireGuard over OpenVPN. WireGuard handles connection interruptions more gracefully.
Monitor Gateway Health
Set up monitoring to alert you when the gateway goes down:
openclaw system heartbeat enable
Configure heartbeat notifications to send alerts to a messaging channel you monitor regularly.
Keep Configuration in Sync
When you update authentication tokens or change settings, update all configuration files:
- Main OpenClaw config file
- Environment variables in Docker
- Reverse proxy configuration
- Any custom scripts or automation
Configuration drift causes mysterious authentication failures.
Regular Updates and Restarts
Update OpenClaw regularly to get bug fixes and improvements:
openclaw update
Restart the gateway after major updates to ensure clean initialization:
openclaw gateway restart
Some updates change internal protocols or authentication flows. A restart ensures everything loads with the new version's expectations.
What Network and Firewall Configuration Does OpenClaw Need?
Proper network configuration prevents many gateway connection problems. Here's what OpenClaw needs to work correctly.
Required Ports
OpenClaw gateway uses port 18789 by default. Both TCP and UDP traffic should be allowed:
- TCP 18789: WebSocket connections, API calls, gateway communication
- UDP 18789: Real-time protocol optimizations (optional but recommended)
If you're connecting to external AI services, you also need outbound HTTPS (port 443) access.
Firewall Configuration by Platform
Linux (UFW):
sudo ufw allow 18789/tcp
sudo ufw allow 18789/udp
sudo ufw reload
Linux (iptables):
sudo iptables -A INPUT -p tcp --dport 18789 -j ACCEPT
sudo iptables -A INPUT -p udp --dport 18789 -j ACCEPT
sudo iptables-save > /etc/iptables/rules.v4
Cloud Security Groups (AWS, DigitalOcean, Vultr):
Create an inbound rule allowing TCP and UDP on port 18789 from your desired source (your IP for private access, or 0.0.0.0/0 for public access with proper authentication).
When choosing between cloud providers for your OpenClaw deployment, performance benchmarks matter. See our comparison of Vultr High Frequency vs DigitalOcean Premium instances to understand which platform delivers better OpenClaw performance.
Local vs Remote Deployment Differences
Local deployment (running on your own machine):
- Bind address:
127.0.0.1:18789 - Access URL:
http://localhost:18789 - Firewall: Can remain restrictive; only localhost access needed
- Authentication: Can use relaxed settings for convenience
Remote deployment (cloud server, VPS, or network server):
- Bind address:
0.0.0.0:18789or specific interface IP - Access URL:
http://your-server-ip:18789or domain name with reverse proxy - Firewall: Must allow inbound connections on 18789
- Authentication: Should use strong tokens and device pairing
DNS and HTTPS Considerations
If you're using a custom domain with HTTPS:
- Point your DNS A record to your server's IP
- Set up a reverse proxy (Nginx, Caddy, etc.) with SSL certificates
- Configure OpenClaw to accept connections forwarded from the proxy
- Set the proper forwarded-for headers so OpenClaw sees real client IPs
HTTPS is strongly recommended for internet-exposed instances to prevent token interception.
Comparison: OpenClaw Gateway Error Codes
Understanding the difference between common error codes helps you troubleshoot faster:
| Error Code | Meaning | Common Causes | Quick Fix |
|---|---|---|---|
| 1006 | Abnormal closure | Reverse proxy misconfiguration, gateway crash, network interruption, firewall blocking | Check proxy WebSocket headers, restart gateway, verify firewall rules |
| 1008 | Policy violation | Device pairing required, token mismatch, authentication failure | Approve device pairing, regenerate and set correct token |
| 1000 | Normal closure | User-initiated disconnect, intentional shutdown | No action needed; this is normal behavior |
| 1001 | Going away | Gateway shutting down, browser tab closing | Wait for gateway to restart or reconnect |
| 4008 | Idle timeout | Connection inactive too long, keep-alive not working | Configure WebSocket keep-alive, check proxy timeout settings |
Common Mistakes to Avoid
When troubleshooting OpenClaw gateway issues, avoid these frequent pitfalls:
Mixing HTTP and HTTPS. If your reverse proxy uses HTTPS but your gateway URL in the configuration still says HTTP, you'll get mixed content errors. Keep your protocols consistent.
Forgetting to restart after config changes. OpenClaw reads configuration at startup. Changing a setting doesn't take effect until you restart the gateway service.
Using weak or guessable tokens. Short tokens like "password123" or "test" are security risks. Use the openclaw doctor --generate-gateway-token command to create strong random tokens.
Not checking logs. The gateway logs contain detailed error messages that point directly to the problem. Always check openclaw logs --follow when troubleshooting.
Trying to fix everything at once. Change one thing at a time and test after each change. If you modify five settings simultaneously and it starts working, you won't know which change actually fixed the problem.
Frequently Asked Questions
How do I know if my OpenClaw gateway is running?
Run openclaw gateway status in your terminal. You should see "Runtime: running" and "RPC probe: ok" if everything is working correctly.
Can I use OpenClaw without device pairing?
Yes, but only for local development or trusted networks. Set gateway.controlUi.allowInsecureAuth: true to allow token or password authentication without device pairing. Don't use this setting for internet-exposed instances.
Why does my gateway disconnect after a few minutes of inactivity?
This usually means your reverse proxy or firewall is timing out idle WebSocket connections. Increase proxy timeouts to at least 86400 seconds and enable WebSocket keep-alive pings with openclaw config set gateway.websocket.keepAlive 30.
Do I need to open port 18789 on my router for local OpenClaw use?
No. If you're only accessing OpenClaw from the same machine it's running on (using localhost), you don't need to modify your router or firewall. Port forwarding is only necessary for remote access from other devices.
What's the difference between token and password authentication?
Token authentication uses a long random string that clients include in the connection URL. Password authentication prompts users to enter a password in the web UI. Token mode is better for automation and API access; password mode is more user-friendly for human access.
Can I run multiple OpenClaw gateways on the same server?
Yes, but each gateway needs a unique port. The first gateway uses 18789, the second could use 18790, etc. Configure the port with openclaw config set gateway.bind "0.0.0.0:18790" for additional instances.
Conclusion
OpenClaw gateway disconnection errors are frustrating, but they usually come down to a few common issues: authentication token problems, device pairing requirements, reverse proxy configurations that don't support WebSockets, or firewall rules blocking connections.
Start with the basics: verify the gateway is running, check your authentication setup, and make sure your firewall allows port 18789. If you're using a reverse proxy, double-check that it includes the WebSocket upgrade headers. For Docker deployments, confirm your port mappings are correct.
Most importantly, use the diagnostic tools OpenClaw provides. The openclaw doctor command catches configuration problems automatically, and openclaw logs --follow shows exactly what's failing when connections drop.
With proper configuration and a systematic troubleshooting approach, you can keep your OpenClaw gateway stable and accessible whether you're running it locally for development or on a remote server for production use.