OpenClaw ダッシュボードが読み込まれない：ポート、WebSocket、リバースプロキシの修正

ダッシュボードのトラブルシューティングをしている皆さんへ — OpenClaw のゲートウェイが確実に動いているのに、白紙のページや「接続拒否」や「認証されていない」エラーを目にしているなら、私もその経験があります。

先週、私はこの問題を4つのセットアップでデバッグしました：Macでのローカル開発、Ubuntu上のDocker、nginxリバースプロキシ、Tailscaleで公開されたインスタンス。どれも異なるエラーモードを持っていましたが、すべて同じ5つの根本原因にたどり着きました。

HTMLは読み込まれます。DevToolsはWebSocketのハンドシェイク失敗を示しています。ゲートウェイのログは役に立たない情報しかありません。それが認証、ネットワーク、または設定の破損によるものかはわかりません。

実際に問題を引き起こしているのは、プロキシでのWebSocketアップグレードヘッダーの欠如、Docker NATがlocalhostを外部として扱うこと、localStorageで認証トークンが保持されないこと、または古いClawdbot/Moltbotサービスがまだ動いていることによるポートの衝突です。

このガイドは、これらを何度も修正した後に構築した診断フローを説明します。ここから始め、チェックを進めれば、ダッシュボードが動作するか、報告すべきことが明確になります。

サービスの健全性を確認

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

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

WebSocket Frame Inspection

DevTools → Network tab
Filter: WS
Click the WebSocket connection
Check "Messages" tab for handshake details
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

これらを異なる環境でデバッグした後、以下のような失敗の分布が見られました：

60% - リバースプロキシのWebSocket設定が欠如

Upgrade/Connectionヘッダーのないnginx
タイムアウト設定が不正
proxy_http_version 1.1が欠如

20% - Docker NATがlocalhostを外部として扱う

Windows/MacのDocker Desktop
ゲートウェイをネイティブで実行するか、trustedProxiesを追加することで修正

10% - 古いClawdbot/Moltbotによるポート競合

OpenClawをインストールする前に古いサービスを停止するのを忘れる
古いプロセスを終了するかポートを変更することで修正

5% - ループバックの代わりにTailscaleがバインド

Tailscaleがアクティブな時にゲートウェイが100.x.x.xにバインド
設定でbind: "loopback"を強制することで修正

5% - 認証トークンの不一致

設定内のトークンとURL内のトークンが一致しない
openclaw dashboardを実行して正しいトークン化されたリンクを取得することで修正

最も一般的なリバースプロキシのWebSocket設定の問題は、HTTP部分が正常に動作するため見落としがちです。HTMLやCSSは読み込まれますが、WebSocketは静かに失敗します。

プロキシの背後で実行していてダッシュボードが接続しない場合、最初に確認すべきポイントです。

Macaronでは、UIをホストします — nginxの設定をデバッグする必要も、WebSocketのタイムアウトを調整する必要も、Docker NATの驚きを心配する必要もありません。インフラのトラブルシューティングに疲れ果て、ワークフローをテストする前に挫折してしまうことありませんか？ホストされたワークフロー用のUIをお好みですか？ Macaronアカウントを作成してください。

FAQ

Q: ダッシュボードのHTMLは読み込まれますが、何も機能しません。どこから始めればいいですか？ DevToolsを開き、ネットワーク → WSタブを確認します。WebSocketハンドシェイクが失敗している場合、リバースプロキシ設定にUpgradeとConnectionヘッダーが欠けている可能性が高いです。それが原因の60%です。まずは悪いインストールを除外したい場合は、プロキシの設定を深く調べる前に、OpenClawインストールガイドを確認します。

Q: トークンを正しく設定したのに、ゲートウェイが「ペアリングが必要」と表示されるのはなぜですか？ ログでremote=172.18.0.1を確認してください。Docker Desktop（WindowsまたはMac）を使用している場合、NATによってゲートウェイが外部接続と認識しています。ゲートウェイをネイティブで実行するか、設定にtrustedProxiesを追加してください。このシナリオに適したネットワーク設定は、Dockerセットアップガイドに正確に記載されています。

Q: ページをリロードするたびにGatewayがトークンを求めてきます。 ブラウザのlocalStorageが保持されていません。通常、シークレットモードや強力なプライバシー拡張機能、または「終了時にストレージをクリア」が有効になっていることが原因です。openclaw dashboardからトークン化されたURLを使うのが回避策です。もし認証の問題がこれを超える場合は、OpenClawセキュリティチェックリストにトークン管理の詳細が記載されています。

Q: ポート18789が既に使用中です。何が使っているのでしょうか？ 十中八九、古いMoltbotやClawdbotのゲートウェイがまだ動いています。lsof -i :18789を実行すると何が使っているか分かります。それを終了するか、OpenClawの設定でポートを変更してください。最近Moltbotから移行した場合は、MoltbotとOpenClawを同時に運用する記事が参考になります—サービスの競合はよくある問題です。

Q: HTTPSダッシュボードがWebSocketに接続できません。 混在コンテンツ—ブラウザはHTTPSページでws://を許可しません。プロキシがwss://の終了を処理する必要があります。VPSを使用していてこの問題に直面する場合は、VPSデプロイメントガイドにnginx + SSLの設定が掲載されているので、それをそのまま使うことができます。

Q: Tailscale がアクティブで、ダッシュボードがローカルで読み込まれません。 既知の問題 (#1380) — Tailscale は 127.0.0.1 の代わりに 100.x.x.x にゲートウェイを引き込むことがあります。設定に "bind": "loopback" を追加して再起動してください。それでもバインド動作がわかりにくい場合は、ゲートウェイリファレンスで全てのオプションが詳しく説明されています。