Symptom

When executing the openclaw start or openclaw serve command, the program fails immediately and outputs the following error message:

Error: listen EADDRINUSE :::3000
    at Server.setupListenHandler [as _listeningListener] (node:net:1465:14)
    at ListenAndServe (node:net:1398:7)
    at ListenAndServe (net:http:1801:9)
    ...

This indicates that the port OpenClaw is trying to bind to (default 3000) is already occupied by another process.

Root Cause Analysis

  1. Port Conflict: Another service on the local computer (such as a Node.js app, Apache, Nginx, or another OpenClaw instance) is already using port 3000.
  2. Zombie Process: A previous OpenClaw process might not have terminated properly and is still holding the port.
  3. Configuration Error: The user might have set an already occupied port in the configuration file.

Solution

Method 1: Find and terminate the process occupying the port

macOS / Linux:

1
2
3
4
5
6
7
8

# Find the process occupying port 3000
lsof -ti:3000

# Terminate the process (replace PID with the actual process ID)
kill -9 <PID>

# Or directly terminate all related processes
killall -9 node

Windows:

1
2
3
4
5

# Find the process occupying port 3000
netstat -ano | findstr :3000

# Terminate the process by PID (replace PID with the actual value)
taskkill /F /PID <PID>

Method 2: Specify a different port using the configuration file

Create or modify openclaw.config.js in the project root directory:

1
2
3
4
5

module.exports = {
  server: {
    port: 3001  // Use another available port
  }
}

Then restart:

1

openclaw start

Method 3: Temporarily specify a port using command-line arguments

1

openclaw start --port 3002

Method 4: Use Environment Variables

1
2
3
4
5
6
7

# macOS / Linux
export OPENCLAW_PORT=3003
openclaw start

# Windows (PowerShell)
$env:OPENCLAW_PORT=3003
openclaw start

Prevention

  1. Clean up residual processes using pkill: Execute pkill -f openclaw before starting to ensure no residual processes are left.
  2. Use a port checking script: Create a pre-start checking script.
  3. Configure health checks: Add port availability checks in openclaw.config.js.

Additional Information

  • OpenClaw’s default port can be modified in the server.port field of the configuration file.
  • Dynamically specifying the port via the OPENCLAW_PORT environment variable is supported.
  • It is recommended to use unregistered ports in the range 3000-9999.