OpenClaw Not Working? 12 Fixes for Common Failures

Introduction

OpenClaw not working is a vague complaint with a short list of actual causes. After a major release like 2.0 — or a quiet week where WhatsApp updates itself on your phone — the failure modes cluster into a handful of patterns: the Gateway won't start, the agent is up but a channel isn't responding, the model rejects your key, or everything works but it's slow and expensive.

This guide is a symptom-first troubleshooting map: twelve fixes covering the failures operators actually hit, ordered from "nothing starts" to "it works but something feels wrong." Each fix tells you what you'll see, what causes it, and what to do. Most OpenClaw problems are diagnosed in under five minutes once you know where to look.

Start Here: The 60-Second Diagnosis

Before touching config, establish which layer is broken. OpenClaw has four: the runtime (Node/OpenClaw itself), the Gateway (the control plane), the channels (WhatsApp/Telegram/etc.), and the model provider. Run these three checks:

openclaw --version      # confirms the binary runs and which version you have
openclaw doctor         # built-in health check: config, gateway, channels

Then watch the logs while you reproduce the problem — the Gateway logs nearly always name the failing layer explicitly (auth error, pairing request, port bind failure, model HTTP error). On a VPS, read them through your service manager (journalctl -u <service> under systemd); locally, the launching terminal shows them. Nine times out of ten, the fix below will be obvious once the log line is in front of you.

Installation and Startup Failures

1. The install script fails or hangs

Symptoms: curl -fsSL https://openclaw.ai/install.sh | bash errors partway, or npm install fails.

Fixes, in order of likelihood: a network or proxy problem (corporate proxies and some regional networks block the install endpoints — try a different network or a proxy-aware mirror); a permissions problem (don't install as root; the installer expects a normal user); or an npm scripts issue — the npm route requires the scripts flag, npm install -g openclaw@latest --allow-scripts=openclaw, and forgetting it produces a broken install. If npm itself is the problem, the curl script route bypasses it entirely.

2. Node version mismatch

Symptoms: cryptic engine errors at install or startup, or the CLI refusing to run.

OpenClaw requires Node 22.22.3+, 24.15+, or 25.9+ — and 2.x tightened this floor from older versions. Check with node --version. If you're on an old LTS, upgrade Node (nvm makes this painless) and reinstall. Version mismatches became more visible after the 2.0 upgrade because the Node floor moved with it.

3. The Gateway won't start

Symptoms: the Gateway process exits immediately, or logs a bind/port error.

Two usual causes. Port conflict: something else has the Gateway's port (another OpenClaw instance you forgot about is the classic — ps aux | grep -i openclaw and kill strays). Config syntax: a trailing comma or wrong type in your config file from a manual edit. Run openclaw doctor — it reports config errors directly, and the configuration guide covers the file layout. Fix the config, start again.

Connected but Not Responding

4. The pairing wall (agent ignores a sender)

Symptoms: WhatsApp/Telegram shows your message sending, but no reply ever comes; the logs show a pairing request.

This is usually not a bug — it's the security default working. OpenClaw pairs unknown senders and ignores everyone else. Approve yourself:

openclaw pairing approve <channel> <code>

The code appears in the logs when the unpaired message arrives; codes expire, so send a fresh message if yours is stale. Full walkthroughs: WhatsApp pairing and Telegram pairing.

5. The channel disconnected

Symptoms: it worked for days, then silence on one channel while others (or the CLI) still respond.

Channels drop independently of the Gateway. WhatsApp linked sessions get logged out by phone updates or WhatsApp's own session hygiene — re-link via Settings → Linked Devices and the QR flow. Telegram bots stop when the token is wrong or a second process is fighting over it (kill duplicate Gateways). The channel's log lines will say which. After relinking, resend a message to regenerate a pairing code if needed.

6. Replies stopped after the 2.0 upgrade

Symptoms: everything worked on 1.x; after updating, channels or skills misbehave.

2.0 changed messaging internals, plugin loading, and secret handling — most third-party skills needed compatibility updates. In order: update OpenClaw to the latest patch (the project resumed its fast release cadence after 2.0 — 2026.8.1 was followed by 2026.8.2, 2026.9.1, and 2026.9.2 within days, each fixing upgrade fallout), update every skill and plugin, then re-check channels. If session history vanished, that's the migration — see fix 9 before you touch anything.

Model and API Key Errors

7. Invalid or expired API key

Symptoms: the agent replies with an apology or nothing at all; logs show 401/403 from the provider.

Keys expire when you revoke them, rotate them at the provider, or hit a project limit. Generate a fresh key at your provider's dashboard, update it in your OpenClaw config (never in chat — see API key handling), restart, test. If you use a subscription as the backend instead of API keys, an expired subscription login produces the same class of error — re-authenticate through the official login flow rather than pasting anything anywhere.

8. Quota, spending caps, and rate limits

Symptoms: the agent worked all week, then stopped mid-task; logs show 429s or quota errors.

Three separate ceilings produce this: your provider's rate limit (wait or upgrade tier), your own spending cap (raise it deliberately — if you set a cap in a hurry, this is it reminding you), or an exhausted subscription allowance (heavy agent usage consumes a chat subscription's limits much faster than chatting does — the cost guide explains why and how to route around it).

Sessions, Memory, and Skills

9. Lost session history after upgrading

Symptoms: after the 2.0 upgrade, conversations are empty or the Gateway errors on startup.

Session state moved to SQLite in 2.0, and the migration runs on first launch. If it was interrupted — the process killed mid-migration, a full disk, a container recreated too early — you're in a half-migrated state. Stop and roll back: restore from the backup you made per the upgrade guide, then re-run the upgrade and let the migration complete without interruption. Do not try to hand-merge session files with the database; that's how recoverable situations become unrecoverable ones.

10. A skill or plugin broke

Symptoms: one capability fails while everything else works; logs show errors naming a specific skill.

After a major upgrade, third-party skills are the usual suspects (fix 6 covers updating them). If a skill fails on the current version with updates applied, uninstall it, confirm the rest of the agent works, and reinstall from a fresh copy — corrupted skill installs happen, especially after interrupted updates. If it still fails, the problem is the skill's compatibility, not your install; check its repo for an issue or pin to a working version. Our ClawHub vetting guide covers choosing replacements.

Performance and Cost Symptoms

11. Very slow responses

Symptoms: replies take minutes, or long tasks stall.

Slow is usually the model, not OpenClaw. In order: a premium model under heavy load (try a different model tier); a bloated session — very long-running sessions re-process their entire accumulated context every turn, and the fix is simply starting a fresh session for the new task; or local-model hardware limits if you've routed to a local model that's too big for the machine. If slowness came with an upgrade, check the release notes and the project's issue tracker before assuming it's your config — fast-cadence projects ship occasional regressions, and they fix them in days.

12. A bill spike you didn't expect

Symptoms: provider charges you didn't authorize.

Assume a leaked or misused key first — this is the one "not working" symptom that is an emergency. Revoke the key at the provider immediately, issue a capped replacement, and hunt the leak path per our API key security guide. If the key turns out to be fine, the usual cause is a runaway session: an agent stuck in a retry loop or a skill that calls the model on a timer. Usage logs at your provider will show the exact call pattern, and spending caps turn any recurrence into a non-event.

When All Else Fails

Three escalation paths, in order:

The official FAQ — the maintainers keep it current, and it covers local dev, VPS, multi-agent setups, and OAuth/API-key quirks the docs pages don't
The GitHub issues on github.com/openclaw/openclaw — search your exact error message before filing; after a big release, someone usually hit your bug within days
Restore from backup — if the instance is genuinely wedged and you have a verified backup (or a VPS snapshot), restoring is faster than debugging. That's what it's for

FAQ

Why is my OpenClaw agent not responding on WhatsApp? Overwhelmingly likely: the sender isn't paired. Check the Gateway logs for a pairing request and approve it with openclaw pairing approve whatsapp <code>. If the session itself dropped, re-link via WhatsApp Settings → Linked Devices.

How do I see OpenClaw logs? Wherever the Gateway runs: the launching terminal locally, journalctl -u <service> on a systemd VPS, or your container runtime's logs (docker logs) if you followed the Docker setup. The logs name the failing layer in nearly every case.

Why did OpenClaw stop working after updating to 2.0? The upgrade changed messaging internals, plugin loading, and session storage. Update OpenClaw to the latest patch release, update all skills/plugins, and if history is missing, restore from your pre-upgrade backup — the full sequence is in the upgrade guide.

Is there a built-in diagnostic? Yes — openclaw doctor checks config validity, Gateway health, and channel connections, and points at the specific failures. Run it before and after any fix.

How do I completely reset OpenClaw and start over? Back up first (config, credentials, sessions), then reinstall fresh and re-onboard — 2.0's setup re-detects subscriptions and keys. Resetting is a last resort; most "broken" installs are one config line or one pairing approval away from working.