Skip to main content
This reference covers supported Node.js lines, why the minimum versions exist, and how they changed across OpenClaw releases. For installation steps, see Node.js; for macOS companion app requirements, see macOS.

​
Supported versions

The exact engines expression is >=24.16.0 <25 || >=26.1.0. It remains the documented support policy and the package.json engine range used by package managers.

​
How the gate decides

Startup, doctor, Gateway runtime selection, update preflight, and installer runtime validation check the actual node:sqlite binding: it must be present, load a WAL-safe SQLite library, and preserve embedded and trailing NULs through TEXT, BLOB, and JSON round trips. The probe uses an in-memory database and caches the current process result; checks of another executable run the same probe in that executable with a bounded timeout. A build within the supported version table is refused if the probe fails. The running package’s startup guard and Gateway runtime selection admit a Node 24 or newer release outside the table when the probe passes, with the note unsupported version, capability probe passed. Its capabilities meet this package’s correctness gate, but it remains outside the tested support policy. This permits vendor backports without claiming support for their version. Node 22 and 23 remain excluded, and package manager engine checks still apply. Installers retain the numeric Node requirement and add the probe as a second gate. Package and Git update preflight also require the selected target’s engines.node range numerically, including any fallback runtime. A passing probe cannot relax another package’s requirements: an older release may still enforce its version table at startup. Update recovery recommends the lowest standard release satisfying both the candidate’s engine range and this updater’s supported range above. For example, an older candidate requiring >=22.19.0 still needs a recommendation of 24.16.0 so the updater can run. If the ranges have no common supported release, the message identifies both ranges and asks you to select a compatible target. After selecting the runtime, continue through the retained absolute launcher so the updater rechecks prefix and service ownership before installation; follow the complete recovery sequence.

​
Why the floors exist

The SQLite WAL-reset corruption bug requires a safe loaded library: SQLite 3.51.3+, 3.50.7+ within 3.50.x, or 3.44.6+ within 3.44.x. OpenClaw validates the library actually loaded because Node builds linked to shared system SQLite can use a different version from Node’s own metadata. Separately, the node:sqlite TEXT decoder in Node 22.23.x, 24.15.0, 25.9.0, and 26.0.0 silently truncates values at embedded NUL characters. The first fixed releases are Node 24.16.0 and 26.1.0; a WAL-safe SQLite library does not fix this decoder. Node 23 was excluded earlier for incompatible node:sqlite behavior.

​
Platform consequences

Official Node 24+ binaries require macOS 13.5+, so macOS 11 through 13.4 no longer support the Node-based CLI or Gateway. The companion app has separate macOS requirements. Supported Node lines have no official Linux ARMv7 builds. Use a 64-bit operating system on compatible ARM hardware, or another supported host. On RPM-based distributions, the installer preserves a supported distro-owned Node package that links unsafe system SQLite and provisions a separate user-space runtime for OpenClaw.

​
What the installer provisions

Recommended, supported, and provisioned are three different things. See Installer internals for provisioning details.

​
Check your runtime

Use a supported Node release for the recommended installation path. A broken TEXT decoder is refused with this diagnostic:
Node <v>: node:sqlite truncates TEXT at embedded NUL (nodejs/node#61954); use 24.16+/26.1+ or a build with the fix

​
History across releases

Rows identify the first effective release, including a beta when applicable. Recommendation and installer changes are listed even when the numeric requirement stayed the same.