OpenClaw Gateway Won't Start — Troubleshooting

OpenClaw FAQ

If the gateway won't start, check for port conflicts, Node.js version, and config errors. Use openclaw gateway --force to kill existing processes.

Common Causes & Fixes

1. Port Already in Use

Another process is using port 18789. Use --force to kill it and start fresh.

2. Wrong Node.js Version

OpenClaw requires Node.js 22+. Check with node --version.

3. Config Errors

Invalid JSON in ~/.openclaw/openclaw.json. Validate your config file.

4. Permission Issues

On Linux/macOS, ensure you have permission to bind to the port and access the config directory.

5. Missing Dependencies

Run npm install -g openclaw@latest to ensure all dependencies are installed.

# Force start (kills existing process)
openclaw gateway --force

# Check Node version
node --version  # Must be 22+

# Start with verbose logging
openclaw gateway --verbose

# Check for port conflicts
lsof -i :18789  # macOS/Linux
netstat -ano | findstr 18789  # Windows

Try OpenClaw — free and open source

Sign up and launch your AI agent in under a minute. No credit card required.

Get Started Free →

Related