Resolving OpenClaw Port Conflicts and Gateway Startup Failures

Problem Description

When starting the OpenClaw gateway, you encounter a port-in-use error:

[openclaw:server] Error: listen EADDRINUSE: address already in use :::3000
    at Server.setupListenHandle [as _listen2] (node:net:1817:16)
    at listenInCluster (node:net:1865:12)
    at Server.listen (node:net:1964:7)

Or the service starts but the management dashboard is inaccessible:

[openclaw:server] Server started on port 3000
$ curl http://localhost:3000/health
curl: (7) Failed to connect to localhost port 3000: Connection refused

OpenClaw uses port 3000 by default for its HTTP gateway service, which receives Webhook callbacks, serves the management dashboard, and provides the REST API. If that port is already occupied by another program, OpenClaw cannot start.

Diagnostic Steps

Check Port Usage

Linux / macOS:

lsof -i :3000

Example output:

COMMAND   PID   USER   FD   TYPE DEVICE SIZE/OFF NODE NAME
node    12345   user   22u  IPv6 123456      0t0  TCP *:3000 (LISTEN)

Or use the ss command:

ss -tlnp | grep 3000

Windows:

netstat -ano | findstr :3000

Example output:

TCP    0.0.0.0:3000    0.0.0.0:0    LISTENING    12345

Find the process occupying the port by PID:

tasklist /FI "PID eq 12345"

Check for Leftover OpenClaw Instances

ps aux | grep openclaw

If you find an old OpenClaw process still running, it may not have been shut down properly.

Check OpenClaw's Configured Port

cat ~/.openclaw/openclaw.json | grep port

Confirm the port number set in the configuration file.

Solutions

Option 1: Stop the Process Occupying the Port

If the port is occupied by an old OpenClaw instance:

openclaw stop

If the stop command doesn't work, forcefully terminate the process:

Linux / macOS:

# Find and terminate the process occupying port 3000
kill $(lsof -t -i :3000)

# If a normal kill doesn't work
kill -9 $(lsof -t -i :3000)

Windows:

# Find the PID
netstat -ano | findstr :3000

# Terminate the process (replace PID)
taskkill /PID 12345 /F

After terminating the process, restart OpenClaw:

openclaw start

Option 2: Change the OpenClaw Port

If port 3000 is occupied by another important service (such as a React dev server), change OpenClaw's port configuration:

Specify the port via command-line argument:

openclaw start --port 3001

Or modify the config file ~/.openclaw/openclaw.json:

{
  "server": {
    "port": 3001,
    "host": "0.0.0.0"
  }
}

Or set it via environment variable:

OPENCLAW_PORT=3001 openclaw start

Note: If you use Webhook-based message reception (e.g., Telegram Webhook), you'll also need to update the port number in the Webhook URL after changing the port.

Option 3: Fix Firewall Blocking

If the port isn't occupied by another program but connections still fail, a firewall may be blocking the connection.

Linux (ufw):

sudo ufw allow 3000/tcp
sudo ufw status

Linux (firewalld):

sudo firewall-cmd --add-port=3000/tcp --permanent
sudo firewall-cmd --reload

Windows:

New-NetFirewallRule -DisplayName "OpenClaw" -Direction Inbound -Port 3000 -Protocol TCP -Action Allow

Option 4: Configure a Reverse Proxy

In production environments, it's recommended to use Nginx or Caddy as a reverse proxy. Have OpenClaw listen on a local port and expose standard ports 80/443 externally through the reverse proxy:

Nginx configuration example:

server {
    listen 80;
    server_name bot.example.com;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # WebSocket support
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

Caddy configuration example (automatic HTTPS):

bot.example.com {
    reverse_proxy localhost:3000
}

When using a reverse proxy, OpenClaw can listen on 127.0.0.1:3000 (local access only) for better security:

{
  "server": {
    "port": 3000,
    "host": "127.0.0.1"
  }
}

Option 5: Use a Unix Socket (Linux/macOS)

If port conflicts are a recurring problem, you can have OpenClaw use a Unix Socket instead of a TCP port:

{
  "server": {
    "socket": "/tmp/openclaw.sock"
  }
}

Update the Nginx configuration accordingly:

location / {
    proxy_pass http://unix:/tmp/openclaw.sock;
}

This completely eliminates the possibility of port conflicts.

Verifying the Fix

After starting, verify the service is running properly:

openclaw start

# Check service health status
curl http://localhost:3000/health

# Expected output
# {"status":"ok","version":"x.x.x","uptime":5}

If you changed the port, replace 3000 with the new port number in the commands. Confirm the management dashboard is accessible by opening http://localhost:3000 (or your configured port) in a browser.