OpenClaw Errors & Fixes

Find solutions to common OpenClaw errors. Gateway issues, authentication problems, configuration errors, and more.

Common Errors

🔑

Gateway Token Missing

"unauthorized: gateway token missing" error

🔐

Device Token Mismatch

Device identity has changed after reinstall

⚙️

gateway.mode=local

Gateway start blocked - set gateway mode

🔒

Unauthorized

Authentication failed - token missing or invalid

📦

EADDRINUSE

Port already in use by another process

🔌

Gateway Connect Failed

Could not connect to gateway

🚫

ECONNREFUSED 18789

Connection refused on port 18789

📡

RPC Probe Failed

Could not reach gateway RPC endpoint

⛔

Access Not Configured

Channel or provider not configured

🔓

Missing Scope

"missing scope: operator read" error

Channel Errors

🔗

Pairing Required

DM sender needs approval

Mention Required

Bot must be mentioned in group

🚫

Channel Forbidden

401/403, not_in_channel errors

⛔

Allowlist Blocked

Sender/channel not permitted

Diagnostic Commands

Most issues can be diagnosed with these commands:

openclaw status

openclaw gateway status

openclaw doctor

openclaw doctor --fix

openclaw logs --follow

openclaw channels list

openclaw models list

openclaw devices list

Related Guides

Getting Started

New to OpenClaw? Start here for the full setup guide.

Common Errors Guide

Deep dive into the most common error scenarios.

Installation

Having trouble installing? Check the setup guides.

Can't Find Your Error?

Search the troubleshooting guide or ask the community.

Full Troubleshooting Ask on Discord