ErrorsTroubleshootingFixes

OpenClaw Errors & Fixes: Complete Troubleshooting Guide

Fix common OpenClaw errors: gateway not running, device token mismatch, channel connection issues, authentication errors, and model API problems.

10 min readLast updated Feb 20, 2026

Stuck?Check the troubleshooting index or ask in Discord.

Overview

This guide covers the most common OpenClaw errors and how to fix them. Find solutions for gateway issues, device token mismatch, authentication errors, channel connection problems, and model API failures.

Most problems can be diagnosed quickly using the built-in troubleshooting commands.

Quick tip

Most issues can be diagnosed by running openclaw doctor. This command checks your configuration and highlights problems.

Useful doctor flags:

openclaw doctor --fix — auto-fix common issues
openclaw doctor --deep — scan for extra gateway installs
openclaw doctor --repair — apply recommended repairs

First Steps: Diagnose the Problem

When something goes wrong, start here. Run these commands in order:

terminal

openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe

What to look for:

Runtime: running — gateway is healthy
RPC probe: ok — can communicate with gateway
Channels: connected/ready — your channels are working

Gateway Not Running

If the gateway won't stay running, here are the common causes:

"Gateway start blocked: set gateway.mode=local"

Add gateway.mode = "local" to your config. If using Podman with the dedicated openclaw user, config lives at ~openclaw/.openclaw/openclaw.json.

"refusing to bind gateway ... without auth"

Non-loopback bind (LAN, Tailscale) requires authentication. Set gateway.auth.token or gateway.auth.password in your config.

"another gateway instance is already listening" / EADDRINUSE

Port conflict. Another process is using the gateway port. Check with lsof -i :18789 or change the port in your config.

Bot Not Responding to Messages

If your channels are connected but the bot won't reply:

Check pairing status

Run openclaw pairing list <channel> to see if senders need approval.

Check group mention settings

Groups require mention by default. Check requireMention and mentionPatterns in your config.

Check allowlists

Verify your channel or user is in the allowlist. Look for blocked or allowlist in logs.

Common log signatures to watch for:

drop guild message (mention required) → message ignored until mentioned
pairing request → sender needs approval
blocked / allowlist → sender/channel filtered by policy

Dashboard/Control UI Won't Connect

Can't access the web interface? Try these checks:

Check gateway status

Run openclaw gateway status to verify the gateway is running.

Check URLs match

Verify the URL you're accessing matches the configured dashboard URL.

Check auth mode

If using authentication, ensure your token/password matches between client and gateway.

"device identity required"

Non-secure context or missing device auth. Make sure you're using HTTPS or the correct local address.

"unauthorized" / reconnect loop

Token or password mismatch between your client and the gateway.

Channel Connection Issues

Telegram, Discord, WhatsApp, etc. won't connect or stay connected:

Check channel status

Run openclaw channels status --probe to see connection state.

Verify credentials

Check your bot tokens and API keys are correct in config or environment variables.

Check permissions

For Discord/Telegram, verify the bot has the required permissions and intents.

Common signatures in logs:

missing_scope → missing channel API permission
not_in_channel → bot not in the channel/group
Forbidden / 401 / 403 → auth/permissions issue

Authentication Errors

"gateway token missing (1008)"

The gateway token isn't configured. Set gateway.auth.token in your config.

API key errors

Check that your ANTHROPIC_API_KEY, OPENAI_API_KEY, or other model provider keys are set correctly in your environment.

After Upgrading: Something Broke

Many issues after upgrades are caused by config drift or stricter defaults. Here's what to check:

1. Auth and URL behavior changed

If gateway.mode=remote, CLI calls may be targeting remote while your local service works fine.

bash

openclaw config get gateway.remote.url
openclaw config get gateway.auth.mode

2. Bind and auth are stricter

Non-loopback binds need auth configured. Check gateway.bind and gateway.auth.token.

3. Pairing and device identity changed

After upgrades, you may need to re-approve pairing requests or device identities. Run openclaw doctor to detect and fix config issues.

bash

openclaw devices list
openclaw pairing list telegram
openclaw pairing list discord

After upgrading, openclaw doctor runs automatic migrations to fix:

Legacy config keys (old schema → new schema)
Config normalization for deprecated values
On-disk state migrations (sessions, agents, WhatsApp auth)
State integrity and permissions checks

Still stuck?

Try reinstalling service metadata: openclaw gateway install --force && openclaw gateway restart

Model/AI Errors

"models: 0" in health check

Your model backend isn't connected. Make sure Ollama, vLLM, or your API provider is running and the MODEL_BACKEND_URL is correct.

Rate limiting errors

You're hitting API rate limits. Check your provider's limits or add retry configuration to your model settings.

Context window exceeded

Conversation too long. Clear session history or reduce contextTokens in your model config.

OAuth/token expiry errors

For Anthropic API, your OAuth token may have expired. Run openclaw doctor to check model auth health and refresh tokens if needed.

Auth profile issues

Check for auth-profile cooldown or disabled states. Some providers have rate limits per profile.