When OpenClaw stops working right after an update, the cause is almost always one of five things: your Node.js version is now too old, openclaw.json holds a key the new schema rejects, npm skipped OpenClaw's install scripts, the gateway is still running the old build, or the gateway has locked up while its status stays green. Run openclaw doctor, read the first error, and match it below.
Everything here is checked against OpenClaw 2026.9.8 (October 2026). Eight stable releases landed between September 3 and October 3, so "it worked yesterday" is normal, not a sign you broke something.
How do I find out which cause it is?
Run a short version of the ladder from the official troubleshooting page, in order, and stop at the first command that reports something wrong:
openclaw --version
openclaw status --all
openclaw gateway status --deep
openclaw doctor
openclaw channels status --probe
openclaw logs --followThen match what you see:
| Symptom | What you will see | Cause | Fix |
|---|---|---|---|
| Update or startup refuses to run | node-runtime-preflight, or node:sqlite truncates TEXT at embedded NUL | Node older than 24.16 or 26.1 | Upgrade Node, then rewrite the service |
| Gateway exits at once and stays down | Invalid config at ... with Unrecognized key | Retired or misplaced config key | openclaw doctor --fix, or bridge through 2026.9.5 |
| npm warns during the install | blocked because they are not covered by allowScripts | npm 12 skipped OpenClaw's lifecycle scripts | Reinstall with --allow-scripts=openclaw |
| Chats drop with close code 1006, or the old version still answers | Old version in openclaw gateway status --deep | The old process is still running | openclaw gateway restart |
| Every turn fails while status is green | Agent database execution admission is closed | Gateway agent database lock-up | Restart the gateway process |
Why does OpenClaw refuse my Node version?
OpenClaw 2026.9.3 dropped Node 22 and Node 25 and raised the Node 24 floor. The supported range is now >=24.16.0 <25 || >=26.1.0, with Node 26 recommended, according to the Node.js compatibility page. The reason is a bug in the node:sqlite TEXT decoder of Node 22.23.x, 24.15.0, 25.9.0 and 26.0.0 that silently truncates values at embedded NUL characters. A broken build prints Node <v>: node:sqlite truncates TEXT at embedded NUL (nodejs/node#61954); use 24.16+/26.1+ or a build with the fix, and openclaw update reports node-runtime-preflight with the required range while the old gateway keeps serving.
The trap is the service. The update troubleshooting page warns that switching your shell's Node "does not change a service's pinned Node path". After upgrading Node, rewrite the service definition so it points at the new runtime:
node --version
openclaw gateway install --force
openclaw gateway restartWhy does the gateway say my config is invalid after an update?
OpenClaw only accepts a config that fully matches its schema. "Unknown keys, malformed types, or invalid values cause the Gateway to refuse to start," per the configuration docs. The error looks like this one from issue #57391:
Invalid config at ~/.openclaw/openclaw.json: - agents.list.0: Unrecognized key: 'thinking'Invalid config exits with code 78, and the systemd unit carries RestartPreventExitStatus=78, so the service stops relaunching instead of looping (gateway docs). That is why it looks dead rather than crashing.
There are two flavours. The first is retired keys: settings older releases accepted and the new schema removed. gateway.controlUi.allowInsecureAuth is the one most people hit; our guide to the retired allowInsecureAuth setting explains what replaced it. Startup migrates simple legacy keys on its own, and openclaw doctor --fix handles the rest. One catch: for some retired inputs, including top-level heartbeat, routing.allowFrom, channels.telegram.requireMention and gateway.webchat, current doctor stops with recovery guidance instead of stripping them, and points you at the 2026.9.5 bridge release (config migrations).
The second is keys in the wrong place, usually pasted from another tool's docs. OpenClaw keeps MCP servers under mcp.servers, so a top-level mcpServers block is an unknown key; add servers with openclaw mcp add or openclaw mcp set instead (MCP registry docs). Provider settings, including a provider apiKey, belong under models.providers.<id> (custom providers), not at the root.
openclaw config file
openclaw config validate
openclaw doctor --fix
openclaw config validateDoctor keeps a broken hand edit as openclaw.json.clobbered.* beside the config (config validation).
Why did npm skip OpenClaw's install scripts?
npm 12 blocks unapproved lifecycle scripts by default. Without --allow-scripts=openclaw, npm reports OpenClaw's preinstall and postinstall steps as blocked because they are not covered by allowScripts, according to the install docs. npm 11.16 only warns and still runs them; npm 11.15 and older do not know the flag, so leave it off there. The npm approve-scripts openclaw command npm suggests fails for a global install with ENOMATCH.
npm --version
npm install -g openclaw@latest --allow-scripts=openclawFor pnpm the equivalent is pnpm add -g --allow-build=openclaw openclaw@latest.
Why is the old version still running after I updated?
Installing a package changes files on disk, not the process in memory. On the gateways we run, we have seen the result: npm swaps OpenClaw's content-hashed build files, so a gateway still running the old build crashes the moment it loads a file that no longer exists, and its WebSocket clients drop with close code 1006. Restart every gateway after an npm upgrade.
The other version is a split install: two copies of OpenClaw, with PATH or the service pointing at the older one. OpenClaw stamps each config write with meta.lastTouchedVersion, and an older binary refuses to start, stop or restart the service (updates and rollbacks):
which -a openclaw
openclaw --version
openclaw config get meta.lastTouchedVersion
openclaw gateway install --force
openclaw gateway restartOn 2026.9.2 specifically, openclaw gateway restart could hang under a systemd user service (issue #140821); a fix was merged on September 9, so update past that release. If the service manager itself is the problem, see systemd user services are unavailable.
Why does every message fail while the gateway looks healthy?
Reported against 2026.9.6, a single failed SQLite close seals the gateway's agent database, and from then on every turn fails with Agent database execution admission is closed while /readyz and openclaw status stay green. One reporter ran 21 hours in that state before noticing (#159652, #159789). Reconnecting the browser does not help; only a gateway process restart does. Both issues were still open on October 3, so do not assume 2026.9.7 or 2026.9.8 fixed it.
grep -i "admission is closed" /tmp/openclaw/openclaw-*.log
openclaw gateway restartWhat if doctor prints "Doctor complete" and never exits?
openclaw doctor --fix --non-interactive --yes once printed Doctor complete. and then left openclaw and openclaw-doctor processes running (issue #18502). That was fixed in February 2026, but our own automation still treats a hang as possible. Give unattended repairs a time limit, and check the gateway afterwards, since a repair that stops partway can leave it stopped:
timeout -k 15 600 openclaw doctor --fix --non-interactive --yes
openclaw gateway statusWhere did my cron jobs go?
Older guides tell you to edit ~/.openclaw/cron/jobs.json. That file store was retired in 2026.6.1: jobs, pending state and run history now live in the shared SQLite state database (cron docs). The docs now call the feature Automations; the command still registers as openclaw cron, with openclaw automations as an alias. If jobs.json or runs/*.jsonl files are still there, install 2026.9.7 and run openclaw doctor --fix before moving to the latest release.
How do I update OpenClaw safely next time?
The updating guide recommends openclaw update, which checks the new version while the old gateway serves, then activates, verifies and restarts it. For an npm install with a managed service, the manual path is below. Run each command only after the previous one succeeds:
mkdir -p ~/Backups/openclaw
openclaw backup create --output ~/Backups/openclaw --verify
openclaw gateway stop
npm install -g openclaw@latest --allow-scripts=openclaw
openclaw --version
openclaw doctor --fix
openclaw gateway start
openclaw gateway status --deep
openclaw health- Back up first. Sessions, cron jobs, auth profiles and pairing all live in SQLite now, and "older releases cannot open newer database schemas", so reinstalling the old package is not a rollback. Automatic config copies are not a full-state backup.
- Bridge old installs. If you are on a release from before July 2026, install 2026.9.5 first, run its doctor, then go to latest.
- Read what changed. Our OpenClaw 2.0 upgrade guide covers the 2026.8.1 changes, including the move of sessions into SQLite.
What this looks like when someone else runs the gateway
On Qoren's managed OpenClaw hosting, each agent's gateway is its own system service and these chores are automated. Once a day, every agent's own openclaw doctor runs; if it finds a problem, the repair runs under a ten minute limit, the check runs again, and a gateway the repair left stopped is started again. Anything still failing is flagged and recorded in the agent's audit trail. When a turn hits admission is closed, Qoren restarts that agent's gateway and retries the message once, at most once every ten minutes per agent so a persistent fault is not hidden. When the installed OpenClaw version changes on a machine, every running gateway on it is restarted.
Upgrades are deliberate, not automatic: an environment keeps its OpenClaw version until Qoren moves the pinned version, so it does not change under you, though it is not always the newest release. You can run the same checkup yourself with qoren agent doctor, described in the CLI reference.