Troubleshooting Gateway Wont Start

Fixing Gateway Startup Issues

The gateway is the core service that connects OpenClaw to your messaging channels. If it fails to start, your agent cannot receive or send messages. Here are the most common causes and fixes.

Common Error: Port Already in Use

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

Fix: Another process is using port 3000. Find and stop it:

# Windows
netstat -ano | findstr :3000
taskkill /PID [PID_NUMBER] /F

# macOS/Linux
lsof -i :3000
kill -9 [PID]

# Or change OpenClaw's port
openclaw config set server.port 3001

Common Error: Node.js Version Too Old

Error: Node.js 22 or higher is required

Fix: Upgrade Node.js to version 22 or higher:

# Using nvm (recommended)
nvm install 22
nvm use 22

# Verify
node --version

Common Error: Missing Configuration

Error: Configuration file not found

Fix: Run the onboarding wizard to generate your configuration:

openclaw onboard

Common Error: API Key Invalid

Error: Authentication failed for provider [openai]

Fix: Verify your API key is valid and has sufficient credits. Re-enter it with:

openclaw config set providers.openai.apiKey "sk-your-new-key"

Still Not Working?

Run full diagnostics: openclaw doctor and check the diagnostics guide for detailed troubleshooting.