Why does OpenClaw show ECONNREFUSED?

The target service is not listening on the expected host and port, or access is blocked by firewall/network settings.

What is the fastest fix for localhost connection refused?

Confirm the gateway process is running, then use 127.0.0.1 with the correct port and retry.

Can IPv4 and IPv6 mismatch cause this?

Yes. Using localhost can resolve to IPv6; explicitly using 127.0.0.1 avoids common binding mismatches.

How to Fix "Connection Refused" Errors in OpenClaw

TL;DR - Quick Fix

Use our Local Doctor Tool to auto-diagnose this issue in 30 seconds.

Run Diagnostic Now

Next Step

Fix now, then reduce repeat incidents

If this issue keeps coming back, validate your setup in Doctor first, then harden your config.

Open Doctor Harden Config

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:

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

Solution 1: Quick Fix (Recommended)

Use ClawKit's Local Doctor

Our diagnostic tool automatically checks for this issue and suggests fixes.

Visit Local Doctor

Run npx clawkit-doctor@latest

Follow the auto-fix suggestions

Solution 2: Manual Fix

Step 1: Check if the Agent is Running

First, verify your agent is actually running:

Check running containers

docker ps

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

Start the 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:

❌ Before

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

✅ After

{
  "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

Related Tools

Local Doctor

Auto-diagnose issues

Config Wizard

Generate valid configs

Cost Estimator

Optimize API costs

Persistent Gateway Disconnection

If your Gateway repeatedly disconnects or sessions don't sync across devices, you may be hitting a combination of issues:

Sessions not syncing across devices

Each device maintains its own session state. If you switch devices, start a new session rather than resuming — the old session context may reference a stale WebSocket.

Multiple messages sent at once cause freeze

Sending several messages in rapid succession before the agent responds can create a message ordering conflict. Wait for each response before sending the next message.

State rollback after Gateway restart

The Gateway may lose in-flight messages during a restart. If your agent appears to "forget" recent messages after a restart, this is expected — the messages were in the WebSocket buffer.

Diagnose and restart gateway

openclaw gateway status
openclaw doctor --fix
openclaw gateway restart

Seeing Other Errors Too?

Connection issues often come with these related problems:

Did this guide solve your problem?