🦞OpenClaw Guide
Dashboard

Dashboard & Web UI — Setup & Troubleshooting

Get the OpenClaw web dashboard working, fix connection errors, resolve white-on-white text, and access the UI remotely from VMs or other machines.

⚠️ The Problem

The web dashboard at http://127.0.0.1:18789 won't load, shows connection refused, or WebSocket errors like '1006 abnormal closure'. The TUI may have unreadable white-on-white text, or messages appear in logs but not in the interface. Remote access from VMs or other machines requires HTTPS or shows 'non-secure context' errors.

🔍 Why This Happens

Dashboard issues stem from: (1) Gateway not running—the web UI is served by the Gateway process. (2) Port 18789 not bound or blocked by firewall. (3) WebSocket connection drops due to network interruption or gateway crash. (4) TUI color scheme conflicts with terminal theme settings. (5) Remote access requires HTTPS due to WebCrypto security requirements—browsers block non-localhost HTTP connections. (6) Empty responses often mean the model isn't configured correctly or API keys are missing.

✅ The Fix

Step 1: Verify Gateway is Running

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

bash
openclaw gateway status

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

bash
openclaw gateway start

Or run in foreground to see errors:

bash
openclaw gateway

Step 2: Check Port 18789 is Actually Listening

On macOS/Linux:

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

On Windows PowerShell:

powershell
Get-NetTCPConnection -LocalPort 18789

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

bash
openclaw logs | tail -50

Step 3: Fix 'command not found' After Install

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

bash
# 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:

bash
source ~/.bashrc# orsource ~/.profile

Step 4: Fix WebSocket 1006 Abnormal Closure

This error means the WebSocket disconnected unexpectedly:

bash
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
  1. Firewall blocking localhost — Temporarily disable to test:
  • Windows: Disable Windows Defender Firewall
  • macOS: Check System Preferences → Security & Privacy → Firewall
  1. 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\
  1. 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:

bash
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:

bash
# 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)

bash
# 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:

json
{  "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:

bash
openclaw config get agents.defaults.model

Check API key is configured:

bash
openclaw auth list

Common error in logs:

bash
No API key found for provider "anthropic"

Fix by adding your API key:

bash
openclaw auth add anthropic YOUR_API_KEY

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

json
{  "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:

bash
# Just restart TUI (not the gateway)openclaw tui

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

bash
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
  1. Try the web dashboard instead of Discord/TUI
  1. This may be a known issue with interleaved tool calls—check GitHub issues

🔥 Your AI should run your business, not just answer questions.

We'll show you how.Free to join.

Join Vibe Combinator →

📋 Quick Commands

CommandDescription
openclaw gateway statusCheck if Gateway is running and on which port
openclaw gateway startStart the Gateway as a background daemon
openclaw gateway restartRestart the Gateway (fixes most connection issues)
openclaw gatewayRun Gateway in foreground to see startup errors
openclaw tuiLaunch the Terminal User Interface
openclaw logs --followWatch live logs for errors
openclaw logs | tail -50View last 50 lines of logs
openclaw auth listShow configured API keys/providers
openclaw auth add PROVIDER API_KEYAdd an API key for a provider
lsof -i :18789Check what's listening on port 18789 (macOS/Linux)
ssh -L 18789:127.0.0.1:18789 user@hostCreate SSH tunnel for remote dashboard access

Related Issues

    📚 You Might Also Like

    Blog

    OpenClaw Gateway Token Security: The Master Key You're Probably Mishandling

    Your OpenClaw gateway token is the master key to your entire setup. Anyone who has it can access your dashboard, read your conversations, run commands throug...

    Guide

    How to Create an AI Research Assistant

    Let AI search the web, summarize articles, and compile research for you.

    Use Case

    AI Assistant for Photographers

    More time shooting. Less time on client communication and business admin.

    Integration

    Discord

    Add your AI assistant to Discord servers and DMs. Get help, manage tasks, and run automations directly from your Discord channels.

    🐙 Your AI should run your business.

    Weekly live builds + template vault. We'll show you how to make AI actually work.Free to join.

    Join Vibe Combinator →