OpenClaw Error Reference 2026

A categorized reference of the most common OpenClaw errors, their root causes, and verified fixes. Each entry links to a full solution page with copy-paste steps.

Gateway Errors

The OpenClaw gateway is the most failure-prone component because it bridges your agent to external APIs, channels, and tools simultaneously.

Gateway crashes silently (no error in logs)

Symptom: Gateway process stops accepting connections but returns no error. openclaw status shows running; channels show disconnected.

Root cause: Memory pressure or an unhandled exception in a channel handler causes the gateway to enter a zombie state — alive but not processing.

Fix: Add health check polling and automatic restart on unresponsive gateway:

# Check if gateway is actually responsive
curl -s --max-time 5 http://localhost:9991/health || openclaw gateway restart

Add to cron or systemd watchdog. Full solution →

Gateway WebSocket handshake timeout (silent 1000 close)

Symptom: CLI commands fail with silent close code 1000. Gateway logs show no error.

Root cause: The default CLI WebSocket handshake timeout is 3 seconds (DEFAULT_HANDSHAKE_TIMEOUT_MS = 3e3). On loaded gateways (600MB+ RAM, 80+ tasks), this is consistently too short.

Fix: Patch to 15s via a startup script that survives updates. Full solution →

Auth & Credential Errors

401 on every request despite valid API key

Symptom: All API calls return 401 even after re-entering credentials. Key works in curl directly.

Root cause: OpenClaw caches auth headers at gateway startup. Rotating a key requires a gateway restart, not just a settings update.

Fix:

openclaw gateway restart

If still failing, check that the key in ~/.openclaw/credentials.json matches what was just set. Full solutions →

OAuth refresh token silently discarded

Symptom: Agent loses OAuth access after ~1 hour. Refresh token present but not used.

Root cause: Some OAuth providers return a new refresh token on each refresh. OpenClaw only stores the original. The stored refresh token becomes invalid after first use.

Fix: Enable token rotation in config:

oauth:
  rotate_refresh_token: true
  persist_path: ~/.openclaw/oauth-tokens.json

Full solution →

Rate Limit Errors

Anthropic API 429 — too many requests

Symptom: Error 429: rate_limit_error from Anthropic API. Happens during peak usage or batch operations.

Root cause: Tier-based rate limits (RPM/TPM). Default OpenClaw config does not implement exponential backoff.

Fix: Add retry with exponential backoff:

# openclaw.config.yaml
providers:
  anthropic:
    retry:
      max_attempts: 5
      initial_delay_ms: 2000
      backoff_multiplier: 2.0
      jitter: true

Full solutions →

Anthropic API 529 — overloaded, model unavailable

Symptom: Error 529: overloaded_error. Typically during peak hours (14:00–18:00 UTC).

Root cause: Provider-side capacity constraint. No client-side fix.

Fix: Add automatic model fallback:

providers:
  anthropic:
    fallback_model: claude-sonnet-4-5
    on_errors: [529, 503]

Sonnet availability is higher during Opus overload periods. Full solution →

Session & Context Errors

Agent forgets context after gateway restart

Symptom: Agent behaves as if starting fresh after any restart. Previous decisions and context gone.

Root cause: Conversation state stored in memory, not persisted to disk. Gateway restart = full memory wipe.

Fix: Enable session persistence:

memory:
  persist: true
  storage: ~/.openclaw/sessions/
  compress: true

Then explicitly save checkpoints at task boundaries. Full solutions →

Context window overflow on long sessions

Symptom: Error: context_length_exceeded or model truncates early responses. Happens after 20–30 message exchanges.

Root cause: Full conversation history sent with every request. History grows linearly; model context window is fixed.

Fix options:

1. Enable automatic summarization at 80% context usage
2. Use .clawignore to exclude large files from context
3. Switch to a model with larger context (claude-3-7-sonnet: 200k tokens)

Full solutions →

Channel-Specific Errors

Telegram channel stops responding (polling stall)

Symptom: Telegram messages not received. No errors in logs. openclaw status shows Telegram channel “initializing” indefinitely.

Root cause: Long-polling connection stalled. Gateway does not detect the stall and does not retry.

Fix: Downgrade to last stable version or patch polling with timeout detection:

npm install -g openclaw@2026.3.22
openclaw gateway restart

Full solutions →

Loop & Stuck Agent Errors

Agent retry storm invisible on Telegram

Symptom: Agent appears stuck. No output on Telegram. CPU usage high on gateway host. Token burn rate 3–5x normal.

Root cause: Agent is retrying a failed tool call in a tight loop. Tool call errors are not surfaced to the Telegram channel, only to internal logs.

Fix: Enable cross-channel error mirroring and add circuit breaker:

error_handling:
  mirror_to_channels: [telegram]
  circuit_breaker:
    failure_threshold: 3
    reset_timeout_ms: 30000

Full solution →

Quick Reference

Browse All OpenClaw Solutions

← View all 253+ OpenClaw solutions

Or search by error message on the homepage — results update in real time.