OpenClaw Troubleshooting: Fix Common Errors

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

Common Beginner Mistakes

These are the errors I see new OpenClaw users make over and over. Avoid them and you will save yourself hours.

Not Reading the Logs

When something breaks, your first move should always be openclaw logs --follow. The logs tell you exactly what went wrong. "API key invalid." "Channel not configured." "Model returned empty response." The error message is right there. Most beginners skip the logs and start randomly changing config values. Read the logs first. Always.

Running Too Many Agents Too Soon

Beginners sometimes try to deploy 10 agents on day one. Start with one. Get it working. Understand how SOPs work, how cron jobs fire, how memory files persist. Then add a second agent. Then a third. Build up gradually. A broken 10-agent setup teaches you nothing. A working 2-agent setup teaches you everything.

Forgetting to Restart After Config Changes

Changed your model? Updated your API key? Added a new channel? None of those changes take effect until you restart the gateway. Run openclaw gateway restart after any config change. This catches 90% of "I changed the setting but nothing happened" issues.

Using the Wrong Model for the Job

Running Claude Opus for a simple weather check wastes money. Running a tiny local model for complex research wastes time because it will produce garbage. Match your model to the task. Simple tasks get cheap or local models. Complex tasks get frontier models. The pricing guide covers the cost implications in detail.

Not Setting Up Memory Files

OpenClaw agents start fresh every session. Without MEMORY.md, AGENTS.md, and SOUL.md in your workspace, your agent has no context. It does not know who you are, what your business does, or what it should prioritize. These files are not optional. They are the foundation. Check the beginner guide for how to set them up properly.

Ignoring Permission Boundaries

Giving every agent full access to everything is a recipe for chaos. Agent A overwrites a file that Agent B needs. Agent C sends an email that Agent D was supposed to draft first. Set up a permission matrix from the start. Which agents can read what? Which agents can write where? Which agents can send external messages? Define these boundaries early.

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.

When to Ask the Community

You have tried the diagnostic commands. Read the logs. Searched GitHub issues. Still stuck. Time to ask for help.

Three places to get help, in order of speed:

1. OpenClaw Discord. The official Discord server is the fastest for technical bugs. Developers and community members hang out there. Post your error message, your OS, and your OpenClaw version. You will usually get a response within hours.
2. OpenClaw Lab on Skool. If you are a member, post your issue in the community. Members running production setups have likely hit your exact problem. The advantage over Discord: posts are searchable and permanent. Your question and the solution stay findable for future members.
3. GitHub Issues. For actual bugs in OpenClaw itself. If you found a reproducible problem, open an issue with steps to reproduce, your config (redacted), and the error output. The maintainers are responsive.

When asking for help, always include:

• Your OpenClaw version (openclaw --version)
• Your OS and hardware
• The exact error message from logs
• What you already tried

"My agent doesn't work" gets you nowhere. "I'm on OpenClaw 1.4.2, macOS 15.3, M4 Mac Mini, getting 'ECONNREFUSED' when starting the gateway, already tried changing the port" gets you a fix in 10 minutes.

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

Frequently Asked Questions

Why is my OpenClaw agent not responding?

Check that the OpenClaw daemon is running with 'openclaw gateway status'. Verify your API key is valid and has credits. Ensure your messaging channel (Telegram, Discord, etc.) is properly configured. Run 'openclaw doctor' for a comprehensive diagnostic.

How do I fix OpenClaw API key errors?

Verify your API key at the provider's dashboard (console.anthropic.com for Anthropic). Check that you have billing set up and sufficient credits. Re-enter the key in your OpenClaw config if needed. Common issues include expired keys and missing billing information.

Why is OpenClaw using too many API credits?

High API usage usually comes from frequent cron jobs, long conversations without context management, or using expensive models for simple tasks. Reduce cron frequency, use cheaper models for basic tasks, and enable context compaction to lower costs.

How do I reset my OpenClaw agent?

Clear the agent's memory files (MEMORY.md and daily logs) to reset its context. You can also restart the gateway with 'openclaw gateway restart'. For a complete reset, re-run 'openclaw onboard' to reconfigure from scratch.

Where can I get help with OpenClaw problems?

Get help on the official OpenClaw Discord server, GitHub issues, or OpenClaw Lab on Skool. Run 'openclaw doctor' first to identify common issues. The Discord community is fastest for technical problems, while OpenClaw Lab offers guided troubleshooting.