OpenClaw Troubleshooting: Fix Every Common Error

Something broke. Your OpenClaw agent stopped replying, the gateway won't start, or you're staring at a cryptic error in your logs. This guide covers every common OpenClaw issue I've hit while running 13 agents on a Mac Mini. Real fixes. No fluff.

The 5 Diagnostic Commands You Need

Before you touch anything, run these five commands in order. They tell you exactly what's wrong 90% of the time.

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

Here's what healthy output looks like:

• openclaw gateway status shows Runtime: running and RPC probe: ok
• openclaw doctor reports zero blocking issues
• openclaw channels status --probe shows all your channels as connected/ready

If those commands all come back clean and things are still broken, keep reading.

Gateway Won't Start

This is the most common issue people hit. The gateway process either won't start or crashes immediately after launching.

Port Conflict (EADDRINUSE)

Another process is already using the gateway port. Default is 3001.

# Check what's using the port
lsof -i :3001

# Option 1: Kill the conflicting process
kill -9 <PID>

# Option 2: Change OpenClaw's port
openclaw config set gateway.port 3002
openclaw gateway restart

Gateway Mode Not Set

You'll see: Gateway start blocked: set gateway.mode=local

Fix it in one command:

openclaw config set gateway.mode local
openclaw gateway start

Or run openclaw configure to walk through the interactive setup again.

Missing Auth on Non-Loopback Bind

If you're binding to a public IP (like on a VPS), OpenClaw requires authentication. You'll see: refusing to bind gateway without auth

# Set a gateway password
openclaw config set gateway.auth.password "your-secure-password"
openclaw gateway restart

This is a security feature. OpenClaw won't expose your agent to the internet without protection. Which is exactly what you want.

Agent Not Replying to Messages

Channel shows connected but your agent ignores you. This is almost always a policy or pairing issue.

Check Pairing Status

openclaw pairing list --channel telegram
openclaw logs --follow

Look for pairing request in the logs. New senders need approval before the agent responds. Run:

openclaw pairing approve --channel telegram --user <userId>

Group Mention Gating

In groups, OpenClaw ignores messages unless you mention the bot. The log signature: drop guild message (mention required)

This is intentional. Your agent shouldn't respond to every message in a group chat. But if you want it to, adjust the config:

openclaw config set channels.telegram.groups.requireMention false

Allowlist Blocking

If you set up allowlists, make sure the sender or group is actually on it. Check with:

openclaw config get channels

Look for allowlist entries under your channel config.

Context Window Errors

After long conversations, you'll hit context_length_exceeded. The agent has too much conversation history to process.

Quick Fix: Compact or Reset

# In your chat session, type:
/compact

# Or start completely fresh:
/new

The /compact command summarizes your conversation history to free up space. /new starts a brand new session with zero history.

Prevent It From Happening

Set auto-compaction in your config so you never hit the wall:

# OpenClaw handles this automatically in most cases
# But you can configure compaction behavior in openclaw.json
# under agents.defaults.compaction

I run 13 agents and the ones doing heavy research (web searches, file reads) hit context limits fastest. Daily cron jobs that reset each run don't have this problem because each run starts fresh.

API Rate Limits and 429 Errors

The dreaded HTTP 429. Your API provider is telling you to slow down.

Anthropic Long Context 429

Error: HTTP 429: rate_limit_error: Extra usage is required for long context requests

This specific error means your Anthropic API key doesn't have long-context access enabled. Three options:

1. Disable long context: Turn off context1m for the model in your config
2. Upgrade your plan: Enable Anthropic Extra Usage on your billing account
3. Set fallback models: Configure alternatives so runs continue when one provider rejects requests

# Check your model configuration
openclaw models status
openclaw config get agents.defaults.models

General Rate Limits

If you're hitting rate limits across providers, you're likely running too many agents or cron jobs simultaneously. Space out your cron schedules. Don't have 5 agents all firing at the same minute.

I stagger my cron jobs across the hour. Dan runs at :00, Tyler at :15, Loop at :30. No collisions.

Cron Jobs and Heartbeats Not Running

Your scheduled tasks aren't firing. Check the scheduler first:

openclaw cron status
openclaw cron list
openclaw cron runs --id <jobId> --limit 20

Cron Scheduler Disabled

Log message: cron: scheduler disabled; jobs will not run automatically

Enable it:

openclaw config set cron.enabled true
openclaw gateway restart

Heartbeat Skipping

Heartbeats skip for specific reasons. Check logs for:

• reason=quiet-hours: Outside your configured active hours. This is working as intended.
• reason=requests-in-flight: Another request is already running. Heartbeat waits.
• reason=dm-blocked: Heartbeat target uses DM and direct policy is set to block.

# Check last heartbeat
openclaw system heartbeat last

Dashboard Won't Connect

The Control UI keeps reconnecting or shows "unauthorized."

Common Causes

• Wrong URL: Make sure you're hitting the right host and port
• Token mismatch: The dashboard auth token doesn't match the gateway config
• HTTP instead of HTTPS: Device identity requires a secure context on some setups

# Verify gateway is actually running and reachable
openclaw gateway status --json

# Check for auth issues
openclaw doctor

Nuclear Options: When Nothing Else Works

You've tried everything above and it's still broken. Here's the escalation path.

Full Gateway Restart

openclaw gateway stop
sleep 5
openclaw gateway start

Doctor Fix + Restart

openclaw doctor --fix
openclaw gateway restart

Reinstall (Keeps Your Config)

npm update -g openclaw
openclaw doctor --fix
openclaw gateway restart

Your config lives in ~/.openclaw/openclaw.json. Reinstalling OpenClaw doesn't touch it. Your agents, cron jobs, and workspace files are safe.

Check GitHub Issues

If you're hitting a bug, someone else probably is too. The OpenClaw GitHub Issues page is active and the maintainers respond fast. Search for your error message before opening a new issue.

The official troubleshooting docs are also comprehensive and updated regularly. Bookmark them.

If you want the full setup walkthrough so you don't run into these issues in the first place, grab the install guide here.