Which Node.js versions does OpenClaw 2026.9.9 support, and why did release 2026.9.3 drop Node 22 and Node 25?
answer
- an engines range with two arms
- the recommended line is the newer one
- an embedded-NUL bug in node:sqlite
- macOS 13.5 and no ARMv7
basics
~10 sOpenClaw 2026.9.9 needs Node 24.16+ or Node 26.1+, with Node 26 recommended. Release 2026.9.3 dropped Node 22 and 25 because their node:sqlite TEXT decoder silently truncates values at embedded NUL characters.
solid answer
~40 sThe engines range is `>=24.16.0 <25 || >=26.1.0`. Node 26 is recommended for faster Gateway startup and lower memory use; Node 24 LTS is what CI and the Linux installer use. Node 22, 23 and 25 are unsupported. The floor was raised in 2026.9.3 because the `node:sqlite` TEXT decoder in Node 22.23.x, 24.15.0, 25.9.0 and 26.0.0 truncates values at embedded NUL characters, and OpenClaw keeps its auth stores and agent state in SQLite; 24.16.0 and 26.1.0 are the first fixed releases. Startup and Doctor also probe the loaded SQLite library for the WAL-reset fix. Upgrade Node before OpenClaw. Host consequences: official Node 24+ binaries need macOS 13.5+, and there are no Linux ARMv7 builds, so a Raspberry Pi needs a 64-bit OS.
go deeper
Remember the two supported lines, Node 24.16+ and Node 26.1+, and that Node 26 is the recommended one.
Explain that the floor exists because of a node:sqlite TEXT truncation bug and a SQLite WAL safety requirement, and that the installer provisions Node.
Plan upgrades in the right order, check the runtime the managed service uses, and rule out hosts that cannot run the floor, such as ARMv7 or macOS before 13.5.
Treat the runtime floor as a hosting constraint: a fleet of older Macs or 32-bit boards becomes a migration project rather than a version bump.
## The supported range OpenClaw 2026.9.9 declares the engines range `>=24.16.0 <25 || >=26.1.0` in its `package.json`. Package managers enforce it, and the runtime checks below back it up. | Node line | Status | Minimum | Notes | | --- | --- | --- | --- | | Node 26 | Recommended | 26.1.0 | Faster Gateway startup and lower memory use than Node 24 | | Node 24 | Supported | 24.16.0 | The LTS line used by CI and the Linux installer | | Node 25 | Unsupported | none | Excluded by the TEXT decoder floor | | Node 23 | Unsupported | none | Excluded earlier for incompatible `node:sqlite` behaviour | | Node 22 | Unsupported | none | Unsupported since the 24.16.0 and 26.1.0 floor | ## Why 2026.9.3 moved the floor OpenClaw keeps much of its durable state in SQLite through Node's built-in `node:sqlite`: the shared state database, per-agent databases with their auth profiles, and other runtime data. Two runtime bugs matter: - **The TEXT decoder bug.** In Node 22.23.x, 24.15.0, 25.9.0 and 26.0.0, the `node:sqlite` TEXT decoder silently truncates a value at an embedded NUL character. Data does not fail loudly; it comes back shorter. The first fixed releases are 24.16.0 and 26.1.0, so release 2026.9.3 raised the floor to those versions and dropped Node 22 and 25, a breaking change in its changelog. - **The SQLite WAL-reset corruption bug.** OpenClaw also requires a WAL-safe SQLite library (3.51.3 or newer, or the patched 3.50.x and 3.44.x lines) and checks the library actually loaded, because a Node build linked to the system SQLite can differ from what Node's own metadata reports. Startup, Doctor, Gateway runtime selection, update preflight and the installers all run these checks. A runtime that fails them is refused with a diagnostic rather than allowed to corrupt state. ## What it means for the host you pick 1. **macOS:** official Node 24 and 26 binaries need macOS 13.5 or later, so an older Mac cannot run the Node-based CLI or Gateway. The OpenClaw menu bar app has its own, higher requirement. 2. **Raspberry Pi and other ARM boards:** supported Node lines have no official Linux ARMv7 builds. Use a 64-bit OS on compatible hardware; 32-bit Raspberry Pi OS is out. 3. **RPM-based Linux:** when a supported distro Node links an unsafe system SQLite, the installer keeps the distro package and provisions a separate user-space Node for OpenClaw. 4. **Containers:** the official image ships its own runtime, so the host's Node version does not matter there. ## How the tooling helps, and where it stops - The installer script provisions Node when it is missing: Node 26 through Homebrew on macOS, Node 24 LTS through NodeSource on Linux. - Run interactively on an incompatible Node, the CLI first looks for a compatible runtime it already knows about (its private runtime, the Node recorded in the managed Gateway service, `PATH`, common version managers). If none passes, it offers `Update NodeJS: Y/N [N]`; **Y** downloads a checksum-verified Node into `~/.openclaw/tools/cli-node` and retries the command. It does not replace the system Node or restart Gateway services. - `openclaw update` checks the target release's Node requirement before replacing the package and can provision a private runtime on supported platforms. - Non-interactive, CI and `--yes` runs never prompt or install Node at startup. The operational rule from the docs: **upgrade Node before upgrading OpenClaw**, then run `openclaw doctor` and check `openclaw gateway status`. ## Checking a host before you commit to it 1. `node -v` on the host: `v26.1.0` or newer is the recommended default, and a 24.x from `v24.16.0` up is supported. 2. `uname -m` on an ARM board should report `aarch64`, the 64-bit architecture. 3. After installing, `openclaw doctor` runs the same SQLite capability probe as startup. A broken decoder is refused at startup with a message naming the problem, `node:sqlite truncates TEXT at embedded NUL`, and the versions to move to. Read it as an instruction to change the runtime, not as an OpenClaw bug to work around. ## Mistakes that cost an evening - Staying on Node 22 because it "was fine last month": it was supported before 2026.9.3 and is refused now. - Treating any 24.x as fine: 24.15.0 is the broken decoder release. - Installing Node 26 for your shell with a version manager and assuming the managed Gateway service follows; the service records its own Node path, so check it. - Flashing 32-bit Raspberry Pi OS to save memory.
- Why is silent TEXT truncation worse for OpenClaw than a crash would be?Much of OpenClaw's durable state, including the auth stores and per-agent databases, lives in SQLite. A truncated value is written and read back without an error, so a credential or transcript can be quietly shortened and the failure appears much later, far from its cause. Refusing the runtime at startup turns a silent data bug into a clear message telling you to upgrade Node.
- Your Gateway runs as a managed service, and you just switched your shell to Node 26 with a version manager. What could still be wrong?The managed Gateway service records which Node it runs, so it may still start on the old runtime. Run `openclaw doctor` and `openclaw gateway status`; a restarting `openclaw update` rebinds the owned service to the invoking install on supported platforms, while on Windows or with operator overrides it keeps the existing service installation.
- Any Node 24 release works, including 24.15.0.
- Node 22 is still supported because it was the original floor.
- OpenClaw runs on 32-bit Raspberry Pi OS if you add swap.
- Upgrade OpenClaw first and let it fix Node afterwards.
- Node 25 is fine because it is newer than Node 24.
Assumes OpenClaw 2026.9.9; the Node 24.16+ or 26.1+ floor arrived in 2026.9.3, and earlier releases accepted Node 22 and 25.