OpenClaw Gateway Not Starting: How to Fix

The Gateway is the central process — if it won't start, the entire agent is down. Here's a systematic troubleshooting guide.

Step 1: Check the logs. Gateway logs show the exact error that prevented startup. Look for the first error message — subsequent errors are usually cascading failures.

Step 2: Run doctor. The diagnostic tool checks all prerequisites: Node.js version, port availability, config validity, API key status, and disk space.

Common causes:

Port conflict: Another service occupies port 18789. Fix: change the port or stop the conflicting service.

Corrupted config: Invalid JSON in config.json. Fix: run openclaw config validate, or restore from backup (~/.openclaw/config.json.bak).

Node.js version: Gateway requires Node.js 22+. Check with node --version. Fix: update via nvm.

Disk full: Gateway can't write logs or memory files. Free up disk space — Gateway needs at least 100 MB free.

Permission denied: The OpenClaw user can't access required files. Fix: check ownership of ~/.openclaw/ directory.

Crash loop: Gateway starts but immediately crashes. Usually a skill problem. Fix: start in safe mode (openclaw gateway start --safe) which disables all skills, then re-enable them one by one.

If nothing works: backup your data directory, reinstall OpenClaw (your config is preserved), and restart.

# Check Gateway logs
openclaw gateway logs --level error

# Run diagnostics
openclaw doctor

# Start in safe mode (no skills)
openclaw gateway start --safe

# Restart Gateway
openclaw gateway restart