openclaw - 💡(How to fix) Fix Clarify Node defaults between install.sh and local-prefix install-cli.sh [1 pull requests]

Summary

The OpenClaw install story is currently confusing for end users because different official install paths imply different Node defaults:

• install.sh defaults to Node 24.
• Docs say Node 24 is the recommended runtime.
• install-cli.sh defaults to Node 22.22.0 for local-prefix installs.
• install-cli.sh also skips replacing the local managed Node if an existing managed Node major is already >=22.

That means a user can reasonably end up with:

• system/global Node: v24.x
• OpenClaw local-prefix managed Node: v22.22.0

This is technically supported, but it is surprising and can cause native-module confusion when OpenClaw-adjacent tools are installed or rebuilt with the wrong Node.

Why this matters

I hit this in a real local-prefix setup under ~/.openclaw.

OpenClaw gateway was running with:

~/.openclaw/tools/node-v22.22.0/bin/node

My shell/global Node was:

v24.15.0

A QMD install used by OpenClaw memory had native modules rebuilt under Node 24, but OpenClaw loaded/invoked it from the managed Node 22 runtime. That produced native ABI errors like:

NODE_MODULE_VERSION 137
This version of Node.js requires NODE_MODULE_VERSION 127

The immediate fix was to isolate QMD under ~/.openclaw and run it with the same managed Node as the gateway. But the root confusion came from the official install paths making it unclear which Node OpenClaw “should” be using.

Current source/docs behavior

From current source/docs:

• scripts/install.sh has NODE_DEFAULT_MAJOR=24.
• docs/install/node.md says Node 24 is recommended and Node 22.16+ is supported.
• docs/install/installer.md says install-cli.sh --node-version defaults to 22.22.0.
• The served install-cli.sh also defaults to OPENCLAW_NODE_VERSION:-22.22.0.
• install-cli.sh skips installing a new managed Node if the existing managed Node major is already >=22.

Expected behavior

One of these should be true:

1. The local-prefix installer should also default to Node 24, matching the main installer and docs.

or:

1. The docs should explicitly say that local-prefix installs intentionally pin a managed Node 22 LTS runtime even though Node 24 is recommended for normal/global installs.

or:

1. install-cli.sh should surface a clear message during install/update like:

Using local managed Node 22.22.0 for reproducible local-prefix runtime.
This may differ from your shell/global Node. Use --node-version 24.x.x to opt into Node 24.

Suggested improvement

I think the least disruptive fix is documentation plus install output:

• In the local-prefix docs, explicitly call out that install-cli.sh defaults to Node 22.22.0.
• Explain why that differs from install.sh defaulting to Node 24.
• Add a warning that native tools used by OpenClaw should be installed/rebuilt with the managed local-prefix Node, not necessarily the user’s shell Node.
• Consider changing install-cli.sh to default to Node 24 in a future release if that is now the recommended operational runtime.

Not asking for

I am not asking OpenClaw to drop Node 22 support. The issue is that the official install paths communicate two different defaults without making the distinction obvious to users.