OpenClaw Stopped Working? Here's How to Fix It (Every Common Issue)

Don't panic. Every common reason OpenClaw breaks — and exactly how to fix each one. Symptoms, causes, and step-by-step solutions.

So OpenClaw stopped working. You were in the middle of something — maybe a complex automation, maybe just chatting with your agent — and suddenly: nothing. An error message. A hang. A response that makes no sense.

Don't panic. You're not the first person this has happened to, and you won't be the last.

This guide covers every common reason OpenClaw stops working and exactly how to fix each one. Symptoms, causes, and step-by-step solutions — including the commands you'll need.

Let's get you back up and running.

1. API Key Expired or Invalid

Symptoms

• Errors like 401 Unauthorized, Invalid API key, or Authentication failed
• OpenClaw starts but every request fails immediately
• You see API key not found or key expired in the logs

Cause

Your API key for the underlying model provider (Anthropic, OpenAI, etc.) has either expired, been revoked, hit its spending limit, or was never set correctly. This is the single most common reason OpenClaw stops working overnight — everything was fine yesterday, and today it's broken.

Fix

First, check which key is configured:

openclaw config show

Look for the apiKey or provider-specific key fields. If the key is present, verify it's still valid by testing it directly:

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: YOUR_KEY_HERE" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-4-20250514","max_tokens":10,"messages":[{"role":"user","content":"hi"}]}'

If you get a 401, the key is dead. Generate a new one from your provider's dashboard, then update it:

openclaw config set anthropic.apiKey sk-ant-your-new-key-here

Then restart the gateway:

openclaw gateway restart

2. Model Rate Limits

Symptoms

• 429 Too Many Requests errors
• Responses suddenly slow to a crawl, then fail
• Works fine for a while, then stops mid-conversation
• Error messages mentioning rate_limit_exceeded or quota

Cause

You've hit the rate limit or token quota for your model provider. This is especially common if you're running multiple agents, using heartbeats with short intervals, or processing large batches of data. Free-tier and lower-tier API plans have aggressive limits.

Fix

Check your current usage on your provider's dashboard. If you're consistently hitting limits, you have a few options:

1. Reduce heartbeat frequency:

openclaw config set heartbeat.intervalMs 1800000  # 30 minutes

2. Use a smaller model for routine tasks:

openclaw config set default_model anthropic/claude-sonnet-4-20250514

3. Upgrade your API tier: If you're doing real work with OpenClaw, the free tier won't cut it. Upgrading usually increases both rate limits and token quotas significantly.

4. Add retry logic:

openclaw config set retry.enabled true
openclaw config set retry.maxRetries 3

3. Connection Timeouts

Symptoms

• ETIMEDOUT, ECONNREFUSED, or socket hang up errors
• OpenClaw hangs for a long time, then fails
• The gateway shows as "not running" even though you started it
• Works on some networks but not others

Cause

Either the OpenClaw gateway isn't running, your network is blocking the connection, or the model provider's API is experiencing an outage. Corporate VPNs and firewalls are frequent culprits.

Fix

Start with the basics:

openclaw gateway status

If it's not running:

openclaw gateway start

If it is running but you're still timing out, check connectivity to the API:

curl -I https://api.anthropic.com

No response? Your network might be blocking it. Try:

• Disconnecting from your VPN
• Switching to a different network (phone hotspot is a good quick test)
• Checking your firewall rules for outbound HTTPS on port 443

For persistent timeout issues, increase the timeout threshold:

openclaw config set request.timeoutMs 120000  # 2 minutes

4. Memory and Context Issues

Symptoms

• The agent "forgets" things from earlier in the conversation
• Responses become incoherent or repetitive
• Errors about context_length_exceeded or max tokens
• Agent starts hallucinating or losing track of the task

Cause

Every model has a context window — the maximum amount of text it can process at once. When your conversation, workspace files, and system prompts exceed that window, things break. OpenClaw loads files like SOUL.md, MEMORY.md, and workspace context automatically, which can eat into your available context quickly.

Fix

Check what's being loaded:

du -sh ~/.openclaw/workspace/*.md
du -sh ~/.openclaw/workspace/memory/

If MEMORY.md or your daily files have grown large, it's time to prune. Keep MEMORY.md under a few KB of the most important context. Archive old daily files:

mkdir -p ~/.openclaw/workspace/memory/archive
mv ~/.openclaw/workspace/memory/2025-*.md ~/.openclaw/workspace/memory/archive/

For context_length_exceeded errors specifically: Start a fresh conversation. Long sessions accumulate context. Sometimes the simplest fix is a clean slate.

Reduce injected context: If you have large files in your workspace root, OpenClaw may be loading them into context. Move non-essential files into subdirectories that aren't auto-loaded.

5. Plugin and Skill Conflicts

Symptoms

• Specific tools or skills stop working while others are fine
• Errors referencing a particular plugin or skill file
• Tool calls fail with not found or permission denied
• Behavior changes after installing a new skill

Cause

Plugins and skills can conflict with each other — especially if two skills define overlapping tool names, or if a skill was written for an older version of OpenClaw. Corrupted skill files or incorrect permissions are also common.

Fix

Identify the problem skill: If the issue started after adding a new skill, temporarily disable it:

mv ~/.openclaw/skills/problem-skill ~/.openclaw/skills/problem-skill.disabled
openclaw gateway restart

Check skill file integrity:

cat ~/.openclaw/skills/your-skill/SKILL.md

Look for obvious issues: corrupted content, syntax errors in code blocks, or references to tools that don't exist.

Permissions:

chmod -R 644 ~/.openclaw/skills/*/SKILL.md

When in doubt, re-clone: If a skill came from a repository, delete it and re-install fresh.

6. Update Breaking Changes

Symptoms

• Everything worked before the update, nothing works after
• New error messages you've never seen before
• Config fields that used to work are now "unknown"
• Commands have different syntax than expected

Cause

OpenClaw is actively developed. Updates sometimes change config schemas, command syntax, or default behaviors.

Fix

Check what version you're on:

openclaw --version

If you need to roll back immediately:

npm install -g openclaw@previous-version-number
openclaw gateway restart

Common post-update fixes:

• Run openclaw config migrate if available — this updates your config to the new schema
• Check for renamed config keys in the changelog and update manually
• Clear any cached state: openclaw cache clear

7. Config File Errors

Symptoms

• OpenClaw fails to start entirely
• YAML parse error, invalid config, or unexpected token in logs
• The gateway starts but ignores your settings
• Behavior doesn't match what you configured

Cause

A typo, indentation error, or invalid value in your config file. YAML is notoriously sensitive to whitespace.

Fix

Validate your config:

openclaw config validate

Common YAML pitfalls:

• Tabs instead of spaces — YAML doesn't allow tabs for indentation
• Missing quotes around strings with special characters — wrap values containing :, #, or { in quotes
• Inconsistent indentation — every level should use the same number of spaces (2 is standard)

Nuclear option — reset config:

cp ~/.openclaw/config.yaml ~/.openclaw/config.yaml.backup
openclaw config reset

Then re-apply your settings one at a time using openclaw config set.

Quick Diagnostic Checklist

When OpenClaw stops working, run through this in order:

1. openclaw gateway status — Is the gateway running?
2. openclaw config show — Is your API key set and valid?
3. Check your network — Can you reach the API provider?
4. Check provider status page — Is the API itself down?
5. openclaw --version — Did you recently update?
6. openclaw config validate — Is the config clean?
7. Check logs — The error message usually tells you exactly what's wrong

Nine times out of ten, it's one of the first three.