Dashboard & Web UI — Setup & Troubleshooting

## Step 1: Verify Gateway is Running

The dashboard is served by the Gateway. First check its status:

openclaw gateway status

Expected output shows the gateway bound to port 18789. If not running:

openclaw gateway start

Or run in foreground to see errors:

openclaw gateway

## Step 2: Check Port 18789 is Actually Listening

On macOS/Linux:

lsof -i :18789# ornetstat -an | grep 18789

On Windows PowerShell:

Get-NetTCPConnection -LocalPort 18789

If nothing is listening, the Gateway isn't running or crashed on startup. Check logs:

openclaw logs | tail -50

## Step 3: Fix 'command not found' After Install

If openclaw or moltbot commands aren't found after npm install:

# Check if npm global bin is in PATHnpm bin -g# Add to PATH temporarilyexport PATH="$(npm bin -g):$PATH"# Or reinstall with pnpm (better global handling)pnpm add -g openclaw@latest

On EC2/Linux, you may need to source your profile:

source ~/.bashrc# orsource ~/.profile

## Step 4: Fix WebSocket 1006 Abnormal Closure

This error means the WebSocket disconnected unexpectedly:

RPC probe: failedRPC target: ws://127.0.0.1:18789gateway closed (1006 abnormal closure)

Common causes and fixes:

1. Gateway crashed — Restart it:

``bash openclaw gateway restart

2. Firewall blocking localhost — Temporarily disable to test:

- Windows: Disable Windows Defender Firewall

- macOS: Check System Preferences → Security & Privacy → Firewall

3. Path with special characters — If your username has non-ASCII characters (Cyrillic, etc.), try:

- Running terminal as Administrator

- Moving config to a simpler path: C:\openclaw\

4. Antivirus interference — Temporarily disable antivirus software

## Step 5: Fix TUI White-on-White Text

The TUI assumes a dark terminal background. If text is invisible:

Option A: Switch terminal to dark theme

- iTerm2: Preferences → Profiles → Colors → Color Presets → Dark Background

- Windows Terminal: Settings → Color schemes → One Half Dark

- macOS Terminal: Preferences → Profiles → Pro or Homebrew

Option B: Force specific colors in terminal

Set your terminal to use explicit foreground/background colors rather than 'auto' or 'system' appearance.

The TUI uses your terminal's color scheme—it's not a bug in OpenClaw, it's a terminal configuration issue.

## Step 6: Access Dashboard from VM or Remote Machine

When accessing from outside localhost, browsers require HTTPS due to WebCrypto security. You'll see:

WebCrypto requires secure context (HTTPS or localhost)

Option A: SSH Tunnel (Recommended for VMs)

Keep Gateway on loopback in the VM, then tunnel from your host:

# On your Windows/Mac host:ssh -L 18789:127.0.0.1:18789 user@vm-ip

Now access http://127.0.0.1:18789 on your host—it tunnels to the VM.

Option B: Tailscale Serve (Best for true remote access)

# On the VM/server:openclaw gateway --tailscale serve

Then access via your Tailscale MagicDNS URL (https://machine-name.tailnet/).

Option C: Allow Insecure Auth (Not Recommended)

Only for trusted networks:

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

This reduces security significantly—anyone on your network can access the dashboard.

## Step 7: Fix Empty Responses / Bot Not Responding

If the dashboard loads but bot doesn't respond:

Check model configuration:

openclaw config get agents.defaults.model

Check API key is configured:

openclaw auth list

Common error in logs:

No API key found for provider "anthropic"

Fix by adding your API key:

openclaw auth add anthropic YOUR_API_KEY

If using OpenRouter, make sure your model is explicitly set:

{  "agents": {    "defaults": {      "model": {        "primary": "openrouter/anthropic/claude-sonnet-4"      }    }  }}

## Step 8: TUI Reconnection After Sleep/Network Drop

The TUI should auto-reconnect when network returns. If it doesn't:

# Just restart TUI (not the gateway)openclaw tui

The Gateway keeps running through sleep—only the TUI connection drops. Check Gateway is still alive:

openclaw gateway status

## Step 9: Messages Show in Logs but Not UI

If tool calls work but final messages don't appear:

This can happen when the response format is: message → tool call → message

The final message may be lost. Workarounds:

1. Check if it appears in openclaw logs --follow

2. Try the web dashboard instead of Discord/TUI

3. This may be a known issue with interleaved tool calls—check GitHub issues