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.

Related

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