The Problem
You see an error like:
Error: connect ECONNREFUSED 127.0.0.1:18789
Or:
Connection refused: Could not connect to gateway
Or the OpenClaw dashboard at http://127.0.0.1:18789/ does not load.
What This Means
The gateway is the core of OpenClaw. It handles all message routing between your chat apps and AI. If it is not running or cannot accept connections, nothing works.
Quick Diagnosis
Run this command to check the gateway status:
openclaw status
Expected Result
Gateway: running Port: 18789 Auth: configured
If you see Gateway: stopped or an error, the gateway is not running.
Common Causes and Solutions
Cause 1: Gateway Not Started
The most common cause is simply that the gateway is not running.
Solution:
Start the gateway:
openclaw gateway --daemon
Expected Result
Gateway started successfully Listening on 127.0.0.1:18789
If you want to see logs in real-time (for debugging):
openclaw gateway
Press Ctrl+C to stop when done.
Cause 2: Port Already in Use
Another application might be using port 18789.
Check what is using the port:
On macOS/Linux:
lsof -i :18789
On Windows (PowerShell):
netstat -ano | findstr 18789
Solutions:
Option A: Stop the other application
If it is an old OpenClaw process:
Find and kill the process
pkill -f openclaw
Then start the gateway again.
Option B: Use a different port
openclaw config set gateway.port 18790
openclaw gateway restart
Remember to use the new port when accessing the dashboard: http://127.0.0.1:18790/
Cause 3: Daemon Not Installed
If OpenClaw should start automatically but does not:
openclaw daemon status
If the daemon is not installed:
openclaw daemon install
openclaw daemon start
Cause 4: Firewall Blocking Connections
Your firewall might block local connections.
On macOS:
- Go to System Settings > Network > Firewall
- Click Firewall Options
- Make sure Node.js is not blocked
On Windows:
- Open Windows Defender Firewall
- Click "Allow an app through firewall"
- Find Node.js and ensure it has access
On Linux (ufw):
Check if firewall is blocking
sudo ufw status
Allow local connections (usually not needed)
sudo ufw allow from 127.0.0.1 to any port 18789
Cause 5: Node.js Issues
The gateway needs Node.js to run. Check if Node.js is working:
node --version
Expected Result
v22.x.x
If Node.js is not found or shows an old version, reinstall it:
Cause 6: Corrupted Installation
If the installation is corrupted:
Reinstall OpenClaw
npm uninstall -g openclaw
npm install -g openclaw
Restart the gateway
openclaw gateway --daemon
Cause 7: Configuration Error
A bad configuration file can prevent the gateway from starting.
Check the logs for errors:
openclaw logs --limit 50
Reset configuration if needed:
This Resets Your Settings
This will remove your current configuration. Back up ~/.openclaw/ first if you have important settings.
Backup (optional)
cp -r ~/.openclaw ~/.openclaw-backup
Reset
rm ~/.openclaw/openclaw.json
openclaw onboard
Advanced Troubleshooting
Check Detailed Logs
openclaw logs --limit 100
Look for error messages that explain why the gateway failed to start.
Run Gateway in Foreground
Running in the foreground shows all output directly:
openclaw gateway --verbose
Watch for any errors as it starts up. Press Ctrl+C to stop.
Verify Network Configuration
openclaw config get gateway.bind_address
openclaw config get gateway.port
Expected Result
127.0.0.1 18789
If these are wrong, reset them:
openclaw config set gateway.bind_address 127.0.0.1
openclaw config set gateway.port 18789
Check System Resources
Low memory or disk space can cause issues:
On macOS/Linux:
Check memory
free -h
Check disk space
df -h
On Windows:
Check memory
Get-Process | Sort-Object WorkingSet -Descending | Select-Object -First 10
Check disk space
Get-PSDrive C
Platform-Specific Issues
Windows (WSL2)
WSL2 not running:
Make sure WSL2 is running:
wsl --status
If not running, start it:
wsl
WSL2 network issues:
Sometimes WSL2 networking needs a reset:
wsl --shutdown
wsl
macOS
Permission issues after update:
sudo chown -R $(whoami) ~/.npm
sudo chown -R $(whoami) ~/.openclaw
Linux
Systemd service not starting:
systemctl --user status openclaw
journalctl --user -u openclaw -n 50
Still Not Working?
If none of the above solutions work:
- Gather diagnostic information:
openclaw status
openclaw --version
node --version
openclaw logs --tail 100
-
Check the official documentation at docs.openclaw.ai
-
Search for your specific error message in the OpenClaw GitHub issues
-
Try a fresh installation:
Complete cleanup
npm uninstall -g openclaw
rm -rf ~/.openclaw
Fresh install
npm install -g openclaw
openclaw onboard --install-daemon
Prevention Tips
- Use the daemon for automatic restarts:
openclaw daemon install
- Monitor the gateway periodically:
openclaw health
- Keep OpenClaw updated:
openclaw update
Need Help?
If you run into problems not covered here, check our Troubleshooting guide or visit the official OpenClaw documentation.
Last updated: February 3, 2026 | Found an error? Contact us