Need help? Try openclaw doctor --fix first →
Troubleshooting

OpenClaw Not Working? How to Fix Every Common Error (2026)

A complete troubleshooting guide for OpenClaw. Fix authentication errors, rate limits, context length issues, messaging channel failures, Docker problems, and installation failures -- with the exact commands to run.

February 11, 2026 · Espen · 12 min read

Run openclaw doctor --fix first. This single command auto-detects and repairs the most common OpenClaw issues -- broken permissions, missing directories, config errors, and connectivity failures -- in about 10 seconds. As of February 2026, it resolves roughly 70% of problems without any manual intervention. (Source: OpenClaw GitHub issue tracker, community-reported resolution rates)

If openclaw doctor --fix does not solve your problem, this guide covers every common error with specific, copy-paste fixes. Find your error below and follow the steps.

Jump to: Quick Fix · Authentication (401) · Rate Limits (429) · Context Length · Messaging Channels · Gateway & Ports · Performance · Docker · Installation · When It's Not Your Fault · FAQ

New to OpenClaw? Read What Is OpenClaw? for the overview, or How to Install OpenClaw for setup instructions.

Quick Fix: openclaw doctor

Before diving into specific errors, run the built-in diagnostic tool:

openclaw doctor --fix

The --fix flag tells it to automatically repair issues instead of just reporting them. Here is what it checks and fixes:

# Example output with auto-fix:
OpenClaw Doctor v1.4.2 (--fix mode)
------------------------------
Config ............. FIXED: repaired YAML indentation on line 12
Permissions ........ OK
Directories ........ OK
Model provider ..... anthropic OK
  API key .......... OK (tested)
Daemon ............. FIXED: restarted (was stopped)
Channels:
  telegram ......... OK
  whatsapp ......... WARN: session expired, re-scan needed
------------------------------
Fixed 2 issues. 1 warning requires manual action.

If openclaw doctor --fix resolves your issue, you are done. If not, find your specific error below.

Authentication Errors (401 Unauthorized)

A 401 error means your AI model API key is invalid, expired, or misconfigured. This is the single most common OpenClaw error.

Symptoms

Fix

# Re-authenticate with your provider
openclaw models auth setup-token

# When prompted, paste your new API key
# Then verify it works:
openclaw models test

If openclaw models test returns a successful response, your key is working. If it still fails, check these common causes:

# Check the config file directly
cat ~/.openclaw/config.yaml | grep apiKey

# Should show something like:
#   apiKey: sk-ant-api03-xxxxxxxxxxxx
Test keys outside OpenClaw. If you suspect a bad key, test it directly with curl: curl -H "x-api-key: YOUR_KEY" https://api.anthropic.com/v1/messages -d '{"model":"claude-sonnet-4-5","max_tokens":10,"messages":[{"role":"user","content":"hi"}]}'. If this returns a valid response, the key is fine and the problem is in OpenClaw's configuration.

Rate Limits (429 Too Many Requests)

A 429 error means you are sending requests faster than your AI provider allows. This typically happens when OpenClaw handles many messages simultaneously or when you are on a lower-tier API plan.

Immediate Fix

Wait 60 seconds and try again. Most rate limits reset within one minute. (Source: Anthropic API documentation, rate limit reset intervals)

Permanent Fix: Configure a Fallback Model

Set up a secondary model that OpenClaw switches to automatically when the primary model is rate-limited:

# Set a fallback model
openclaw config set model.fallback openrouter/anthropic/claude-haiku-4.5

# Or set explicit rate limit handling
openclaw config set model.rateLimitRetry true
openclaw config set model.rateLimitDelay 5000

With rateLimitRetry enabled, OpenClaw waits 5 seconds (5000ms) and retries automatically instead of failing. With a fallback model configured, it switches to the cheaper/faster model during rate limit periods.

Root Causes

Context Length Errors

This error occurs when the input (conversation history + memory + system prompt) exceeds the model's maximum token limit. For example, sending 38,000 tokens to a model with a 32,000-token limit.

Symptoms

Fix Option 1: Switch to a Larger Context Model

# Claude Sonnet 4.5 supports 200K tokens
openclaw config set model.name claude-sonnet-4-5

# GPT-4o supports 128K tokens
openclaw config set model.name gpt-4o

Fix Option 2: Reduce Loaded Skills

Every loaded skill adds to the context. If you have 15+ skills active, they can consume 10,000-20,000 tokens before any conversation even starts.

# Check active skills and their token cost
openclaw skills list --verbose

# Disable unused skills
openclaw skills disable skill-name-here

Fix Option 3: Trim Memory Files

Large memory files eat into your context budget. Check your total memory size:

openclaw memory status

# If memory is consuming >40% of context, prune it:
# Edit ~/.openclaw/MEMORY.md and remove outdated entries
Need help choosing a model? See Best Models for OpenClaw for context size comparisons.

Messaging Channel Issues

Telegram Not Responding

If your Telegram bot is not replying to messages, check these in order:

  1. Verify the bot token. Tokens can be revoked in @BotFather. Run openclaw channels test telegram to check connectivity.
  2. Ensure mentions are enabled. In group chats, bots only respond to @mentions by default. In BotFather, disable "Group Privacy" mode if you want the bot to read all messages.
  3. Check that the bot received /start. New Telegram bots require the user to send /start before they can respond. This is a Telegram requirement, not an OpenClaw one.
  4. Check the webhook URL. If you are running OpenClaw behind a reverse proxy, verify the webhook URL is accessible from the internet: openclaw channels config telegram --show.
# Full Telegram diagnostic
openclaw channels test telegram

# Expected output:
# Token: valid
# Bot info: @YourBotName
# Webhook: active (https://...)
# Last message: 2 minutes ago

WhatsApp Connection Drops

WhatsApp Web sessions expire after approximately 14 days. This is a WhatsApp platform limitation, not an OpenClaw bug.

Fix: Re-scan the QR code:

openclaw channels login

For better stability, consider these options:

WhatsApp may restrict automated accounts. WhatsApp's Terms of Service do not officially support automation via the linked device method. For business use or high-volume messaging, the official WhatsApp Business API is the only compliant option.

Gateway & Port Problems

OpenClaw's gateway listens on port 3456 by default. If this port is blocked or already in use, the gateway will not start.

Check What is Using the Port

# Check if port 3456 is in use
lsof -i :3456

# Example output:
# COMMAND   PID   USER   FD   TYPE  DEVICE SIZE/OFF NODE NAME
# node    12345  user   22u  IPv4  0x1234      TCP *:3456 (LISTEN)

Fix: Change the Port

# Switch to a different port
openclaw config set gateway.port 3457

# Restart the daemon
openclaw daemon restart

Fix: Firewall Rules

If the port is not in use but the gateway still fails, your firewall may be blocking it:

Cloud server users. If you are running OpenClaw on a VPS (AWS, DigitalOcean, etc.), check your cloud provider's security group or firewall rules in addition to the OS firewall. Both need to allow traffic on the gateway port.

Performance Issues

Too Many Skills Loaded

Each active skill adds to the system prompt, consuming tokens and increasing latency. If you have 20+ skills active, response times can noticeably degrade.

# See all active skills and their token cost
openclaw skills list --verbose

# Example output:
# ACTIVE SKILLS (23):
#   calendar       ~ 800 tokens
#   web-search     ~ 1,200 tokens
#   code-runner    ~ 950 tokens
#   ...
#   TOTAL: ~18,400 tokens (9.2% of context)

# Disable skills you don't use
openclaw skills disable skill-name

A good rule of thumb: keep active skills under 10. Disable anything you do not use at least weekly. You can always re-enable a skill when needed with openclaw skills enable skill-name.

Slow Response Times

If OpenClaw responds but takes 15-30+ seconds, the bottleneck is usually one of these:

Docker Troubleshooting

Container Keeps Crashing

# Check container logs
docker logs openclaw --tail 100

# Check container status
docker ps -a | grep openclaw

Common Docker issues:

# Correct Docker Compose setup with restart policy and volumes:
services:
  openclaw:
    image: openclaw/openclaw:latest
    restart: unless-stopped
    volumes:
      - ./data:/root/.openclaw
    ports:
      - "3456:3456"
    environment:
      - NODE_ENV=production

Viewing Logs

# Follow logs in real-time
docker logs -f openclaw

# Search logs for errors
docker logs openclaw 2>&1 | grep -i error

Installation Failures

Mac: Xcode Command Line Tools Missing

Some npm packages require native compilation. On Mac, this needs the Xcode Command Line Tools:

xcode-select --install

Follow the prompt to install. This downloads about 1.5 GB and takes 5-10 minutes. After installation, retry the OpenClaw install.

Windows: WSL2 Not Installed

OpenClaw does not run natively on Windows. You need WSL2 (Windows Subsystem for Linux):

# Open PowerShell as Administrator
wsl --install

# Restart your computer
# Then open the Ubuntu terminal and install OpenClaw:
curl -fsSL https://openclaw.ai/install.sh | bash

Linux: Missing build-essential

On Debian/Ubuntu systems, native module compilation requires build tools:

sudo apt update && sudo apt install -y build-essential

Then retry the OpenClaw installation.

Node.js Version Too Old

OpenClaw requires Node.js 18+. As of February 2026, Node.js 22 LTS is recommended.

# Check your version
node --version

# Upgrade on Mac
brew install node@22

# Upgrade on Ubuntu/Debian
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs

API Key Configuration

Keys live in ~/.openclaw/config.yaml. You can set them via CLI or edit the file directly:

# Via CLI (recommended)
openclaw models auth setup-token

# Or test that your current key works
openclaw models test

# Example test output:
# Provider: anthropic
# Model: claude-sonnet-4-5
# API Key: sk-ant-***...***
# Test response: "Hello! I'm working correctly."
# Latency: 1.2s
# Status: OK

When It's Not Your Fault

Not every problem is a misconfiguration. OpenClaw is actively developed software that pushes updates frequently, and rapid updates occasionally introduce regressions.

Before spending hours debugging, check these sources:

Downgrading to a stable version. If a recent update broke something, pin to the last known stable version: npm install -g openclaw@1.3.12 (replace with the actual version number). Then wait for a patch release before upgrading again. You can check available versions with npm view openclaw versions.

Quick Reference: Error-to-Fix Table

Error Likely Cause Fix Command
401 Unauthorized Bad API key openclaw models auth setup-token
429 Rate Limited Too many requests Wait 60s, or add fallback model
context_length_exceeded Input too large Switch to larger model or reduce skills
Telegram silent Bot needs /start Send /start to bot in Telegram
WhatsApp disconnected Session expired (~14 days) openclaw channels login
Port 3456 in use Another process on port openclaw config set gateway.port 3457
Docker crash loop Missing restart policy Add restart: unless-stopped
command not found PATH not set export PATH="$PATH:$(npm config get prefix)/bin"
Node.js too old Version <18 brew install node@22

FAQ

Why is OpenClaw not responding to messages?

OpenClaw (created by Peter Steinberger, formerly Clawdbot, then Moltbot) may not respond because the daemon is not running, your API key is invalid, or the messaging channel is disconnected. Run openclaw doctor --fix first -- it auto-detects and repairs the most common issues in about 10 seconds. As of February 2026, this resolves roughly 70% of problems automatically.

How do I fix the 401 Unauthorized error?

Run openclaw models auth setup-token and enter a fresh API key. Then verify with openclaw models test. Common causes: expired trial keys, copy-paste errors with extra whitespace, and using a key from the wrong provider (e.g., an Anthropic key with the OpenAI provider setting).

How do I fix the 429 Rate Limited error?

Wait 60 seconds and try again. For a permanent fix, configure a fallback model: openclaw config set model.fallback openrouter/anthropic/claude-haiku-4.5. You can also enable automatic retries: openclaw config set model.rateLimitRetry true.

Why does OpenClaw keep disconnecting from WhatsApp?

WhatsApp Web sessions expire after approximately 14 days. This is a WhatsApp limitation, not an OpenClaw bug. Run openclaw channels login and re-scan the QR code. For more stability, use the WhatsApp Business API instead of the linked device method.

What Node.js version does OpenClaw require?

Node.js 18 or higher. As of February 2026, Node.js 22 LTS is recommended. Check with node --version. On Mac, upgrade with brew install node@22. The one-line OpenClaw installer handles Node.js installation automatically.

Related Guides

Install Your Chief AI Officer

Watch a hands-on walkthrough where I set up OpenClaw from scratch, troubleshoot common errors, and build a working AI assistant.

Get the Free Blueprint href="/blueprint">Watch the Free Setup Video →rarr;

Related Articles

How to Install OpenClaw: Step-by-Step

12 min read

Best Models for OpenClaw (2026)

10 min read

OpenClaw WhatsApp & Telegram Setup

10 min read