Hindi Naglo-load ang OpenClaw Dashboard: Mga Ports, WebSockets, Mga Pag-aayos ng Reverse Proxy

Hey mga nag-aayos ng dashboard — kung nakatitig ka sa blangkong pahina, connection refused, o "hindi awtorisado" na mga error habang tumatakbo naman ang gateway ng OpenClaw, naranasan ko na 'yan.

Noong nakaraang linggo, nag-debug ako ng eksaktong problemang ito sa apat na setup: lokal na dev sa Mac, Docker sa Ubuntu, nginx reverse proxy, at isang instance na naka-expose sa Tailscale. Bawat isa ay may iba't ibang mode ng pagkabigo — pero lahat ay nag-ugat sa parehong limang pangunahing sanhi.

Naglo-load ang HTML. Ipinapakita ng DevTools ang mga pagkabigo sa WebSocket handshake. Walang sinasabi ang mga gateway log na kapaki-pakinabang. Hindi ka sigurado kung ito ba ay auth, networking, o config corruption.

Narito ang talagang sumisira: nawawala ang mga WebSocket upgrade header sa iyong proxy, tinatrato ng Docker NAT ang localhost bilang external, hindi nagpapatuloy ang mga auth token sa localStorage, o mga banggaan ng port mula sa mga lumang serbisyo ng Clawdbot/Moltbot na patuloy na tumatakbo.

Ang gabay na ito ay naglalakad sa diagnostic flow na aking binuo pagkatapos ayusin ang mga ito nang paulit-ulit. Magsimula dito, sundin ang mga tseke, at o mapapagana mo ang dashboard o malalaman mo kung ano ang dapat iulat.

Kumpirmahin ang Kalusugan ng Serbisyo

Before diving into proxies and ports, verify the gateway is actually functional.

Is the Gateway Process Running?

# Check gateway status
openclaw status
# If using systemd
systemctl --user status openclaw-gateway
# Docker users
docker ps | grep openclaw-gateway

What you're looking for:

• Status: running or active
• Uptime: More than 30 seconds (not crash-looping)
• No recent restarts

If it's not running or restarting constantly, stop here and fix the gateway install issues first.

Can the WebSocket Server Respond?

Test the WebSocket endpoint directly:

# Install wscat if you don't have it
npm install -g wscat
# Test connection (replace with your actual token)
wscat -c "ws://127.0.0.1:18789/?token=YOUR_TOKEN_HERE"

Possible outcomes:

• Connected, gets challenge message → Gateway is fine, problem is browser/proxy
• Connection refused → Port/bind issue, go to next section
• Connected then immediately closes with 1008 → Auth problem

If wscat connects but the browser doesn't, the issue is either CORS, proxy config, or browser security policy.

Check What the Gateway Actually Heard

Look at recent logs:

# View last 50 log lines
openclaw logs --limit 50
# Docker
docker logs openclaw-gateway --tail 50
# Look for WebSocket handshake attempts
openclaw logs | grep -E 'ws\]|websocket|handshake'

Key patterns:

• [ws] accepted → Connection succeeded
• [ws] closed before connect ... code=1008 reason=pairing required → Auth mismatch
• [ws] closed before connect ... code=1008 reason=unauthorized: gateway token missing → Token not reaching gateway
• Origin http://... is not allowed → CORS issue

Port Conflicts & Bind Addresses

Problem: Gateway Binds to Wrong Interface

Symptom: Gateway runs fine via CLI, but browser can't connect to 127.0.0.1:18789.

Cause: Gateway bound to a Tailscale IP, VPN interface, or external IP instead of loopback.

This is Issue #1380 — when Tailscale is active, the gateway sometimes binds to 100.x.x.x instead of 127.0.0.1. Browser WebSocket connections to Tailscale IPs fail.

Diagnose:

# Check what interface the gateway bound to
openclaw status
# Or inspect the actual listening socket
sudo lsof -i :18789
# Look at the "NAME" column - should show 127.0.0.1:18789

Fix:

Force loopback binding in config (~/.openclaw/config.json):

{
  "gateway": {
    "bind": "loopback",
    "port": 18789
  }
}

Valid bind options:

• loopback → 127.0.0.1 only (default, safest)
• lan → 0.0.0.0 (all interfaces, requires auth)
• tailnet → Tailscale IP

After changing bind, restart:

systemctl --user restart openclaw-gateway
# or
docker compose restart openclaw-gateway

Problem: Port 18789 Already in Use

Symptom: Gateway won't start, logs show EADDRINUSE.

Cause: Old Clawdbot/Moltbot gateway still running, or another service using 18789.

Diagnose:

# Find what's using the port
sudo lsof -i :18789
# Or
sudo ss -tlnp | grep 18789

Fix Option A: Stop Conflicting Service

# Stop old Clawdbot
systemctl --user stop clawdbot-gateway
# Kill the process if needed
sudo kill -9 <PID>

Fix Option B: Change OpenClaw Port

In ~/.openclaw/config.json:

{
  "gateway": {
    "port": 18790
  }
}

Update Docker compose if using containers:

ports:
  - "127.0.0.1:18790:18790"

Then access dashboard at http://127.0.0.1:18790/.

Problem: Docker NAT Breaks Localhost Detection

Symptom: Running gateway in Docker Desktop on Windows/Mac, browser shows "pairing required" even with correct token.

Cause: Docker's NAT networking makes the gateway see connections from 172.18.0.1 instead of 127.0.0.1. Gateway treats this as an external connection requiring node pairing.

Diagnose:

Check gateway logs for:

[ws] closed before connect conn=... remote=172.18.0.1 ... code=1008 reason=pairing required

If you see remote=172.18.0.1 but you're connecting from 127.0.0.1, this is the issue.

Fix:

Add trusted proxies to your config:

{
  "gateway": {
    "trustedProxies": ["172.18.0.0/16", "172.17.0.0/16"]
  }
}

Or run gateway with --bind lan and enforce token auth:

{
  "gateway": {
    "bind": "lan",
    "auth": {
      "mode": "token",
      "token": "your-secret-token"
    }
  }
}

Better fix for Windows/Mac: Run gateway natively instead of in Docker to get real localhost connections.

Reverse Proxy WebSockets Checklist

If you're exposing OpenClaw through nginx, Caddy, or another reverse proxy, WebSocket support needs explicit configuration.

nginx Configuration

The dashboard uses WebSockets for real-time communication. Standard HTTP proxying breaks this.

Minimal working config:

server {
    listen 443 ssl;
    server_name openclaw.yourdomain.com;
    # SSL certs
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;
    location / {
        proxy_pass http://127.0.0.1:18789;
        # Critical for WebSockets
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";     
        # Pass through client info
        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;
        # WebSocket timeouts
        proxy_read_timeout 86400;
        proxy_send_timeout 86400;
    }
}

Common nginx mistakes:

• Missing proxy_http_version 1.1 → WebSocket upgrade fails
• Missing Upgrade and Connection headers → Handshake rejected
• Default timeout (60s) → WebSocket closes after idle time

Detailed nginx reverse proxy guide: nginx WebSocket proxying

Caddy Configuration

Caddy handles WebSockets automatically, but you still need proper config:

openclaw.yourdomain.com {
    reverse_proxy 127.0.0.1:18789
}

That's it. Caddy auto-detects the WebSocket upgrade and adjusts timeouts.

If using subpath:

yourdomain.com {
    reverse_proxy /openclaw/* 127.0.0.1:18789
}

Then access via https://yourdomain.com/openclaw/.

Debugging Caddy WebSocket issues:

Enable verbose logging:

openclaw.yourdomain.com {
    log {
        output file /var/log/caddy/openclaw.log
        level DEBUG
    }
    reverse_proxy 127.0.0.1:18789
}

Check for websocket upgrade in logs. If missing, Caddy isn't detecting the upgrade request.

Apache Configuration

Less common but occasionally used:

<VirtualHost *:443>
    ServerName openclaw.yourdomain.com
    SSLEngine On
    SSLCertificateFile /path/to/cert.pem
    SSLCertificateKeyFile /path/to/key.pem
    # Enable proxy modules
    # a2enmod proxy proxy_http proxy_wstunnel rewrite
    ProxyPreserveHost On
    # WebSocket tunnel
    RewriteEngine On
    RewriteCond %{HTTP:Upgrade} =websocket [NC]
    RewriteRule /(.*)  ws://127.0.0.1:18789/$1 [P,L]
    # Regular HTTP proxy
    ProxyPass / http://127.0.0.1:18789/
    ProxyPassReverse / http://127.0.0.1:18789/
</VirtualHost>

Enable required modules:

sudo a2enmod proxy proxy_http proxy_wstunnel rewrite
sudo systemctl restart apache2

CORS / HTTPS Gotchas

Mixed Content Blocking

Symptom: Dashboard loads over HTTPS but WebSocket connection fails with mixed content error.

Cause: Browser blocks ws:// (non-secure WebSocket) when page is loaded over https://.

Fix:

Use wss:// (WebSocket Secure) behind your reverse proxy.

Your nginx/Caddy terminates SSL and forwards to http://127.0.0.1:18789, but the browser needs to connect via wss://.

Example flow:

• Browser: wss://openclaw.yourdomain.com/ → nginx with SSL
• nginx: ws://127.0.0.1:18789/ → gateway (local, no SSL needed)

The dashboard auto-detects this if you access it via HTTPS URL.

CORS Rejections

Symptom: Browser console shows CORS policy: No 'Access-Control-Allow-Origin' header.

Cause: Accessing dashboard from a different domain than the gateway expects.

Context: As of OpenClaw's security updates, the Control UI has stricter origin validation.

Fix:

If your dashboard is at https://openclaw.example.com but gateway config doesn't know about it:

{
  "gateway": {
    "cors": {
      "origins": ["https://openclaw.example.com"]
    }
  }
}

Security note: Don't use "origins": ["*"] in production. This exposes your gateway to external access vulnerabilities.

Token Not Persisting in localStorage

Symptom: Dashboard keeps asking for token every time you reload.

Cause: Browser's localStorage API blocked or cleared.

Diagnose:

Open DevTools → Application → Local Storage → http://127.0.0.1:18789

Look for key: openclaw-gateway-token

If missing after login, check:

• Browser in private/incognito mode (localStorage disabled)
• Third-party cookie blocking extensions
• Browser set to clear storage on exit

Workaround:

Use the tokenized URL every time:

openclaw dashboard

This command outputs a URL with ?token=... appended. The UI strips it after first load and saves to localStorage — but if that fails, you need the URL each time.

Logs to Collect Before Reporting

If none of the above fixes work, you're in edge case territory. Before opening a GitHub issue, collect these logs:

Gateway Logs

# Last 100 lines with timestamps
openclaw logs --limit 100 > gateway-logs.txt
# Docker
docker logs openclaw-gateway --tail 100 > gateway-logs.txt

Browser Console Logs

1. Open DevTools (F12)
2. Go to Console tab
3. Reproduce the connection failure
4. Right-click console → Save as... → browser-console.txt

WebSocket Frame Inspection

1. DevTools → Network tab
2. Filter: WS
3. Click the WebSocket connection
4. Check "Messages" tab for handshake details
5. Screenshot the Headers tab showing request/response

Config Sanitized

# Export config (redact tokens)
cat ~/.openclaw/config.json | sed 's/"token": ".*"/"token": "REDACTED"/g' > config-sanitized.json

Network Environment

# Check firewall rules (Linux)
sudo iptables -L -n | grep 18789
# Check what's binding to the port
sudo lsof -i :18789
# Test from external host if relevant
curl -v http://your-server-ip:18789/

What Actually Breaks Dashboards

Matapos i-debug ang mga ito sa iba't ibang environment, narito ang pagkakahati ng mga pagkabigo na nakita ko:

60% - Nawawala ang reverse proxy WebSocket config

• nginx na walang Upgrade/Connection headers
• Mali ang mga setting ng timeout
• Nawawala ang proxy_http_version 1.1

20% - Ipinapakita ng Docker NAT na ang localhost ay parang external

• Windows/Mac Docker Desktop
• Naayos sa pamamagitan ng pagpapatakbo ng gateway nang natively o pagdaragdag ng trustedProxies

10% - Mga conflict sa port mula sa lumang Clawdbot/Moltbot

• Nakalimutan patigilin ang lumang serbisyo bago i-install ang OpenClaw
• Naayos sa pamamagitan ng pagpapatigil sa lumang proseso o pagbabago ng port

5% - Tailscale binding sa halip na loopback

• Ang gateway ay nagbubuklod sa 100.x.x.x kapag aktibo ang Tailscale
• Naayos sa pamamagitan ng pagpilit ng bind: "loopback" sa config

5% - Hindi tugmang auth token

• Ang token sa config ay hindi tugma sa token sa URL
• Naayos sa pamamagitan ng pagpapatakbo ng openclaw dashboard upang makuha ang tamang tokenized na link

Ang pinaka-karaniwang problema — reverse proxy WebSocket config — ay madalas ding hindi napapansin dahil gumagana nang maayos ang HTTP na bahagi. Nakikita mo ang HTML, naglo-load ang CSS, ngunit tahimik na nabibigo ang WebSocket.

Kung tumatakbo ka sa likod ng isang proxy at ang dashboard ay hindi kumokonekta, iyon ang iyong unang suriin.

Sa Macaron, kami ang bahala sa UI para sa iyo — wala nang mga nginx configs na kailangang i-debug, walang mga WebSocket timeouts na kailangang ayusin, at walang mga Docker NAT na sorpresa. Kung pagod ka na sa pagtroubleshoot ng infrastructure bago mo pa ma-test ang workflows, mas gusto mo ba ng hosted UI para sa workflows? Gumawa ng Macaron account.

FAQ

Q: Naglo-load ang dashboard HTML pero wala namang gumagana. Saan ako magsisimula? Buksan ang DevTools → Network → WS tab. Kung ang WebSocket handshake ay nabigo, halos tiyak na kulang ka ng Upgrade at Connection headers sa iyong reverse proxy config. Iyan na ang 60% ng mga kaso diyan. Kung gusto mong i-rule out muna ang bad install, irirekomenda kong i-cross-check laban sa OpenClaw installation guide bago sumulong sa mas malalim na proxy configs.

Q: Bakit ang gateway ko ay nagpapakita ng "pairing required" kahit na tama ang pagkakatalaga ko ng token? Tingnan ang iyong mga logs para sa remote=172.18.0.1. Kung gumagamit ka ng Docker Desktop (Windows o Mac), ang NAT ay nagpapaisip sa gateway na ikaw ay isang external connection. I-run ang gateway nang natively, o magdagdag ng trustedProxies sa iyong config — ang Docker setup guide ay may eksaktong network config para sa senaryong ito.

Q: Bakit patuloy na humihingi ng token ang Gateway tuwing nire-reload ang pahina? Hindi napapanatili ng localStorage ng iyong browser ang data. Karaniwan itong nangyayari sa incognito mode, isang agresibong privacy extension, o kapag naka-enable ang "clear storage on exit". Gamitin ang tokenized URL mula sa openclaw dashboard bilang alternatibong solusyon. Kung lampas pa rito ang mga isyu sa authentication, ang OpenClaw security checklist ay may detalyadong impormasyon tungkol sa pamamahala ng token.

Q: Nakakagamit na ng Port 18789. Ano ang gumagamit nito? Siyam sa sampung beses, ito ay isang lumang Moltbot o Clawdbot gateway na tumatakbo pa rin. Ang lsof -i :18789 ay magpapakita kung ano ito. Patayin ito, o baguhin na lang ang port ng OpenClaw sa config. Kung kamakailan kang lumipat mula sa Moltbot, ito ang artikulo tungkol sa pagtakbo ng parehong sabay na dapat basahin — pangkaraniwang problema ang mga pagkakontra ng serbisyo doon.

Q: Hindi makakonekta ang aking HTTPS dashboard sa WebSocket. Mixed content — hindi papayagan ng browser ang ws:// sa isang HTTPS na pahina, walang pasubali. Kailangang i-handle ng iyong proxy ang wss:// termination. Kung nasa VPS ka at patuloy na nakakaranas nito, ang VPS deployment guide ay may gumaganang nginx + SSL config na maaari mong gamitin.

Q: Aktibo ang Tailscale at ngayon hindi mag-load ang dashboard nang lokal. Kilalang isyu (#1380) — Maaaring kunin ng Tailscale ang gateway patungo sa 100.x.x.x sa halip na 127.0.0.1. Idagdag ang "bind": "loopback" sa iyong config at mag-restart. Kung nakakalito pa rin ang bind behavior pagkatapos nito, ang gateway reference ay malinaw na nagpapaliwanag ng lahat ng mga opsyon.