OpenClaw Gateway Port 18789 Error: Complete Troubleshooting Guide

The OpenClaw gateway multiplexes WebSocket and HTTP traffic on port 18789 by default. When this port is unavailable or misconfigured, you'll see errors like:

• address already in use :::18789
• Connection refused on port 18789
• RPC probe: failed
• Gateway starts, then immediately exits

Port issues cause 45% of gateway failures, making them the #2 most common OpenClaw error after Node.js version problems.

---

Start Here: Quick Diagnosis

openclaw doctor --fix

This automatically checks port availability, identifies blocking processes, verifies gateway configuration, and tests WebSocket connectivity. It resolves many port issues automatically.

If the issue persists, identify your specific error type below.

---

Error Type 1: Port Already in Use

Error message:

Error: listen EADDRINUSE: address already in use :::18789

Cause: Another process has claimed port 18789.

Most common culprits:

• Old OpenClaw instance that didn't fully shut down (45% of cases)
• Custom development server on a non-standard port (30%)
• Another AI tool using the same port (15%)
• A crashed Node.js script holding the port open (10%)

Fix:

# Find what's holding the port
lsof -i :18789
# Shows: COMMAND, PID, USER, TYPE

# Kill the specific process
kill -9 <PID>

# Restart OpenClaw
openclaw restart

Alternative — change OpenClaw's port:

openclaw config set gateway.port 18790
openclaw restart
# Dashboard is now at http://localhost:18790

---

Error Type 2: Connection Refused

Error message:

Unable to Hatch: Gateway Connection Refused on Port 18789

Cause: The service attempted to start but failed to bind to the port.

Common reasons:

1. Service crashed during startup (check logs for the crash reason)
2. Missing or invalid API keys (most common)
3. Node.js version too old (must be 22+)
4. Firewall blocking localhost connections

Fix:

# Check if OpenClaw is actually running
openclaw status

# If not running, check recent logs for the crash cause
openclaw logs --lines 50

# Most likely: missing API key
export ANTHROPIC_API_KEY=sk-ant-your-key-here
openclaw config set providers.anthropic.apiKey "sk-ant-your-key-here"
openclaw restart

---

Error Type 3: Tailscale VPN Binding Issue

Error message:

Gateway bound to 100.x.x.x instead of 127.0.0.1
WebSocket connection failed

Cause: When Tailscale VPN is active, the gateway sometimes binds to your Tailscale IP (in the 100.x.x.x range) instead of localhost.

Fix:

# Force binding to localhost
openclaw config set gateway.host "127.0.0.1"
openclaw restart

# Alternative: access via Tailscale IP
# Open: http://100.x.x.x:18789

---

Error Type 4: RPC Probe Failed

Error message:

RPC probe: failed - gateway not responding

Cause: Gateway is running but not responding to health checks. Usually an authentication issue.

Fix:

# Test the gateway directly
curl http://localhost:18789/health

# If no response, check for auth errors in logs
openclaw logs | grep "authentication"

# Verify API key is configured
openclaw config get providers.anthropic.apiKey

# Restart gateway only (without restarting the full agent)
openclaw gateway restart

---

Error Type 5: Dashboard Loads Blank or Fails

Symptom: Port 18789 responds, but the browser shows a blank page or connection error.

Cause: WebSocket upgrade failure, often caused by a reverse proxy misconfiguration.

Fix:

# Test WebSocket capability
curl -i -N   -H "Connection: Upgrade"   -H "Upgrade: websocket"   -H "Host: localhost:18789"   http://localhost:18789/ws
# Expected: HTTP/1.1 101 Switching Protocols

If using nginx as a reverse proxy:

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;
}

---

Error Type 6: Works Locally, Fails Remotely

Symptom: http://localhost:18789 works. http://your-server-ip:18789 doesn't.

Cause: By default, the gateway only binds to localhost — a security feature to prevent unintended exposure.

Fix (internal networks only):

# Bind to all interfaces
openclaw config set gateway.host "0.0.0.0"
openclaw restart
# Now accessible at http://your-server-ip:18789

For production: Use a reverse proxy with SSL (nginx, Caddy, Cloudflare) rather than exposing port 18789 directly to the internet.

---

Port Issues Summary

Error	Cause	Fix
EADDRINUSE	Another process has the port	Kill process or change port
Connection refused	Service crashed	Check logs, fix API keys
RPC probe failed	Auth/health check failure	Check API keys, restart gateway
Dashboard blank	WebSocket failure	Check reverse proxy config
Remote access fails	Binding to localhost only	Bind to 0.0.0.0 or use reverse proxy

---

The Zero-Port-Configuration Alternative

Every port error on this page only exists because you're managing your own gateway. NeatClaw's managed hosting eliminates all of it:

• No port 18789 to configure
• No port conflicts possible
• No firewall rules to set
• Access via https://app.neatclaw.com — standard HTTPS, standard port 443

Try NeatClaw free — no port debugging required

---

Sources: OpenClaw Port Not Listening Guide, GitHub Discussion #11508