.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
OpenClaw is not simple software. It's a Node.js agent framework with a long-running Gateway process, multiple channel adapters, a memory layer, a cron scheduler, webhook routing, and model providers that can each break in their own specific way. When something stops working, the failure is rarely obvious, and the error message you get is often misleading or generic.
This guide covers the most common OpenClaw errors systematically, starting from the ground up: environment and install, then the Gateway, then config and models, then channels, then memory, then cron and webhooks, and finally logging and diagnostics. It applies to any OS and any host, whether you're running OpenClaw locally, on a VPS, or inside a container.
Environment and installation problems
Node.js version and dependency errors
OpenClaw requires a modern Node.js LTS. If you're on anything older than Node 20, you'll hit obscure syntax errors or dependency install failures that don't point obviously to the Node version as the cause. Check yours first:
node --versionIf you see 18.x, 16.x, or anything below 20, that's likely your problem. Install via nvm to manage versions cleanly without touching system packages:
nvm install 20
nvm use 20On Ubuntu/Debian, you can also go through NodeSource directly, but nvm is easier when you need to switch versions later. After updating Node, clear your npm cache and reinstall:
npm cache clean --force
npm install -g openclawMissing build tools (Linux)
Many npm dependencies compile native modules. Without build tools installed, the install either fails outright or succeeds but breaks at runtime. On Debian/Ubuntu:
sudo apt install build-essential git python3On Fedora/RHEL-based distros, the equivalent is gcc gcc-c++ make. The git requirement often trips people up too since several npm packages expect it on PATH during install.
Shell installer hangs or exits early
The curl | bash installer launches a TUI (terminal UI). On headless environments like some VPS setups without a proper TTY, that TUI stalls and the install never completes. If you're seeing a hang, kill it and fall back to a direct npm install:
npm install -g openclawThen run openclaw doctor to provision the initial config. On truly headless setups, you can use openclaw doctor --non-interactive and fill in the config manually afterward.
"Command not found" after install
This almost always means npm's global bin directory isn't in your PATH. Find it:
npm config get prefixThe binary lives in <prefix>/bin/openclaw. Add that to your PATH in ~/.bashrc or ~/.zshrc and reload:
export PATH="$(npm config get prefix)/bin:$PATH"
source ~/.bashrcIf you installed with nvm, the path is different. Running which openclaw after a fresh shell session is the quickest way to confirm the binary is actually findable.
Corrupt or incomplete openclaw.json after onboarding
The onboarding wizard sometimes doesn't ask all required questions, which leaves ~/.openclaw/openclaw.json (or the YAML equivalent) incomplete. The resulting errors can be pretty cryptic. Validate the file with a JSON linter first:
python3 -m json.tool ~/.openclaw/openclaw.jsonIf it throws a parse error, you've got a syntax issue. You can try running openclaw doctor --fix, but if the config is badly broken, it's sometimes faster to back it up and start fresh with just the minimal valid structure, then re-apply your settings one section at a time.
Gateway crashes and service-level issues
The Gateway is the process that holds everything together. If it's not running or keeps crashing, nothing works: channels are dead, cron jobs don't fire, webhooks don't get routed. Most Gateway problems fall into a small set of categories.
Port conflicts
The Gateway binds to one or more local ports (typically 9090 and 18789, though this can vary with your config). If anything else is using those ports, the Gateway fails to start. Check what's listening:
ss -tlnp | grep -E '9090|18789'Either stop the conflicting service or change OpenClaw's bind port in config using openclaw config set gateway.port <new_port>. Don't edit the JSON directly for this if you can avoid it, since there are related settings that need to stay consistent.
Stale PID lock files
If the Gateway crashes without cleanup, it leaves a stale PID file at ~/.openclaw/gateway.pid. A new Gateway instance may refuse to start or warn about an already running process that isn't actually there. First confirm there's no real Gateway running:
ps aux | grep openclawIf nothing's running, remove the stale lock:
rm ~/.openclaw/gateway.pidThen restart normally.
WebSocket 1006 errors and plugin crashes
Abnormal WebSocket closure (code 1006) is a common symptom of a Gateway that's starting but crashing immediately due to a plugin loading issue. Community reports show this happening with Discord bot plugins and some local extensions. The approach here is to disable non-core plugins temporarily in config, confirm the Gateway stays stable, then re-enable them one by one until you find the culprit.
Running as a systemd service
If the Gateway works fine when you run it manually but fails as a service, the most common cause is environment variables not being passed to the service. Specifically, API keys and HOME. When HOME isn't set correctly, OpenClaw reads a different config directory or creates a second profile you didn't intend. A minimal systemd unit looks like this:
[Unit]
Description=OpenClaw Gateway
After=network.target
[Service]
Type=simple
User=youruser
Environment=HOME=/home/youruser
Environment=OPENCLAW_LOG_LEVEL=info
ExecStart=/home/youruser/.npm-global/bin/openclaw gateway run
Restart=on-failure
WorkingDirectory=/home/youruser
[Install]
WantedBy=multi-user.targetAdjust the binary path with which openclaw. Also check running OpenClaw as a systemd service for a more complete walkthrough with a real channel and model configured.
Config schema errors and model failures
"Unsupported schema node" and invalid config keys
Manual edits to openclaw.json are tempting but often cause schema validation errors after upgrades, because key names change between versions. The safest approach is using the CLI to modify config wherever possible:
openclaw config get
openclaw config set <key> <value>When you do need to add vendor-specific or untyped keys, use provider-specific "extra" fields that bypass strict schema validation. And when you update OpenClaw, always check the changelog for renamed or removed keys before restarting the Gateway. You can diff your old config against the new expected structure using openclaw doctor.
What needs a full restart vs what hot-reloads
Not everything in config requires a restart. Some timeout and interval values, model parameters within existing providers, and certain channel toggles are safe to change without a full restart. But adding or removing model providers, changing port/bind settings, modifying the agent structure, and auth profile changes all require a full Gateway restart. If you change something and see stale behavior, assume you need to restart before debugging further.
"Model not allowed" error
This one catches people constantly. The agents.defaults.models setting acts as an allowlist. When it's non-empty, only the model keys listed there can be selected, by the user in chat and by any cron jobs or tools in config. If you add a new provider or switch to a different model but forget to update this list, everything that references that model fails silently or returns a "model not allowed" error.
Check your current model allowlist:
openclaw config get agents.defaults.modelsAdd the new model key if it's missing. This is also a common reason why cron jobs stop working after a model change even though the provider config looks correct.
"All models failed" and repeated 401/403/429 errors
If you're getting a 401, your API key is wrong or expired. Double-check the key against your provider dashboard and re-run the credential setup. A 403 usually means your account doesn't have access to that specific model, often because it's gated behind a usage tier or requires an explicit beta signup.
For 429s, you're being rate-limited. The immediate fix is to wait, but longer term you should either add a rate-limiting proxy or adjust your concurrency settings to stay within limits. On providers like Anthropic that use beta headers for experimental features, sometimes those headers get rejected by proxy layers. If you see "invalid beta flag" errors, try explicitly setting beta_features: [] in config to stop sending those headers, or switch to a direct API endpoint that doesn't go through a provider wrapper.
Channel and connection problems
Channel issues follow a fairly predictable diagnostic path. Start with openclaw status for a quick overview, then use openclaw status --all for a more detailed report, and openclaw channels status --probe for per-channel failure signatures. Most problems fall into three buckets: auth errors, permission/scope issues, or mention/pairing policy mismatches.
Telegram: bot online but no replies
The most common Telegram issue is a bot that appears online but ignores messages in groups. The usual culprits:
Privacy mode. Telegram bots with privacy mode enabled only receive messages that explicitly mention them or start with a slash command. You can disable privacy mode through BotFather (/setprivacy), or configure OpenClaw's Telegram adapter to require mentions. Check your logs to see if messages are being received and then dropped due to a missing mention filter.
Token errors. Wrong or expired bot tokens return 401 from Telegram's API. This shows up clearly in logs when you enable debug logging.
Network/DNS issues. On some VPS configurations with IPv6 mismatches or strict egress rules, the Telegram API calls can fail silently. If you see "network error" in logs around outbound Telegram calls, check that your server can actually reach api.telegram.org:
curl -s https://api.telegram.org/bot<YOUR_TOKEN>/getMeIf that returns an error, the problem is network-level, not OpenClaw. See the Telegram connection guide and BotFather configuration for more setup detail.
Discord: bot online, never replies in server channels
Discord issues usually come down to one of these:
Message content intent not enabled. In the Discord developer portal, your bot needs the "Message Content Intent" enabled under Privileged Gateway Intents. Without it, the bot can't read message content and will appear online but never respond.
Mention gating. OpenClaw's Discord adapter can require messages to mention the bot before it responds. Check logs for "dropped due to requireMention" or similar. You can set requireMention: false in config for channels where you want the bot to reply to all messages.
DM pairing for new users. DM replies won't work for users who haven't been paired yet. Run openclaw pairing list discord to see pending requests and approve users. See also the Discord memory and brain setup and the Discord integration guide.
WhatsApp: random disconnects and relogin loops
WhatsApp via QR code pairing is one of the more fragile connections because the session is tied to your phone's login state. Symptoms of expired or corrupt sessions include repeated disconnect messages and relogin prompts even right after scanning a new QR code.
When this happens, run openclaw channels status --probe and inspect the logs. If credentials are corrupt, you may need to clean the credentials directory under ~/.openclaw/channels/whatsapp/ and start a fresh session. Also check DM pairing: connected but no DM replies is often a pairing policy issue, fixable with openclaw pairing list whatsapp and approving the sender. The WhatsApp QR code guide and production setup guide cover this in detail.
Memory loss and context resets
This is probably the most confusing class of OpenClaw issues, partly because people expect AI memory to work like human memory, and partly because there are multiple memory layers that can each behave differently.
How OpenClaw memory actually works
Default OpenClaw memory has two main components: in-session chat history (limited by your token window and subject to compaction) and workspace files like ~/.openclaw/workspace/MEMORY.md and additional files under memory/*.md, which are indexed and used as retrieval sources.
The in-session history is temporary. If you restart the Gateway, the in-session context is gone. The workspace files persist, but only what got written there. If a conversation never explicitly saved anything to MEMORY.md, there's nothing to retrieve later. This is why memory "resets" after breaks: the chat transcript is gone and the persistent memory files either don't exist or don't have the relevant context.
The compaction problem
During long sessions, OpenClaw compacts the context window to stay within token limits. The compaction process summarizes older messages and drops details. This is by design but it means that important decisions or instructions from early in a session can disappear from context partway through. You'll notice the agent starts forgetting things it "knew" earlier. The fix is proactive: write important things to MEMORY.md explicitly during the conversation, rather than relying on compaction to preserve them.
Fixing persistent memory loss
Use smaller, topic-focused memory files under memory/ rather than one giant MEMORY.md. Retrieval quality is better when files are scoped, and it reduces the chance that one large file crowds out relevant content. For anything important, explicitly ask the agent to update the relevant memory file during the session.
For more robust persistence, the ClawVault plugin adds a durable layer with explicit store/search/checkpoint flows. The Cognee plugin goes further and builds a knowledge graph from your conversations and memory files, scanning MEMORY.md and memory/*.md on startup, indexing changes, and using semantic relationships to recall relevant context before each run.
At runtime, you can also use /debug in chat (when commands.debug: true is set in config) to inspect and adjust memory behavior without editing files or restarting the Gateway. See the memory explainer for how the full memory system is structured.
Missing tool results in session history
Sometimes tool outputs show up as synthetic placeholders in session history rather than actual results. This happens when the history compactor prunes large tool outputs, or when there are storage issues for tool messages. The workaround: use /debug to adjust maxTokens or history behavior at runtime, and for large or important tool outputs, have the agent write results to a workspace file so they're preserved regardless of compaction.
Cron jobs and heartbeat problems
Cron is the Gateway's built-in scheduler. It keeps a persistent JSON store of jobs at ~/.openclaw/cron/jobs.json, loads them into memory on startup, and wakes the agent at scheduled times. Heartbeats are periodic Gateway-initiated runs defined by a HEARTBEAT.md checklist in your workspace. When either stops working, the symptoms look similar: nothing runs, or things run but you never see the output.
Jobs appear in list but never run
Work through these in order:
Check that cron is enabled. If cron.enabled is false in config, or the environment variable OPENCLAW_SKIP_CRON=1 is set, no jobs will ever fire. Verify:
openclaw config get cron.enabledCheck the Gateway is running continuously. Cron only works when the Gateway is running as a persistent service. If you're starting it manually for testing sessions and stopping it, cron jobs scheduled during downtime are missed. See heartbeat vs cron on a VPS for context on how this affects behavior.
Check each job's enabled flag. Jobs created via chat or tools sometimes miss enabled: true in their JSON even though it should default. Open ~/.openclaw/cron/jobs.json and confirm each job has it explicitly, or edit through openclaw cron edit.
Check the delivery channel. Some jobs deliver to a "system" channel or a different session, so you don't see them in your normal chat UI. Verify delivery.to, channel bindings, and session choice in the job definition match where you actually expect output.
For a deep dive into cron configuration, see the cron scheduler guide.
Heartbeats suppressing output or interrupting tasks
A well-documented issue from the OpenClaw community: if a heartbeat run produces only a short "HEARTBEAT_OK" message, internal filters treat it as system noise and suppress it. If the heartbeat checklist is poorly structured, it can also preempt active subagents or tasks.
The recommended HEARTBEAT.md pattern is:
- Check for pending tasks and review subagent status first.
- Only if there's no active work, perform proactive actions or send summaries.
- Make HEARTBEAT_OK the last and only terminal message in the checklist, after all logic is done.
This avoids both early termination and suppression of more informative outputs.
wakeMode and session isolation
Cron jobs can have different wake modes. wakeMode: next-heartbeat means the job depends on a heartbeat to actually execute. If heartbeats are disabled or misconfigured, cron jobs with this mode stay perpetually pending. wakeMode: now triggers immediately but can cause rapid re-runs if you're not careful. Make sure you understand which mode each job uses.
Also worth knowing: cron jobs run in isolated sessions with full tool access, which is different from how heartbeats work. This isolation is useful but it means cron jobs don't share context with your active chat session.
Don't edit jobs.json while the Gateway is running
The Gateway loads cron jobs into memory and writes them back on changes. Manual edits to jobs.json while the Gateway runs can get overwritten or corrupt the job state. Always: stop Gateway, edit, restart. Or use the CLI to modify jobs, which handles synchronization correctly.
Webhook errors
Webhooks in OpenClaw can receive inbound HTTP requests (routing them to agents) and send outbound HTTP POSTs (from cron or agent events). Failures are usually auth problems, payload mismatches, or misconfigured URLs.
Common inbound webhook failures
400 Bad Request: the payload doesn't match the expected schema. Your transform or agent expects fields that aren't present in the incoming request. Check what fields the agent expects and validate against a sample payload.
401 Unauthorized: missing or invalid auth on incoming requests. Verify any expected shared secret, basic auth, or bearer token. Check OpenClaw logs for the exact auth failure message.
413 Payload Too Large: the request exceeds configured size limits. For large payloads, consider storing the data separately and sending a reference URL instead.
Common outbound webhook failures
Cron/webhook URLs must be valid http:// or https:// URLs. A missing scheme or wrong host causes immediate failure. If cron.webhookToken is set, OpenClaw adds Authorization: Bearer <token> to outbound requests. If the receiving service expects a different scheme, you'll get 401 or 403 responses even though your config looks right.
Also watch for legacy cron jobs that use notify: true with the global cron.webhook URL as a fallback. If you've migrated to per-job delivery.to URLs but have old jobs still pointing at the legacy webhook, notifications go to the wrong place.
The fastest way to debug webhook issues is simulating calls manually:
curl -X POST https://your-endpoint.example.com/hook \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your-token" \
-d '{"key": "value"}'See the webhooks guide for a full breakdown of inbound/outbound behavior, transforms, and security.
Transform path and TypeScript issues
Transform modules live under ~/.openclaw/hooks/transforms/ and must resolve inside that directory. Path traversal is rejected for security reasons. TypeScript transforms additionally require a TS loader (like bun) to be configured. If your transform works in isolation but fails inside OpenClaw, check that the path is within the allowed directory and that any TypeScript compilation is set up correctly.
Logging, diagnostics, and the /debug command
Where logs live and how to read them
OpenClaw writes JSON-formatted logs to ~/.openclaw/logs/. The log level is controlled by the OPENCLAW_LOG_LEVEL environment variable, or with the --log-level flag on a specific command. The --verbose flag increases console output but doesn't change what gets written to the log file.
For debugging persistent issues, run the Gateway with debug-level logging:
OPENCLAW_LOG_LEVEL=debug openclaw gateway runOr if you're running via systemd, add it to your unit's environment block. Then tail the log file while reproducing the issue:
tail -f ~/.openclaw/logs/openclaw.json | python3 -m json.toolThe piped json.tool formats each entry for readability. Debug-level logs show auth errors, channel message filtering decisions, cron scheduling logic, and webhook request/response pairs.
openclaw status, status --all, and doctor
openclaw status is your quick sanity check: it shows configured channels and obvious auth errors. openclaw status --all gives a more detailed diagnostic report that's useful to share when asking for help in the community. openclaw doctor runs diagnostics on your config and environment and may offer auto-fix steps for known issues.
Using /debug in chat
When commands.debug: true is set in config, you can use /debug in any chat session to inspect and modify runtime behavior without editing files or restarting the Gateway. Key operations:
/debug show # inspect current runtime overrides
/debug set key=value # set a runtime override (e.g., messages.responsePrefix)
/debug unset key # remove a specific override
/debug reset # clear all overrides and revert to disk configThis is useful for testing whether a behavior change is a config issue or a code issue. If toggling an override via /debug fixes the problem, you can then persist that setting to your actual config.
Post-upgrade breakage and config compatibility
OpenClaw releases can introduce schema changes, renamed keys, or removed options. After an upgrade, the most common symptom is a cascade of "unknown key" or "unsupported schema node" errors that weren't there before. Run openclaw doctor immediately after upgrading to catch config compatibility problems. Use openclaw config get / set rather than manual edits to normalize settings where possible.
Before any major upgrade, snapshot your ~/.openclaw/ directory:
cp -r ~/.openclaw ~/.openclaw.backup.$(date +%Y%m%d)This lets you diff old vs new configs and roll back if something breaks badly. See the backup guide for a more structured approach to protecting data, settings, and memory.
Local LLM issues with Ollama
Running OpenClaw against a local model via Ollama introduces its own failure modes. Model names must match the provider config exactly, character for character. A mismatch produces a "model not allowed" or generic provider error, not a "model not found" error, which makes it hard to identify. Always confirm the model name you pulled with:
ollama listAnd verify it matches exactly what's in your OpenClaw provider config. Context window constraints differ between local models too. Some GGUF/ggml backends will crash under certain prompt sizes or with specific tool call patterns. If you're seeing low-level assertion failures, start with smaller prompts and simpler tool chains to isolate the problem. The local Ollama setup guide covers the full configuration.
Performance, stability, and out-of-memory crashes
Intermittent crashes without clear error messages in the OpenClaw logs are often OOM (out of memory) kills from the OS. Check system logs:
journalctl -k | grep -i "oom\|killed"
dmesg | grep -i "oom\|killed"If you find OOM kills, the Gateway is consuming more RAM than the host has available. This can happen with heavy cron concurrency, large memory indexing operations, or running too many channels simultaneously. Reduce maxConcurrentRuns in cron config, disable optional plugins and channels to find the memory consumer, and consider giving the Gateway its own VPS instance rather than sharing with other services.
For high latency issues, use debug-level logging to measure where time is being spent. Long model call times point to provider latency or network conditions; long tool execution times suggest the tool itself is slow or blocked on an external API.
Filing a useful bug report
If you've worked through all of the above and still can't find the cause, the OpenClaw GitHub Issues is where to go. A good bug report should include: OS and version, Node.js version, OpenClaw version (from openclaw --version), exact reproduction steps, relevant config sections with secrets redacted, and log snippets at debug level. The output of openclaw status --all is also genuinely useful. The more specific you are, the faster you'll get a useful response.
