OpenClaw Troubleshooting — Every Error, Every Fix

"OpenClaw is not replying"

The most-searched OpenClaw issue. Six causes in order of frequency:

1. The daemon isn't running

openclaw status
# Expect: ● running (PID 12345)
# If: ● stopped → openclaw start

If status shows running but messages still don't get a reply, continue down the list.

2. Channel allowlist is excluding you

OpenClaw silently drops messages from senders not in allowFrom. This is a security feature, not a bug. Check your config:

grep -A 3 "allowFrom" ~/.openclaw/config.yaml

If the list doesn't include your phone number / Telegram handle / email address, add it and restart: openclaw restart.

3. Mention rule in groups

In group chats (Telegram, WhatsApp, Slack), OpenClaw only responds when explicitly @mentioned by default. Either mention it or set the channel to "free-response mode":

openclaw config set channels.telegram.require_mention false

4. Provider key is invalid or out of credit

If the LLM call fails, OpenClaw logs the error but doesn't reply. Check:

openclaw logs --tail 50 | grep -E "401|402|403|429|invalid"

If you see 401: rotate the API key in your config. 402: add credit to your provider account. 429: see the 429 section.

5. A skill in the chain is crashing

If a skill throws an exception during the response pipeline, OpenClaw aborts the message. Tail logs:

openclaw logs --tail 100 | grep -E "ERROR|skill:"

Common offenders: skills that call external APIs and don't handle timeouts. Disable the problem skill temporarily: openclaw skill disable <name>.

6. The DM policy is set to "ignore"

OpenClaw has a per-channel DM policy. ignore means "don't respond to direct messages at all." Check:

openclaw config get channels.telegram.dm_policy

Set to respect_allowlist (responds to senders in allowFrom) or respond (responds to everyone — usually unsafe).

"HTTP 429 — Rate limit exceeded"

Three distinct causes. The fix depends on which one is firing.

Provider-side 429 (most common)

Your model provider (Anthropic, OpenAI, etc.) is rate-limiting your account. Check the response headers in openclaw logs for x-ratelimit-reset to see when the window resets. Fixes:

• Wait it out — most provider rate limits reset within 60 seconds.
• Switch to a cheaper model for the next few requests. openclaw config set default.model claude-haiku-4-5.
• Enable provider fallback in config so 429s automatically route to a backup provider:

  providers:
    - name: primary
      type: anthropic
      apiKey: ${ANTHROPIC_API_KEY}
    - name: fallback
      type: openrouter
      apiKey: ${OPENROUTER_API_KEY}
  fallback:
    on: [429, 503, timeout]
    to: fallback

• Upgrade your plan tier if 429s are persistent — most providers have a per-minute TPM/RPM cap that scales with the plan.

OpenClaw self-imposed cap (intentional)

If you've set rate.max_per_minute in config, OpenClaw will throttle itself before hitting the provider. Check:

openclaw config get rate.max_per_minute

Default is unlimited. If set, increase it or remove it.

Heartbeat firing too often

A skill subscribed to the heartbeat (cron-style) may be calling the model every few seconds and burning your rate limit. Diagnose:

openclaw logs --tail 200 | grep heartbeat

Fix by lowering the heartbeat frequency: openclaw config set heartbeat.interval 60s (was probably 5s or 10s).

Installation & npm errors

npm ERR! code EACCES when installing OpenClaw

Don't use sudo. The fix is a per-user npm prefix:

mkdir -p ~/.npm-global
npm config set prefix "$HOME/.npm-global"
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
npm install -g openclaw

This installs to ~/.npm-global/, no root required. Same fix applies to skill installs.

Command 'openclaw' not found after install

PATH didn't pick up ~/.npm-global/bin. Confirm the line is in .bashrc (or .zshrc on macOS), then source ~/.bashrc or open a fresh terminal.

node: bad option: --experimental-vm-modules

Your Node version is too old. OpenClaw requires Node 22.16+. Check: node -v. Upgrade via your package manager or nvm.

Skill install fails with manifest validation

The skill's skill.yaml is malformed or references a permission OpenClaw doesn't recognize (often because the skill is for an older OpenClaw version). Run openclaw skill audit <name> to see what's wrong. If the skill is from the official 53, file an issue on GitHub. If it's community, prefer the official equivalent or write your own with openclaw skill new.

Memory & database

"database is locked"

Two OpenClaw processes are writing to the same SQLite memory store. Find them:

ps aux | grep openclaw | grep -v grep

Kill duplicates. If you intentionally run multiple OpenClaw instances on one host, give each its own memory dir:

openclaw config set memory.path ~/.openclaw/instance-2/memory.db

For heavy concurrent use (5+ instances or a busy heartbeat), switch to PostgreSQL:

openclaw config set memory.backend postgres
openclaw config set memory.connection "postgres://user:pass@host:5432/openclaw"

Memory store growing unbounded

OpenClaw doesn't auto-prune by default. Check size: du -h ~/.openclaw/memory.db. If >1 GB, run periodic vacuum:

openclaw memory vacuum --older-than 90d

Or schedule it weekly via the heartbeat.

Lost memory after upgrade

Some major version bumps migrate the memory schema. Check for a backup in ~/.openclaw/backups/ — OpenClaw writes one before any migration. Restore with openclaw memory restore <backup-file>. If no backup exists, you're out of luck for that data — file an issue on GitHub so future migrations preserve.

Channel-specific issues

Telegram: messages sent but bot doesn't see them

Either the webhook isn't registered or the bot is muted in the chat. Re-register the webhook:

openclaw channel telegram register-webhook

Verify with: curl https://api.telegram.org/bot<TOKEN>/getWebhookInfo — look for url matching your server and pending_update_count: 0.

Telegram: "chat not found" on outbound send

Your chat_id is wrong. Send a test message from the target chat to the bot, then read the incoming chat_id from openclaw logs. Update config.

Email: IMAP IDLE keeps disconnecting

Many email providers (Gmail, Outlook) drop IDLE connections every 10–30 minutes. OpenClaw should auto-reconnect; if not, enable periodic poll-mode fallback: openclaw config set channels.email.poll_interval 60s. This costs more API quota but is more reliable.

Email: outbound mail goes to spam

Standard email-deliverability hygiene applies — SPF, DKIM, DMARC records. If you're sending from a personal-use Gmail, OpenClaw uses the standard SMTP API and outbound mail is treated like any Gmail-sent message. For high-volume sending, switch to a transactional provider (Postmark, Resend, SES) and configure OpenClaw to use it.

WhatsApp: Business API only — Personal accounts don't work

OpenClaw's WhatsApp integration uses the WhatsApp Business API. Personal WhatsApp accounts cannot be used (Meta restricts this). You need a Business account and Meta-approved sender number. If you only have a Personal WhatsApp, use Telegram or Signal instead.

Provider-specific gotchas

Anthropic: "model not found" for newest Claude version

Your OpenClaw is older than the model. Either upgrade OpenClaw (npm install -g openclaw@latest) or pin to a known-good model version in config.

Ollama: "connection refused" on localhost:11434

Ollama daemon isn't running. ollama serve in a separate terminal (or set up as a system service). Verify: curl http://localhost:11434/api/tags should list installed models.

OpenAI: 401 even with a valid key

Most commonly: the key is for a different OpenAI project than the one you've enabled billing on. Check platform.openai.com → Settings → Billing. The active project on your key must have billing enabled.

OpenRouter: model name format

OpenRouter uses provider/model format: anthropic/claude-sonnet-4-6, not just claude-sonnet-4-6. If you see "model not found" via OpenRouter, that's almost always the cause.

Cost & billing

Bill is way higher than expected

Run the cost-breakdown report:

openclaw cost report --last 7d

Common high-cost causes ranked by frequency:

1. Runaway heartbeat skill — a cron-style skill is calling the model every tick. Check the heartbeat frequency and which skills subscribe.
2. Retry storm after errors — a skill is failing then retrying without exponential backoff. Add max_retries: 3 and retry_backoff: exponential to the skill config.
3. Wrong default model — defaulting to Opus when Sonnet would suffice can 5× costs. openclaw config set default.model claude-sonnet-4-6.
4. Long-context overflow — chat histories growing into 100K+ tokens per call. Enable summarization: openclaw config set memory.auto_summarize_after 50000.

Hard-cap monthly spending

openclaw config set cost.monthly_cap 50.00
openclaw config set cost.cap_action stop

OpenClaw stops calling the model when the cap is reached. Alternative action: cost.cap_action: downgrade automatically switches to a cheaper model.

Reading the logs

OpenClaw logs everything to /tmp/openclaw/openclaw-*.log (path varies by OS; openclaw config get log.path to confirm). Live-tail:

openclaw logs --tail              # last 100 lines, no follow
openclaw logs --tail --follow     # live tail (Ctrl+C to exit)
openclaw logs --since 1h          # last hour
openclaw logs --grep "ERROR"      # just errors

Log levels

Default is info. For deeper debugging:

openclaw config set log.level debug
openclaw restart

Debug-level adds full prompts and responses to the log. Useful for diagnosing "the agent said something weird" issues — but remember debug logs may contain sensitive context. Don't share verbatim.

When all else fails

1. Run openclaw doctor. Catches 90% of issues.
2. Read the logs. Almost every error has a clear cause in the last 100 log lines.
3. Restart the daemon. openclaw restart. Embarrassing how often it works.
4. Try a fresh config. Move ~/.openclaw/config.yaml aside, run openclaw setup for a clean slate. Most "weird state" bugs are config-related.
5. File an issue: github.com/openclaw/openclaw/issues. Include openclaw --version, openclaw doctor output, last 50 log lines, and a clear repro.

Related on this site

• Cross-platform troubleshooting database — searchable across all 7 agents
• OpenClaw Quick Start — full install walkthrough
• OpenClaw Security Hardening — locking down before production
• OpenClaw Cost Optimisation — getting bills under $10/month
• OpenClaw Configuration Reference — every config key explained