Bumping Node: what would break

Research only — nothing was changed, built or installed. Registry data and image contents read on 2026-09-14, against the container currently running Node v22.23.2 / npm 10.9.8.

1. engines, as published

Raw values from npm view <pkg>@<version> engines, so you can check the reading.

Nothing caps Node below 24. The claude-code and codex values are also less load-bearing than they look: both now ship platform binaries (@anthropic-ai/claude-code-linux-x64, @openai/codex-linux-x64), so Node is a launcher shim rather than the runtime. Same for opencode-ai, which ships opencode-linux-x64. Of the npm-installed CLIs, gemini-cli is the one that genuinely runs on the system Node — and it asks only for >=20.

2. The two non-npm CLIs — neither is at risk

Both checked on the running container rather than assumed.

• fx 0.0.5 — /usr/local/bin/fx is an ELF 64-bit, statically linked executable installed from a release tarball. No Node involvement at all, at build time or run time. no risk
• hermes v0.21.2 — ~/.local/bin/hermes is a three-line shell shim whose last line is exec "~/.hermes/hermes-agent/venv/bin/python" "~/.hermes/hermes-agent/hermes" "$@". It runs on its own venv Python 3.11.2, not on Node. no runtime risk

"engines": { "node": "^22.22.0 || ^24.11.0 || >=26.0.0",
             "npm":  "<11.10.0 || >=11.17.0" }

3. Agent Manager's own server

server/package.json declares "engines": { "node": ">=20.19" } — advisory only; there is no .npmrc with engine-strict anywhere in the repo, so engines produce warnings, not install failures. web/package.json declares none. There is no .nvmrc and no CI job pinning a Node version, so nothing else in the repo needs editing alongside the Dockerfile.

Native dependencies — all N-API, which is why this is low risk

Compiled addons are what actually break across Node majors, and only if they use NAN/V8 APIs. Neither of these does.

There is no better-sqlite3 and no node-gyp module using the V8 API anywhere in the dependency set.

The SQLite you asked me to look at first is Node's own

The durable-state / trace work does not use an npm SQLite package. It uses the built-in node:sqlite, imported defensively in two places so a Node without it degrades rather than crashes:

server/src/traces.js:514  try { ({ DatabaseSync } = await import('node:sqlite')); } catch { /* older node: skip opencode */ }
server/src/share.js:362   try { ({ DatabaseSync } = await import('node:sqlite')); } catch { return null; }

The API surface used is small and read-only — new DatabaseSync(path, { readOnly: true }), .prepare(), .get(), .all(), one .exec(). That is the original core of the module and is unchanged from 22.5 onward. It runs unflagged today; nothing in entrypoint.sh or the package scripts passes --experimental-sqlite or suppresses warnings. The module remains experimental on 24, so expect the same ExperimentalWarning on stderr, and treat the opencode/hermes trace suites as the thing to re-run rather than assuming.

4. Which Node, and why 24

Take Node 24. It is the LTS line, it satisfies OpenClaw with five patch releases of headroom above the 24.16.0 floor, and it is the smaller jump. Node 26 would also work but buys nothing here and puts the fleet on a non-LTS line that will churn. Node 25 is excluded by OpenClaw and is effectively dead anyway — last release was March.

node:24-bookworm exists on Docker Hub (as do lts-bookworm and krypton-bookworm, which alias it). Keeping bookworm is the single biggest blast-radius reducer: the Debian base, its python3 3.11, apt package set, and glibc all stay exactly as they are. Hermes's venv and the /opt/py data stack are built on that Python — moving to a trixie-based tag would rebuild both against a different interpreter for no reason.

Both FROM lines change (Dockerfile:2 web builder, :11 runtime). The comment on :10 — "Node 22+: required by OpenClaw (22.19+)" — is stale and should be corrected while you are there.

5. Wider blast radius

• npm goes 10.9.8 → 11.19.0. The biggest single change, and the reason for the Hermes note above. Nothing in the repo sets engine-strict, so tightened engines elsewhere stay warnings.
• Playwright / Chromium. playwright@1.62.1 allows >=20, so the pinned-revision install step is fine. It is worth re-reading the Dockerfile's own comment there: the revision must match what the app pins, and PLAYWRIGHT_SKIP_BROWSER_GC=1 is what keeps the shared /opt/pw-browsers working. A bump does not change that logic, but it does re-run it.
• uv, hf, and the Python stack. Installed from astral.sh and via uv tool against /usr/bin/python3. No Node coupling. Unaffected as long as the Debian base does not move.
• The || echo "… failed" pattern. gemini-cli, opencode, openclaw, ccusage, uv, hf, playwright and hermes all swallow their own failure. That is precisely why a missing OpenClaw shipped green build after green build. After the bump, the build log is the only evidence that anything installed.
• Nothing else is pinned to 22. No .nvmrc, no CI Node matrix, no other node:22 reference in the repo.

6. What to check after the build

1. openclaw --version — the whole point; it should exist for the first time.
2. claude, codex, gemini, opencode, hermes, fx, ccusage all still answer --version.
3. Grep the build log for install failed and for the Hermes step — a green image is not evidence.
4. server/node_modules/node-pty/build/Release/pty.node exists, and terminal panes actually render (that also exercises the libghostty prebuild).
5. Open an opencode or hermes session in the Reader — that is the node:sqlite path. The server suites test/reader-protocol, test/trace-window and test/trace-tail cover it; run them individually, since the runner stops at the first failure and test/crons.test.mjs #4 is known-red on main.
6. npm --version inside the image, against Hermes's excluded window of 11.10.0–11.16.x.

7. What I could not determine without building

Stated rather than guessed, with the test for each:

• Does node-pty compile clean against Node 24 headers? The source is N-API and the toolchain is present, so it should — but the proof is the build. Test: the npm install --omit=dev layer, and pty.node existing afterwards.
• Does Hermes's installer enforce its own engines? It is a vendor install.sh fetched at build time; I did not run it. Test: the Hermes step in the build log, and hermes --version after.
• Does OpenClaw actually work once installed, as opposed to merely installing? It has never run in this image. Its sqlite-vec dependency is prebuilt, so installation should succeed — first launch is a separate question.

Sources: npm registry (npm view … engines), nodejs.org/dist/index.json for release lines and bundled npm, Docker Hub tag list, and direct inspection of the running container and a fresh read-only clone at a74b327. No file on the box was modified.