OpenClaw Gateway Not Starting? Here's How to Fix It

The most common OpenClaw issue — and the fastest way to resolve it. Covers macOS, Linux, and Windows.

⚡ Quick Fix — Let AI Handle It

Don't want to debug manually? Run this in your terminal:

npx clawaid

ClawAid auto-diagnoses the root cause and fixes it. Takes ~30 seconds. Free.

Symptoms

Symptom: openclaw status shows "Gateway: not running" or "service not found"

Symptom: openclaw gateway start exits silently or shows "already running" but nothing works

Symptom: Control UI says "Connecting..." forever, never loads

Symptom: Gateway starts but crashes within seconds (check openclaw logs --follow)

Common Causes & Manual Fixes

1. Port Conflict (Most Common)

Cause: Another process is using port 18789 (or your configured port)

Check what's using the port:

lsof -i :18789

If another process is occupying it, kill it or change the OpenClaw port in your config:

openclaw config set gateway.port 18790
openclaw gateway restart

2. Corrupt Config File

Cause: ~/.openclaw/openclaw.json has invalid JSON or unknown fields

Validate your config:

openclaw doctor

If it reports config errors, you can reset to defaults:

# Back up first
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak

# Re-run setup
openclaw setup

3. Stale LaunchAgent (macOS)

Cause: The LaunchAgent plist is outdated after an OpenClaw update

# Unload the old agent
launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/com.openclaw.gateway.plist

# Reinstall
openclaw gateway install
openclaw gateway start

4. Node.js Version Mismatch

Cause: OpenClaw requires Node.js 18+. Older versions cause silent crashes.

node --version
# If below v18, upgrade Node.js first

5. Proxy / Network Environment Variables

Cause: HTTP_PROXY or HTTPS_PROXY variables point to a dead proxy

# Check current proxy settings
echo $HTTP_PROXY $HTTPS_PROXY

# If set but proxy isn't running, unset them
unset HTTP_PROXY HTTPS_PROXY
openclaw gateway restart

6. Wrong Model ID Causing HTTP 400

Cause: Your configured model doesn't exist at your provider, causing the gateway to fail on every request

# Check current model
openclaw config get models.primary

# Set a known-good model
openclaw config set models.primary openai/gpt-4o

Still Not Working?

🤖 Let ClawAid Diagnose It Automatically

ClawAid reads your actual system state — logs, config, processes, network — and figures out the root cause. It handles edge cases that manual debugging misses.