Paste your OpenClaw error message and get an instant diagnosis with step-by-step, copy-paste fix commands. Covers every common error β gateway startup, schema validation, model not allowed, disconnects 1006/1008, port conflicts, permission errors, channel failures and post-upgrade breakage.
The most common OpenClaw errors fall into five categories: gateway startup failures, config schema errors, WebSocket disconnects, model and channel errors, and post-upgrade breakage. Understanding which category your error belongs to cuts the average debug time from 45 minutes to under 5. [web:54]
| Error / Symptom | Category | First Command |
|---|---|---|
| Gateway did not become healthy | Gateway startup | openclaw doctor --fix |
| unknown key / unsupported schema node | Config schema | openclaw doctor --fix |
| Disconnected: 1006 Abnormal Closure | WebSocket | openclaw gateway restart |
| Disconnected: 1008 Policy Violation | Auth / Token | Regenerate gateway token |
| model not allowed | Model allowlist | Update agents.defaults.models |
| EADDRINUSE :::18789 | Port conflict | lsof -i :18789 |
| Permission denied /tmp/openclaw-1000 | Permissions | chmod 700 /tmp/openclaw-1000 |
| Telegram not responding | Channel / Bot | openclaw channels status |
| LLM request timed out | Model / API | Check API key + provider status |
| All broken after update | Post-upgrade | openclaw doctor --fix + openclaw gateway restart |
Roughly 70% of OpenClaw issues resolve with just two commands run in sequence: [web:58]
openclaw doctor --fix β scans config for drift, removes stale keys, repairs directory permissions, and normalizes settingsopenclaw gateway restart β cleanly stops and restarts the gateway process, re-registering all cron jobs and channel connectionsAlways run these two commands first, before any deeper debugging. They are idempotent β running them when nothing is wrong does not cause new issues.
OpenClaw releases frequently rename or remove config keys. Any key in openclaw.json that no longer exists in the current schema causes strict Zod validation to reject the entire config β the gateway refuses to start with no graceful fallback. [web:54] Always run openclaw doctor --fix immediately after openclaw update. Check the changelog for renamed keys before restarting.
openclaw.json causes Zod validation to reject the entire config. Run openclaw doctor --fix immediately after every upgrade. If still failing, check openclaw gateway status --deep and look for permission errors on /tmp/openclaw-1000 β fix with chmod 700 /tmp/openclaw-1000. [web:54][web:57]openclaw.json and restarting. [web:61]agents.defaults.models block acts as an allowlist. When non-empty, only listed model keys can be used. If you add a new provider or switch models without updating this list, every reference to that model fails with "model not allowed" β often silently in cron jobs. Fix: add the new model key to the allowlist, run openclaw doctor --fix and restart. [web:54]lsof -i :18789 to identify the conflicting process and its PID. If it's a stale OpenClaw process: kill -9 <PID>. If it's a different service, change OpenClaw's port with openclaw config set gateway.port 18790 (use CLI, not manual JSON edit, to keep related settings consistent). [web:54][web:59]memory/YYYY-MM-DD.md). Use small, topic-focused memory files rather than one giant MEMORY.md β retrieval quality is better when files are scoped. [web:54]