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

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 <25`	LTS line used by CI and the Linux installer.
Node 25	Unsupported	—	Excluded by the current TEXT decoder floor.
Node 23	Unsupported	—	Excluded earlier for incompatible `node:sqlite` behavior.
Node 22	Unsupported	—	Unsupported since the 24.16.0/26.1.0 floor.

The exact engines expression is >=24.16.0 <25 || >=26.1.0. It is enforced by package.json engines during npm installation, the startup runtime guard for every openclaw command, and the installer scripts.

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.

Platform	Installer path	Node provisioned
Linux	`install.sh`: apt/dnf/yum via NodeSource	Node 24.x LTS.
Linux and macOS	Rootless `install-cli.sh`	Node 24.19.0 by default; existing runtime reuse and explicit version selection can differ.
macOS	`install.sh`: Homebrew `node`	Node 26; no exact patch pinned, and an existing supported Node can be retained.
Windows	`install.ps1`: Chocolatey, Scoop, or winget	LTS package; no exact patch pinned, validated after installation.
Windows	`install.ps1`: portable fallback	Latest 26.x Windows zip.

See Installer internals for provisioning details.

Check your runtime

node -v

Upgrade Node before updating OpenClaw if your version is unsupported. The startup guard prints this requirement sentence:

openclaw requires Node >=24.16.0 <25, or >=26.1.0.

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.

Release	Node requirement	What changed and why
Unreleased (main)	`>=24.16.0 <25 \|\| >=26.1.0`	Raises the Node 24 floor and drops Node 22 and 25 to prevent embedded-NUL TEXT truncation; Node 23 remains excluded. Official Node-based support for macOS 11–13.4 and Linux ARMv7 provisioning ends. #140672
v2026.8.2	`>=22.22.3 <23 \|\| >=24.15.0 <25 \|\| >=25.9.0`	Preserves supported RPM-owned Node packages with unsafe system SQLite and provisions a separate user-space runtime. The numeric range and loaded-library safety requirement stay unchanged. #134166
v2026.8.1	`>=22.22.3 <23 \|\| >=24.15.0 <25 \|\| >=25.9.0`	Rootless defaults advance to 24.19.0, or 22.23.2 on ARMv7. Linux package provisioning returns to Node 24 LTS to avoid prerelease repository builds. #130369
v2026.8.1-beta.3; stable v2026.8.1	`>=22.22.3 <23 \|\| >=24.15.0 <25 \|\| >=25.9.0`	Centralizes release classification in `node-version.mjs`, rejecting prerelease, nightly, and malformed version labels. #124812
v2026.7.2-beta.5; stable v2026.8.1	`>=22.22.3 <23 \|\| >=24.15.0 <25 \|\| >=25.9.0`	Recommends Node 26 for faster Gateway startup and lower memory use than Node 24. CI and release workflows retain Node 24. #114399
v2026.7.1; main v2026.7.2-beta.1	`>=22.22.3 <23 \|\| >=24.15.0 <25 \|\| >=25.9.0`	Requires builds carrying the SQLite WAL-reset fix, validates the actual loaded SQLite library, and excludes all Node 23. Shipped through a release cherry-pick. #106065
v2026.7.1-beta.2	`>=22.19.0 <23 \|\| >=23.11.0`	Excludes Node 23.0–23.10 for incompatible SQLite behavior in the dialect’s `StatementSync.columns()` path. Superseded before stable v2026.7.1. #99832
v2026.5.16-beta.7; stable v2026.5.18	`>=22.19.0`	Raises the floor with the Pi dependencies’ update to 0.75.1. Node 24 remains recommended.
v2026.5.9-beta.1; stable v2026.5.12	`>=22.16.0`	Raises the floor for the native SQLite Kysely dialect’s use of `StatementSync.columns()` to identify result-producing statements. #78921
v2026.3.24-beta.2; stable v2026.3.24	`>=22.14.0`	Lowers the floor from 22.16 so npm installs and self-updates do not strand existing Node 22.14 users.
v2026.3.12	`>=22.16.0`	Raises the floor from 22.12 and makes Node 24 the default/recommended line for installs, CI, and releases. The recorded change does not identify a specific missing API.
v2026.2.6	`>=22.12.0`	Aligns the startup guard with the package requirement because Matrix’s SDK requires 22.12 and older runtimes produce misleading module-not-found errors. #5370
v2026.1.5 (earlier v2.0.0-beta3)	Package `>=22.12.0`; startup `>=22.0.0`	Raises the package floor from 22.0 to 22.12 without a recorded API-specific reason. Startup validation temporarily retains the older minimum.
Before 2026	`>=22.0.0`	The earliest package engine declaration requires Node 22; no narrower runtime-feature justification is recorded.

Install overview

Runtimes

Maintenance

Containers

Hosting

Advanced setup

Node.js compatibility

Supported versions

Why the floors exist

Platform consequences

What the installer provisions

Check your runtime

History across releases

​Supported versions

​Why the floors exist

​Platform consequences

​What the installer provisions

​Check your runtime

​History across releases

​Related

Supported versions

Why the floors exist

Platform consequences

What the installer provisions

Check your runtime

History across releases

Related