OpenClaw Troubleshooting — Every Error, Every Fix

Broke after a recent update? Start here (checked 2026-09-30)

Problems introduced by specific OpenClaw releases, newest first. Each links to the fix OpenClaw itself published.

macOS app crashes on every launch after updating to 2026.9.6

The first 2026.9.6 macOS build crashed at launch (issue #156861). OpenClaw replaced it at 09:52 UTC on 2026-09-24 with a rebuilt, notarized 2026.9.6 build that contains the fix (#156881).

• Your app won't open: download the 2026.9.6 DMG from the OpenClaw releases page and install it once, over the top. In-app updating can't help, because the app can't start.
• Still on 2026.9.5: updating from inside the app now installs the fixed build.
• npm / Gateway installs (headless, servers, VPS) were never affected. The npm package did not change.

Update fails, or text comes back cut off, after 2026.9.3 — Node version

From 2026.9.3, OpenClaw requires Node 24.16.0+ (on 24.x) or Node 26.1.0+; Node 26 is recommended. Node 22, 23 and 25, Node 24 before 24.16.0 and Node 26 before 26.1.0 are unsupported. The reason is SQLite: older builds can truncate stored text, so upgrade Node before you update OpenClaw, not after.

Since 2026.10.6, the patched runtimes are required: Node 24.22.1+ on the 24 line or 26.12.1+ on the 26 line. Per the release notes they reject TLS chains signed with the compromised certificate keys fixed in the October 2026 Node.js security releases, Docker images ship Node 24.22.1, and updates (run with openclaw update) are blocked with recovery guidance before installing on an older Node, so a running install is not broken. The install docs still list 24.16.0+ / 26.1.0+ as the minimum and strongly recommend the patched versions.

node -v                      # need v24.16.0+ or v26.1.0+
nvm install 26 && nvm use 26  # or your package manager / fnm / Volta
npm install -g openclaw

If you start openclaw under an unsupported Node, it looks for a compatible runtime it already knows about (its private runtime, the Node recorded in the Gateway service, then PATH, nvm, fnm, Volta and Homebrew) and re-runs the command with it. That covers many cases automatically, but don't rely on it for the upgrade itself. macOS 11–13.4 and official Linux ARMv7 provisioning can't meet the new floor for Node-based installs. See OpenClaw's Node requirements.

Skills missing or read-only after 2026.9.3

2026.9.3 replaced workspace ownership of Workshop skills with one writable Workshop collection per agent and retired skills.workshop.allowSymlinkTargetWrites. Startup and openclaw doctor --fix migrate skills whose ownership is clear. Skills with ambiguous ownership are deliberately left in place for you to review, which is why one can seem to vanish from an agent. Run openclaw doctor --fix, then check what it reports as unresolved.

Updating to 2026.9.7: backups, rollback and old installs

• Make and verify a full backup first. New verified backups check that every agent database recorded at capture is present; a config-only export is not a recovery backup. Older archives may have unknown completeness.
• Automatic rollback has limits. Database restoration needs a snapshot taken while OpenClaw was stopped, with the new version never started. The updater removes its snapshots after a verified successful update, but a failed or unverified update keeps them and may leave OpenClaw stopped, so check the update report before deleting anything. Snapshots need substantial free disk space and can block an update that would otherwise work.
• Installed before June 2026? Upgrade through 2026.9.5 first, following the docs' very old versions steps, and run openclaw doctor --fix there before continuing.
• Replacing OpenClaw by hand, or using a custom container entrypoint? Run openclaw doctor --fix before starting it. If a repair was deferred, fix the reported problem and rerun openclaw update repair.
• Tasks and TaskFlow are gone. Their panels, commands and APIs were removed in 2026.9.7. Use subagent controls, ACP sessions, background processes, automation history or Lobster pipelines instead.

Source: OpenClaw 2026.9.7 release notes.

An update failed, or you want to wait out the churn

• Rehearse first: openclaw update --dry-run reports what would change without applying it.
• A failed update tries to roll back. When the rollback verifies, the previous version keeps running; interactively, OpenClaw then offers to diagnose or report the failure. openclaw update repair finishes an interrupted repair, and openclaw update cleanup --dry-run shows leftover recovery files.
• Hold back on a slower line: openclaw update --channel extended-stable moves a Gateway to OpenClaw's LTS equivalent — the end-of-July code plus security and reliability fixes (2026.7.35, released 2026-09-21, is Gateway-only).
• Uninstalling to start over is now safer: since 2026.9.1, openclaw uninstall removes only the service and keeps your data by default.

Running OpenClaw inside NemoClaw? OpenClaw 2026.9.1 rejects the legacy auth profile NemoClaw generates on managed routes — see the NemoClaw fix. Using Claude Opus 5.5 as your model? Its breaking API changes are covered in the thinking-disabled 400 fix.

"OpenClaw is not replying"

The most-searched OpenClaw issue. Work down this list.

1. The Gateway isn't running

openclaw status
openclaw gateway status
openclaw gateway start      # if it's stopped

2. Your sender isn't allowed

Each channel has a dmPolicy: pairing, allowlist, open or disabled. With pairing, an unknown sender gets a pairing code that you approve (openclaw pairing approve <channel> <code>). With allowlist, only IDs in allowFrom get through, and everyone else is silently ignored. That's by design.

openclaw config get channels.telegram.dmPolicy
openclaw config get channels.telegram.allowFrom

Add your sender ID to allowFrom (or switch to pairing), run openclaw config validate, then openclaw gateway restart.

3. Group chats need a mention

In groups the bot normally answers only when mentioned. The Telegram setting is per group, for example channels.telegram.groups."*".requireMention for all groups. Mention the bot, or set it to false for groups where it should answer freely. See Telegram setup.

4. The provider call is failing

If the model call fails, there's no reply. Look for 401/402/403/429 in the logs:

openclaw logs --plain --limit 500 | grep -E "401|402|403|429"

401 means a bad key, 402 means no credit, and 429 is covered below.

5. A skill is failing

openclaw skills check
openclaw logs --plain --limit 500 | grep -i error

Disable a suspect skill while you investigate: openclaw config set skills.entries.<name>.enabled false.

6. Still stuck

openclaw doctor checks config, channels, credentials and skills, and openclaw doctor --fix repairs what it safely can. openclaw channels status --probe tests each channel's connection.

"HTTP 429 — Rate limit exceeded"

Provider-side 429 (most common)

Your model provider is throttling your account. OpenClaw already handles short spikes: per its model failover docs, it first retries the same model for temporary rate limits (bounded, keeping the transcript), then rotates auth profiles within the provider, then falls back to the next model in agents.defaults.model.fallbacks. So the durable fix is to configure fallbacks:

// ~/.openclaw/openclaw.json
{
  agents: {
    defaults: {
      model: {
        primary:   "anthropic/claude-sonnet-5-5",
        fallbacks: ["openrouter/anthropic/claude-sonnet-5.5"]   // use your provider's model ids
      }
    }
  }
}

Then run openclaw config validate. If 429s persist, your provider plan's per-minute limits are too low for your usage, so raise the plan or spread the load.

Heartbeat or cron running too often

A frequent heartbeat burns requests around the clock. Check agents.defaults.heartbeat.every and lengthen it (for example "2h"), or set it to "0m" to turn the heartbeat off:

openclaw config get agents.defaults.heartbeat.every
openclaw config set agents.defaults.heartbeat.every "2h"

Correction 2026-09-27: this section previously suggested default.model, a YAML providers: block, rate.max_per_minute and heartbeat.interval. None of those exist in OpenClaw's config.

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 now requires Node 24.16+ or Node 26.1+ (Node 26 recommended); Node 22 stopped being supported in 2026.9.3. Check with node -v and upgrade via your package manager or nvm — before you update OpenClaw.

Skill install fails with manifest validation

The skill's SKILL.md front matter is malformed or references a permission OpenClaw doesn't recognize (often because the skill is for an older OpenClaw version). Run openclaw skills check and openclaw skills info <name> to see what's wrong. If the skill is from ClawHub, check its page for a newer version or report it there. If it's community-made, prefer an official equivalent or write your own (see the skills guide).

Memory & database

"database is locked"

Usually two OpenClaw processes are using the same state directory. Find duplicates with ps aux | grep openclaw | grep -v grep and stop the extra one. To run several instances on one host on purpose, give each its own profile (--profile <name>), which keeps separate state. Don't point two Gateways at one directory.

Note: OpenClaw's memory engine is builtin only. The old memory.backend / QMD settings were retired, and openclaw doctor --fix removes them. There is no PostgreSQL memory backend to switch to.

Memory index growing large

Inspect it with openclaw memory status --deep, and prune old sessions with openclaw sessions cleanup. Take a backup first: openclaw backup create.

Lost memory after an upgrade

Restore from a backup archive with openclaw backup restore <archive> --target <fresh-directory>, and make openclaw backup create part of every upgrade. Your long-term notes are plain files in the workspace (MEMORY.md and memory/), so a copy of the workspace is also a backup.

Channel-specific issues

Telegram: the bot doesn't see messages

Probe the channel with openclaw channels status --probe. In groups, check the mention rule above and Telegram's bot privacy mode (BotFather /setprivacy). If api.telegram.org fails over IPv6 on your host, see the IPv4 fix in our Telegram guide.

Telegram: "chat not found" on outbound send

The target chat ID is wrong or the bot was never added to that chat. Send a message from the target chat, read the incoming chat ID from openclaw logs --follow, and update your config.

Email

OpenClaw reads email through triggers: a Gmail integration, or the IMAP email trigger plugin for other providers, which runs sender-gated, isolated reader sessions. For an agent that manages a mailbox with a CLI, see our email guide.

WhatsApp

WhatsApp connects by QR pairing and keeps more state on disk than Telegram. OpenClaw's docs recommend starting with Telegram, which needs only a bot token. For groups, the bot can wake only when mentioned and keep each group's session separate from your DMs.

Correction 2026-09-27: this section previously described a WhatsApp Business-API-only integration and a channels.email.poll_interval setting. Neither matches OpenClaw's docs.

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-5.5, not just claude-sonnet-5.5. If you see "model not found" via OpenRouter, that's almost always the cause.

Cost & billing

Bill is higher than expected

openclaw gateway usage-cost --days 7

Common causes:

• Heartbeat or cron too frequent. Lengthen agents.defaults.heartbeat.every and review scheduled automations.
• An expensive primary model for routine chat. Set a cheaper agents.defaults.model.primary and keep the strong model as a fallback or for specific agents. See cost optimisation.
• Long transcripts. Compaction settings live under compaction in the config. Reset long sessions, or give scheduled jobs isolated sessions.

Hard spending caps

OpenClaw has no built-in monthly cap setting. OpenClaw's own docs recommend a dedicated API key with spend limits at your provider or router, which stops spending at the source without changing OpenClaw config.

Correction 2026-09-27: this section previously listed cost.monthly_cap, cost.cap_action, memory.auto_summarize_after and per-skill max_retries. None of these exist in OpenClaw.

Reading the logs

By default the Gateway writes JSONL logs to /tmp/openclaw/openclaw-YYYY-MM-DD.log (named profiles add the profile name). If you set logging.file, they go there instead. Redaction is always on.

openclaw logs --follow                     # live tail
openclaw logs --plain --limit 500          # recent lines as plain text
openclaw logs --json                       # structured output
openclaw logs --plain --limit 5000 | grep -i "telegram"

Log levels

Set logging.level in ~/.openclaw/openclaw.json (for example "debug"), validate, and restart the Gateway. Debug output can contain sensitive context, so don't paste it publicly.

When all else fails

1. openclaw doctor, then openclaw doctor --fix.
2. Read the last few hundred log lines (openclaw logs --plain --limit 500).
3. openclaw gateway restart.
4. Rule out config: back up ~/.openclaw/openclaw.json, then rerun openclaw onboard or openclaw configure.
5. File an issue at github.com/openclaw/openclaw/issues with openclaw --version, doctor output, recent logs 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