From 96a38d5aa46eb045e836cbec4cc98e8586ea9576 Mon Sep 17 00:00:00 2001
From: Jason Hargrove <285708+jasonhargrove@users.noreply.github.com>
Date: Mon, 2 Mar 2026 17:16:31 -0700
Subject: [PATCH] fix(cli): fail fast on unsupported Node versions in install
 and runtime paths

Surface a clear Node 22.12+ requirement before npm/install bootstrap work so users avoid misleading downstream errors.

- Add installer shell preflight to block active Node <22 and suggest NVM recovery commands
- Add openclaw.mjs runtime preflight for npm/npx usage with explicit Node version guidance
- Keep messaging actionable for both NVM and non-NVM environments
---
 openclaw.mjs       | 23 +++++++++++++++++++++++
 scripts/install.sh | 40 ++++++++++++++++++++++++++++++++++++++++
 2 files changed, 63 insertions(+)

diff --git a/openclaw.mjs b/openclaw.mjs
index 6649f4e81cb..570fd138f0c 100755
--- a/openclaw.mjs
+++ b/openclaw.mjs
@@ -2,6 +2,29 @@
 
 import module from "node:module";
 
+const MIN_NODE_MAJOR = 22;
+const MIN_NODE_MINOR = 12;
+
+const ensureSupportedNodeVersion = () => {
+  const [majorRaw = "0", minorRaw = "0"] = process.versions.node.split(".");
+  const major = Number(majorRaw);
+  const minor = Number(minorRaw);
+  const supported = major > MIN_NODE_MAJOR || (major === MIN_NODE_MAJOR && minor >= MIN_NODE_MINOR);
+  if (supported) {
+    return;
+  }
+
+  throw new Error(
+    `openclaw: Node.js v${MIN_NODE_MAJOR}.${MIN_NODE_MINOR}+ is required (current: v${process.versions.node}).\n` +
+      "If you use nvm, run:\n" +
+      "  nvm install 22\n" +
+      "  nvm use 22\n" +
+      "  nvm alias default 22",
+  );
+};
+
+ensureSupportedNodeVersion();
+
 // https://nodejs.org/api/module.html#module-compile-cache
 if (module.enableCompileCache && !process.env.NODE_DISABLE_COMPILE_CACHE) {
   try {
diff --git a/scripts/install.sh b/scripts/install.sh
index 1710ce1d6a4..0bd11ce90e6 100755
--- a/scripts/install.sh
+++ b/scripts/install.sh
@@ -1313,6 +1313,43 @@ ensure_macos_node22_active() {
     return 1
 }
 
+ensure_node22_active_shell() {
+    local major
+    major="$(node_major_version || true)"
+    if [[ -n "$major" && "$major" -ge 22 ]]; then
+        return 0
+    fi
+
+    local active_path active_version
+    active_path="$(command -v node 2>/dev/null || echo "not found")"
+    active_version="$(node -v 2>/dev/null || echo "missing")"
+
+    ui_error "Active Node.js must be v22+ but this shell is using ${active_version} (${active_path})"
+    print_active_node_paths || true
+
+    local nvm_detected=0
+    if [[ -n "${NVM_DIR:-}" || "$active_path" == *"/.nvm/"* ]]; then
+        nvm_detected=1
+    fi
+    if command -v nvm >/dev/null 2>&1; then
+        nvm_detected=1
+    fi
+
+    if [[ "$nvm_detected" -eq 1 ]]; then
+        echo "nvm appears to be managing Node for this shell."
+        echo "Run:"
+        echo "  nvm install 22"
+        echo "  nvm use 22"
+        echo "  nvm alias default 22"
+        echo "Then open a new shell and rerun:"
+        echo "  curl -fsSL https://openclaw.ai/install.sh | bash"
+    else
+        echo "Install/select Node.js 22+ and ensure it is first on PATH, then rerun installer."
+    fi
+
+    return 1
+}
+
 check_node() {
     if command -v node &> /dev/null; then
         NODE_VERSION="$(node_major_version || true)"
@@ -2157,6 +2194,9 @@ main() {
     if ! check_node; then
         install_node
     fi
+    if ! ensure_node22_active_shell; then
+        exit 1
+    fi
 
     ui_stage "Installing OpenClaw"