How to Fix "Connection Refused" Errors in OpenClaw

Problem Description

You're trying to start your OpenClaw agent, but you see one of these errors:

• ECONNREFUSED 127.0.0.1:3000
• Error: connect ECONNREFUSED
• Connection refused to localhost:3000

Why This Happens

This is the #1 most common error in OpenClaw setups. It means your client is trying to connect to the agent server, but:

1. The agent isn't running
2. The agent is running on a different port
3. Network interface binding issues (IPv4 vs IPv6)
4. Firewall blocking the connection

Solution 1: Quick Fix (Recommended)

Solution 2: Manual Fix

Step 1: Check if the Agent is Running

First, verify your agent is actually running:

docker ps

You should see a container named openclaw or similar. If not, start your agent:

docker-compose up -d

Step 2: Use 127.0.0.1 Instead of localhost

Node.js v18+ prefers IPv6, which can cause issues. Change your config:

{
  "host": "localhost",
  "port": 3000
}

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

Step 3: Check Firewall Settings

On Windows, ensure port 3000 is allowed:

• Open Windows Defender Firewall
• Click "Advanced settings"
• Add inbound rule for port 3000

Prevention

Avoid this error from the start by using our Config Wizard to generate error-free configs. It automatically:

• Uses 127.0.0.1 instead of localhost
• Validates port numbers
• Checks for common misconfigurations

Last Updated: February 2026 | Time to Fix: 30 seconds (with Local Doctor) or 5-10 minutes (manual)