Gateway Won't Start: Quick Diagnostics and Fixes

Quick Diagnostics

Start with these commands to understand the issue:

# Check overall status
openclaw status
# Deep diagnostic with probes
openclaw status --deep
# Run repair checks
openclaw doctor

Common Issues and Fixes

"Gateway start blocked: set gateway.mode=local"

Cause: Your config exists but gateway.mode is not set.

Fix Option 1: Run the configuration wizard:

openclaw configure

Fix Option 2: Set directly:

openclaw config set gateway.mode local

Port 18789 Already in Use

Cause: Another process is using the gateway port.

Diagnose:

lsof -nP -iTCP:18789 -sTCP:LISTEN

Fix: Stop the conflicting process, or change the port:

openclaw config set gateway.port 18790

Service Running but Gateway Not Responding

Symptoms: openclaw gateway status shows "Runtime: running" but nothing works.

Check the logs:

# macOS
cat ~/Library/Logs/OpenClaw/gateway.log
# Linux
cat ~/.openclaw/logs/gateway.log

Common causes:

Fix: Reinstall the service:

openclaw gateway install --force

Config Validation Errors

Cause: Malformed JSON in openclaw.json

Diagnose:

# Check config syntax
cat ~/.openclaw/openclaw.json | jq .

Common mistakes:

Service Environment Issues

If commands work in terminal but fail when run by the service:

Cause: The service runs with minimal PATH.

Fix: Add paths to the service environment:

{
  "tools": {
    "exec": {
      "pathPrepend": "/usr/local/bin:/opt/homebrew/bin"
    }
  }
}

Or set environment variables in ~/.openclaw/.env.

Still Stuck?

Contact our team for professional troubleshooting support.