Node.js compatibility

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 check uses an in-memory database and caches the current process result; checks of another executable run the same check in that executable with a bounded timeout. A build within the supported version table is refused if the check fails.

The running package's startup guard and Gateway runtime selection admit a Node 24 or newer release outside the table when the check passes, with a note that the version is unsupported but its capabilities passed validation. 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 check 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 check 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.

V8 compiler settings

On Node 24 and 26, process.exit() can hang forever after a command has printed its output: Node joins V8's background threads while a Maglev or concurrent Sparkplug compile job waits for a garbage collection the exiting main thread never runs (nodejs/node#64274). OpenClaw's CLI, Gateway, hook relay, and macOS node worker therefore start with Maglev and concurrent Sparkplug turned off, the tiering Node 22 used; TurboFan still optimizes hot code. Passing --maglev or --concurrent-sparkplug to node keeps that compiler enabled.

Platform consequences

Official Node 24+ macOS binaries are built for macOS 13.5+, the oldest release Node supports. macOS does not block them on older releases, and the CLI and Gateway have been observed running on macOS 12 with official Node 24. OpenClaw does not test or support macOS 11 through 13.4, so features that ship their own native binaries can still fail there. 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

node -v

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.

Related

• Bun compatibility
• Installer internals
• Linux
• macOS
• Node.js