Runtimes
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 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.
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 -vUse 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.
| Release | Node requirement | What changed and why |
|---|---|---|
| Unreleased (main) | Unchanged support policy | Replaces decoder version-only admission with an in-memory NUL round-trip probe; capable vendor builds on Node 24+ may run with an unsupported-version note. Node 22/23 remain excluded. |
| v2026.9.3 | >=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. |
