From 31438a086f3226f51e357a48a29c3a25f65de9b6 Mon Sep 17 00:00:00 2001 From: PerfectPan <24316656+PerfectPan@users.noreply.github.com> Date: Sat, 31 Oct 2026 12:38:02 +0800 Subject: [PATCH 1/2] fix: align channels and Node checks with OpenClaw - Resolve beta and extended-stable channels to concrete versions before install. - Keep stable on the stable tag, falling back to latest when absent. - Report unsupported or stale Node.js runtimes in install and doctor. - Sort unpadded calendar versions numerically for list and list-remote. - Move the Docker e2e image to Node 26. --- CHANGELOG.md | 5 + README.md | 23 +++- site/src/content.ts | 5 +- site/src/routes/index.tsx | 6 +- src/cli.rs | 13 ++- src/source.rs | 43 +++++-- src/version.rs | 228 ++++++++++++++++++++++++++++++++++++-- tests/core.rs | 70 ++++++++++++ tests/e2e/Dockerfile | 2 +- 9 files changed, 361 insertions(+), 34 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 08f8838..41f5f6a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,11 @@ ## Unreleased +- Added `beta` and `extended-stable` channel resolution, including support for the npm `extended-stable` dist-tag. +- Resolved channel names to concrete versions before install so `.openclaw-version` and `ocvm list` stay reproducible. +- Added Node.js runtime checks to install and `doctor` for OpenClaw's current Node 24/26 requirements. +- Fixed local and remote version ordering for OpenClaw's unpadded calendar versions. +- Updated the Docker e2e image to Node 26 and refreshed channel documentation. - Replaced GitHub raw installer guidance with a static installer path that can be mirrored to OSS/CDN. - Added website documentation routes for installation, commands, configuration, and release sources. - Added GitHub and documentation navigation to the landing page. diff --git a/README.md b/README.md index badb3a0..b7bf17f 100644 --- a/README.md +++ b/README.md @@ -6,12 +6,19 @@ This is a version manager, not an OpenClaw installer replacement. Installation i Website: https://ocvm.vercel.app +## Requirements + +OpenClaw currently requires Node.js 24.16+ on the 24.x line or 26.1+ on the +26.x line (24.22.1+ / 26.12.1+ recommended). Node 22, 23, and 25 are +unsupported. `ocvm` does not install or switch Node.js; `ocvm doctor` reports +unsupported runtimes before they turn into confusing install failures. + ## Status MVP crate scaffold with the full command surface from the PRD: ```bash -ocvm install +ocvm install ocvm uninstall ocvm use ocvm default @@ -19,7 +26,8 @@ ocvm current ocvm list ocvm list-remote ocvm list-remote --channel stable -ocvm list-remote --channel nightly +ocvm list-remote --channel beta +ocvm list-remote --channel extended-stable ocvm pin ocvm unpin ocvm init @@ -130,7 +138,11 @@ Manifest format: The release provider also accepts a raw array of version objects. Tarball fields can be named `url`, `tarball`, or `npm`. -The npm provider maps `stable` to the `latest` dist-tag when npm does not define a separate `stable` dist-tag. Project config can override this with `channels.stable`. +The npm provider resolves `latest`, `stable` (npm's `latest` tag), `beta`, and +`extended-stable` to a concrete version before installing. `beta` falls back to +`latest` when npm has no beta tag; `extended-stable` never falls back. Project +config can override any channel with `channels.`. Release manifests opt +into the same behavior through their `tags` arrays. Release manifest entries can include `sha256` or `executableSha256`. When present, `ocvm` verifies the staged `openclaw` executable before activation. @@ -196,6 +208,11 @@ ocvm rollback before-upgrade Rollback does not delete unrelated installed versions. +`snapshot` and `rollback` only restore ocvm's default and session selection. +They do not back up OpenClaw's configuration or SQLite state. OpenClaw refuses +to open state written by a newer schema, so use OpenClaw's own backup tooling +(see `openclaw backup --help`) before switching to an older release. + ## Install After a GitHub Release exists, publish `install.sh` to a stable HTTPS path. The diff --git a/site/src/content.ts b/site/src/content.ts index 964b0ad..f48422e 100644 --- a/site/src/content.ts +++ b/site/src/content.ts @@ -23,12 +23,13 @@ export const commandGroups = [ { title: 'Install and remove', commands: [ - 'ocvm install ', + 'ocvm install ', 'ocvm uninstall ', 'ocvm list', 'ocvm list-remote', 'ocvm list-remote --channel stable', - 'ocvm list-remote --channel nightly', + 'ocvm list-remote --channel beta', + 'ocvm list-remote --channel extended-stable', ], }, { diff --git a/site/src/routes/index.tsx b/site/src/routes/index.tsx index 7d7ce76..b0557b5 100644 --- a/site/src/routes/index.tsx +++ b/site/src/routes/index.tsx @@ -19,8 +19,8 @@ const features = [ body: 'Commit .openclaw-version and every shell in the repo resolves the same OpenClaw version before falling back to user defaults.', }, { - title: 'Stable and exact installs', - body: 'Install stable, latest, nightly, or an exact version from npm today, with release manifests ready for GitHub Release assets.', + title: 'Release channels and exact installs', + body: 'Install stable, extended-stable, beta, latest, or an exact version from npm, with release manifests ready for GitHub Release assets.', }, { title: 'Snapshot and rollback', @@ -28,7 +28,7 @@ const features = [ }, { title: 'Doctor checks', - body: 'Inspect PATH, shims, defaults, project pins, and installed executables when a local OpenClaw environment behaves strangely.', + body: 'Inspect Node.js, PATH, shims, defaults, project pins, and installed executables when a local OpenClaw environment behaves strangely.', }, { title: 'Release verification', diff --git a/src/cli.rs b/src/cli.rs index d921df4..ae3beeb 100644 --- a/src/cli.rs +++ b/src/cli.rs @@ -1,7 +1,7 @@ use crate::config; use crate::paths::OcvmPaths; use crate::project; -use crate::source::provider_from_config; +use crate::source::{is_channel_name, provider_from_config}; use crate::version; use anyhow::{anyhow, Result}; use clap::{Parser, Subcommand, ValueEnum}; @@ -120,7 +120,9 @@ where } Commands::ListRemote { channel } => { let source = provider_from_config(&paths)?; - for remote in source.list_remote(channel.as_deref())? { + let mut remotes = source.list_remote(channel.as_deref())?; + remotes.sort_by(|left, right| version::compare_versions(&left.version, &right.version)); + for remote in remotes { if remote.tags.is_empty() { println!("{}", remote.version); } else { @@ -201,14 +203,13 @@ end } fn resolve_for_local_command(paths: &OcvmPaths, requested: &str) -> Result { - if requested != "latest" && requested != "stable" { - return Ok(requested.to_string()); - } - let config = config::load(paths)?; if let Some(version) = config.channels.get(requested) { return Ok(version.clone()); } + if !is_channel_name(requested) { + return Ok(requested.to_string()); + } let source = provider_from_config(paths)?; source.resolve_alias(requested) diff --git a/src/source.rs b/src/source.rs index 9a67e64..be266c8 100644 --- a/src/source.rs +++ b/src/source.rs @@ -26,6 +26,12 @@ pub trait SourceProvider { } } +pub const CHANNEL_NAMES: [&str; 4] = ["latest", "stable", "beta", "extended-stable"]; + +pub fn is_channel_name(value: &str) -> bool { + CHANNEL_NAMES.contains(&value) +} + pub struct NpmSource { package: String, } @@ -55,15 +61,21 @@ impl NpmSource { impl SourceProvider for NpmSource { fn resolve_alias(&self, requested: &str) -> Result { - if requested != "latest" && requested != "stable" { + if !is_channel_name(requested) { return Ok(requested.to_string()); } let tags = self.npm_json(&["view", &self.package, "dist-tags", "--json"])?; - tags.get(requested) - .or_else(|| tags.get("latest")) + let resolved = match requested { + "stable" => tags.get("stable").or_else(|| tags.get("latest")), + "beta" => tags.get("beta").or_else(|| tags.get("latest")), + "latest" => tags.get("latest"), + "extended-stable" => tags.get("extended-stable"), + _ => None, + }; + resolved .and_then(|value| value.as_str()) .map(ToOwned::to_owned) - .ok_or_else(|| anyhow!("npm dist-tags did not include {requested} or latest")) + .ok_or_else(|| anyhow!("npm dist-tags did not include {requested}")) } fn list_remote(&self, channel: Option<&str>) -> Result> { @@ -79,7 +91,7 @@ impl SourceProvider for NpmSource { .as_str() .ok_or_else(|| anyhow!("npm versions response included a non-string version"))?; let mut labels = Vec::new(); - for tag in ["stable", "latest", "beta"] { + for tag in ["stable", "latest", "beta", "extended-stable"] { if tags.get(tag).and_then(|value| value.as_str()) == Some(version) { labels.push(tag.to_string()); } @@ -166,14 +178,25 @@ impl ReleaseSource { impl SourceProvider for ReleaseSource { fn resolve_alias(&self, requested: &str) -> Result { - if requested != "latest" && requested != "stable" { + if !is_channel_name(requested) { return Ok(requested.to_string()); } - self.versions()? - .into_iter() + let versions = self.versions()?; + if let Some(version) = versions + .iter() .find(|version| version.tags.iter().any(|tag| tag == requested)) - .map(|version| version.version) - .ok_or_else(|| anyhow!("release manifest did not include {requested}")) + { + return Ok(version.version.clone()); + } + if requested == "stable" || requested == "beta" { + if let Some(version) = versions + .iter() + .find(|version| version.tags.iter().any(|tag| tag == "latest")) + { + return Ok(version.version.clone()); + } + } + Err(anyhow!("release manifest did not include {requested}")) } fn list_remote(&self, channel: Option<&str>) -> Result> { diff --git a/src/version.rs b/src/version.rs index cea9524..0f52bee 100644 --- a/src/version.rs +++ b/src/version.rs @@ -4,6 +4,7 @@ use crate::project; use crate::source::SourceProvider; use anyhow::{anyhow, Context, Result}; use serde::{Deserialize, Serialize}; +use std::cmp::Ordering; use std::ffi::OsStr; use std::path::Path; use std::process::{Command, Output, Stdio}; @@ -47,14 +48,14 @@ pub fn resolve_requested( source: &dyn SourceProvider, requested: &str, ) -> Result { - if requested == "latest" || requested == "stable" { - let config = config::load(paths)?; - if let Some(version) = config.channels.get(requested) { - return Ok(version.clone()); - } - return source.resolve_alias(requested); + let config = config::load(paths)?; + if let Some(version) = config.channels.get(requested) { + return Ok(version.clone()); } - Ok(requested.to_string()) + if !crate::source::is_channel_name(requested) { + return Ok(requested.to_string()); + } + source.resolve_alias(requested) } pub fn resolve_active(paths: &OcvmPaths, cwd: &Path) -> Result> { @@ -109,10 +110,62 @@ pub fn list_installed(paths: &OcvmPaths) -> Result> { versions.push(entry.file_name().to_string_lossy().into_owned()); } } - versions.sort(); + versions.sort_by(|left, right| compare_versions(left, right)); Ok(versions) } +/// Compare OpenClaw calendar versions such as `2026.10.9` and +/// `2026.10.10-beta.5`. +/// +/// OpenClaw does not zero-pad version segments, so plain string ordering puts +/// `2026.10.9` before `2026.9.36`. Compare numeric segments numerically and +/// treat a prerelease as lower than its matching final release. +pub fn compare_versions(left: &str, right: &str) -> Ordering { + let (left_core, left_prerelease) = split_version(left); + let (right_core, right_prerelease) = split_version(right); + let core = compare_segments(left_core, right_core); + if core != Ordering::Equal { + return core; + } + match (left_prerelease, right_prerelease) { + (None, None) => Ordering::Equal, + (None, Some(_)) => Ordering::Greater, + (Some(_), None) => Ordering::Less, + (Some(left), Some(right)) => compare_segments(left, right), + } +} + +fn split_version(version: &str) -> (&str, Option<&str>) { + let version = version.split('+').next().unwrap_or(version); + match version.split_once('-') { + Some((core, prerelease)) => (core, Some(prerelease)), + None => (version, None), + } +} + +fn compare_segments(left: &str, right: &str) -> Ordering { + let left: Vec<&str> = left.split('.').collect(); + let right: Vec<&str> = right.split('.').collect(); + for index in 0..left.len().max(right.len()) { + let left = left.get(index).copied().unwrap_or("0"); + let right = right.get(index).copied().unwrap_or("0"); + let ordering = compare_segment(left, right); + if ordering != Ordering::Equal { + return ordering; + } + } + Ordering::Equal +} + +fn compare_segment(left: &str, right: &str) -> Ordering { + match (left.parse::(), right.parse::()) { + (Ok(left), Ok(right)) => left.cmp(&right), + (Ok(_), Err(_)) => Ordering::Less, + (Err(_), Ok(_)) => Ordering::Greater, + (Err(_), Err(_)) => left.cmp(right), + } +} + pub fn write_shim(paths: &OcvmPaths) -> Result<()> { paths.ensure()?; let shim = paths.shims.join(if cfg!(windows) { @@ -136,8 +189,77 @@ pub fn write_shim(paths: &OcvmPaths) -> Result<()> { Ok(()) } +const NODE_MINIMUM: &str = "Node.js 24.16+ (24.x) or 26.1+ (26.x)"; +const NODE_RECOMMENDED: &str = "24.22.1+ or 26.12.1+"; +const NODE_REQUIREMENTS_URL: &str = "https://docs.openclaw.ai/install/node"; + +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +struct NodeVersion { + major: u64, + minor: u64, + patch: u64, +} + +impl NodeVersion { + fn parse(raw: &str) -> Option { + let raw = raw.trim(); + let raw = raw.strip_prefix('v').unwrap_or(raw); + let core = raw.split(['-', '+']).next()?; + let mut segments = core.split('.'); + Some(Self { + major: segments.next()?.parse().ok()?, + minor: segments.next().unwrap_or("0").parse().ok()?, + patch: segments.next().unwrap_or("0").parse().ok()?, + }) + } + + fn is_supported(self) -> bool { + (self.major == 24 && self.minor >= 16) + || (self.major == 26 && self.minor >= 1) + || self.major >= 27 + } + + fn is_recommended(self) -> bool { + (self.major == 24 && (self.minor > 22 || (self.minor == 22 && self.patch >= 1))) + || (self.major == 26 && (self.minor > 12 || (self.minor == 12 && self.patch >= 1))) + || self.major >= 27 + } +} + +impl std::fmt::Display for NodeVersion { + fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + write!(formatter, "v{}.{}.{}", self.major, self.minor, self.patch) + } +} + +fn detect_node_version() -> Option { + let output = Command::new("node").arg("--version").output().ok()?; + if !output.status.success() { + return None; + } + NodeVersion::parse(&String::from_utf8_lossy(&output.stdout)) +} + +fn node_warning() -> Option { + match detect_node_version() { + None => Some(format!( + "warning: Node.js was not found; OpenClaw requires {NODE_MINIMUM}.\n See {NODE_REQUIREMENTS_URL}" + )), + Some(version) if !version.is_supported() => Some(format!( + "warning: Node.js {version} is not supported by OpenClaw; install {NODE_MINIMUM}. Node 22, 23, and 25 are unsupported.\n See {NODE_REQUIREMENTS_URL}" + )), + Some(version) if !version.is_recommended() => Some(format!( + "warning: Node.js {version} is below OpenClaw's recommended security patch level; upgrade to {NODE_RECOMMENDED}." + )), + Some(_) => None, + } +} + pub fn install(paths: &OcvmPaths, source: &dyn SourceProvider, requested: &str) -> Result { paths.ensure()?; + if let Some(warning) = node_warning() { + eprintln!("{warning}"); + } let version = resolve_requested(paths, source, requested)?; let staging = paths .home @@ -355,6 +477,25 @@ pub fn doctor( let mut ok = true; let mut findings = Vec::new(); + match detect_node_version() { + None => { + ok = false; + findings.push(format!( + "fix: Node.js was not found; OpenClaw requires {NODE_MINIMUM}\n See {NODE_REQUIREMENTS_URL}" + )); + } + Some(version) if !version.is_supported() => { + ok = false; + findings.push(format!( + "fix: Node.js {version} is not supported by OpenClaw; install {NODE_MINIMUM}. Node 22, 23, and 25 are unsupported.\n See {NODE_REQUIREMENTS_URL}" + )); + } + Some(version) if !version.is_recommended() => findings.push(format!( + "warn: Node.js {version} is below OpenClaw's recommended security patch level; upgrade to {NODE_RECOMMENDED}." + )), + Some(_) => {} + } + let path = std::env::var("PATH").unwrap_or_default(); if !path_contains_dir(&path, &paths.shims) { ok = false; @@ -408,7 +549,8 @@ pub fn doctor( #[cfg(test)] mod tests { - use super::is_text_file_busy; + use super::{compare_versions, is_text_file_busy, NodeVersion}; + use std::cmp::Ordering; #[test] #[cfg(unix)] @@ -425,4 +567,72 @@ mod tests { assert!(!is_text_file_busy(&error)); } + + #[test] + fn calendar_versions_sort_numerically() { + let mut versions = vec!["2026.10.9", "2026.9.36", "2026.10.10", "2026.3.28"]; + + versions.sort_by(|left, right| compare_versions(left, right)); + + assert_eq!( + versions, + ["2026.3.28", "2026.9.36", "2026.10.9", "2026.10.10"] + ); + } + + #[test] + fn prereleases_sort_before_their_final_release() { + assert_eq!( + compare_versions("2026.10.10-beta.5", "2026.10.10"), + Ordering::Less + ); + assert_eq!( + compare_versions("2026.10.10-beta.5", "2026.10.10-beta.4"), + Ordering::Greater + ); + assert_eq!( + compare_versions("2026.10.10-beta.10", "2026.10.10-beta.9"), + Ordering::Greater + ); + } + + #[test] + fn node_version_parsing_accepts_prefixes_and_prereleases() { + assert_eq!( + NodeVersion::parse("v26.13.0\n"), + Some(NodeVersion { + major: 26, + minor: 13, + patch: 0 + }) + ); + assert_eq!( + NodeVersion::parse("27.0.0-nightly20261018f88a1d25e9"), + Some(NodeVersion { + major: 27, + minor: 0, + patch: 0 + }) + ); + assert_eq!(NodeVersion::parse("not-a-version"), None); + } + + #[test] + fn node_support_matrix_matches_openclaw_requirements() { + let supported = |raw: &str| NodeVersion::parse(raw).unwrap().is_supported(); + let recommended = |raw: &str| NodeVersion::parse(raw).unwrap().is_recommended(); + + assert!(!supported("22.14.0")); + assert!(!supported("23.10.0")); + assert!(!supported("25.0.0")); + assert!(supported("24.16.0")); + assert!(supported("26.1.0")); + assert!(supported("27.0.0")); + + assert!(!recommended("24.16.0")); + assert!(!recommended("24.22.0")); + assert!(recommended("24.22.1")); + assert!(!recommended("26.12.0")); + assert!(recommended("26.12.1")); + } } diff --git a/tests/core.rs b/tests/core.rs index 62ca484..10c91c4 100644 --- a/tests/core.rs +++ b/tests/core.rs @@ -238,6 +238,76 @@ fn stable_alias_can_fallback_to_latest_when_source_has_no_stable() { assert_eq!(resolved, "2026.4.01"); } +#[test] +fn beta_and_extended_stable_aliases_resolve_to_concrete_versions() { + let tmp = TempDir::new().unwrap(); + let paths = paths(&tmp); + let source = FakeSource { + versions: vec![ + RemoteVersion { + version: "2026.10.9".to_string(), + tags: vec!["latest".to_string(), "stable".to_string()], + url: None, + executable_sha256: None, + }, + RemoteVersion { + version: "2026.10.10-beta.5".to_string(), + tags: vec!["beta".to_string(), "prerelease".to_string()], + url: None, + executable_sha256: None, + }, + RemoteVersion { + version: "2026.9.36".to_string(), + tags: vec!["extended-stable".to_string()], + url: None, + executable_sha256: None, + }, + ], + fail_install: false, + fail_verify: false, + installed_specs: RefCell::new(Vec::new()), + }; + + assert_eq!( + version::resolve_requested(&paths, &source, "beta").unwrap(), + "2026.10.10-beta.5" + ); + assert_eq!( + version::resolve_requested(&paths, &source, "extended-stable").unwrap(), + "2026.9.36" + ); + assert_eq!( + version::resolve_requested(&paths, &source, "2026.9.36").unwrap(), + "2026.9.36" + ); +} + +#[test] +fn install_resolves_channel_to_concrete_version_directory() { + let tmp = TempDir::new().unwrap(); + let paths = paths(&tmp); + let source = FakeSource { + versions: vec![RemoteVersion { + version: "2026.10.10-beta.5".to_string(), + tags: vec!["beta".to_string()], + url: None, + executable_sha256: None, + }], + fail_install: false, + fail_verify: false, + installed_specs: RefCell::new(Vec::new()), + }; + + let installed = version::install(&paths, &source, "beta").unwrap(); + + assert_eq!(installed, "2026.10.10-beta.5"); + assert!(paths.openclaw_bin("2026.10.10-beta.5").exists()); + assert_eq!( + source.installed_specs.borrow().as_slice(), + ["2026.10.10-beta.5"] + ); +} + #[test] fn release_manifest_versions_parse_sha256_alias() { let parsed: serde_json::Value = serde_json::from_str( diff --git a/tests/e2e/Dockerfile b/tests/e2e/Dockerfile index e828c74..e2c6dfe 100644 --- a/tests/e2e/Dockerfile +++ b/tests/e2e/Dockerfile @@ -2,7 +2,7 @@ FROM rust:1-bookworm RUN apt-get update \ && apt-get install -y --no-install-recommends ca-certificates curl gnupg \ - && curl -fsSL https://deb.nodesource.com/setup_22.x | bash - \ + && curl -fsSL https://deb.nodesource.com/setup_26.x | bash - \ && apt-get install -y --no-install-recommends nodejs \ && rm -rf /var/lib/apt/lists/* From dfbdf76da8e1d60752d8c955edae5841bb5bc3a5 Mon Sep 17 00:00:00 2001 From: PerfectPan <24316656+PerfectPan@users.noreply.github.com> Date: Sat, 31 Oct 2026 12:48:11 +0800 Subject: [PATCH 2/2] fix: reject Node 24/26 prerelease runtimes - Treat Node 24/26 prereleases as unsupported while accepting Node 27+ dev labels. - Mention beta and extended-stable in the install help text. - Document Node 27 and the prerelease rule in README and site install docs. --- CHANGELOG.md | 4 +-- README.md | 9 ++++--- site/src/routes/docs.installation.tsx | 7 ++++++ src/cli.rs | 2 +- src/version.rs | 35 ++++++++++++++++++++++++--- 5 files changed, 46 insertions(+), 11 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 41f5f6a..da65fd0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,8 +3,8 @@ ## Unreleased - Added `beta` and `extended-stable` channel resolution, including support for the npm `extended-stable` dist-tag. -- Resolved channel names to concrete versions before install so `.openclaw-version` and `ocvm list` stay reproducible. -- Added Node.js runtime checks to install and `doctor` for OpenClaw's current Node 24/26 requirements. +- Resolved channel names to concrete versions before install so defaults, pins, and `ocvm list` stay reproducible. +- Added Node.js runtime checks to install and `doctor` for OpenClaw's current Node 24/26/27 requirements, including prerelease rejection for Node 24/26. - Fixed local and remote version ordering for OpenClaw's unpadded calendar versions. - Updated the Docker e2e image to Node 26 and refreshed channel documentation. - Replaced GitHub raw installer guidance with a static installer path that can be mirrored to OSS/CDN. diff --git a/README.md b/README.md index b7bf17f..1578aaa 100644 --- a/README.md +++ b/README.md @@ -8,10 +8,11 @@ Website: https://ocvm.vercel.app ## Requirements -OpenClaw currently requires Node.js 24.16+ on the 24.x line or 26.1+ on the -26.x line (24.22.1+ / 26.12.1+ recommended). Node 22, 23, and 25 are -unsupported. `ocvm` does not install or switch Node.js; `ocvm doctor` reports -unsupported runtimes before they turn into confusing install failures. +OpenClaw currently requires Node.js 24.16+ on the 24.x line, 26.1+ on the +26.x line, or 27+ (24.22.1+ / 26.12.1+ recommended). Node 24/26 prereleases +and Node 22, 23, and 25 are unsupported. `ocvm` does not install or switch +Node.js; `ocvm doctor` reports unsupported runtimes before they turn into +confusing install failures. ## Status diff --git a/site/src/routes/docs.installation.tsx b/site/src/routes/docs.installation.tsx index ab6a376..68f3079 100644 --- a/site/src/routes/docs.installation.tsx +++ b/site/src/routes/docs.installation.tsx @@ -23,6 +23,13 @@ function InstallationDocs() {
           {installCommand}
         
+

Node.js requirement

+

+ ocvm installs OpenClaw but does not install Node.js. OpenClaw currently + requires Node.js 24.16+ on 24.x, 26.1+ on 26.x, or 27+ (24.22.1+ / + 26.12.1+ recommended). Run ocvm doctor to check the + active runtime. +

Release layout

Publish one stable installer script:

diff --git a/src/cli.rs b/src/cli.rs
index ae3beeb..7dfbc60 100644
--- a/src/cli.rs
+++ b/src/cli.rs
@@ -16,7 +16,7 @@ pub struct Cli {
 
 #[derive(Debug, Subcommand)]
 enum Commands {
-    /// Install an OpenClaw version, latest, or stable.
+    /// Install an OpenClaw version or a release channel (latest, stable, beta, extended-stable).
     Install { version: String },
     /// Uninstall an installed OpenClaw version.
     Uninstall { version: String },
diff --git a/src/version.rs b/src/version.rs
index 0f52bee..37c4e6e 100644
--- a/src/version.rs
+++ b/src/version.rs
@@ -198,28 +198,40 @@ struct NodeVersion {
     major: u64,
     minor: u64,
     patch: u64,
+    prerelease: bool,
 }
 
 impl NodeVersion {
     fn parse(raw: &str) -> Option {
         let raw = raw.trim();
         let raw = raw.strip_prefix('v').unwrap_or(raw);
-        let core = raw.split(['-', '+']).next()?;
+        let (raw, _build) = raw.split_once('+').unwrap_or((raw, ""));
+        let (core, prerelease) = match raw.split_once('-') {
+            Some((core, suffix)) => (core, !suffix.is_empty()),
+            None => (raw, false),
+        };
         let mut segments = core.split('.');
         Some(Self {
             major: segments.next()?.parse().ok()?,
             minor: segments.next().unwrap_or("0").parse().ok()?,
             patch: segments.next().unwrap_or("0").parse().ok()?,
+            prerelease,
         })
     }
 
     fn is_supported(self) -> bool {
+        if self.prerelease && self.major <= 26 {
+            return false;
+        }
         (self.major == 24 && self.minor >= 16)
             || (self.major == 26 && self.minor >= 1)
             || self.major >= 27
     }
 
     fn is_recommended(self) -> bool {
+        if self.prerelease && self.major <= 26 {
+            return false;
+        }
         (self.major == 24 && (self.minor > 22 || (self.minor == 22 && self.patch >= 1)))
             || (self.major == 26 && (self.minor > 12 || (self.minor == 12 && self.patch >= 1)))
             || self.major >= 27
@@ -228,7 +240,15 @@ impl NodeVersion {
 
 impl std::fmt::Display for NodeVersion {
     fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
-        write!(formatter, "v{}.{}.{}", self.major, self.minor, self.patch)
+        if self.prerelease {
+            write!(
+                formatter,
+                "v{}.{}.{} (prerelease)",
+                self.major, self.minor, self.patch
+            )
+        } else {
+            write!(formatter, "v{}.{}.{}", self.major, self.minor, self.patch)
+        }
     }
 }
 
@@ -603,7 +623,8 @@ mod tests {
             Some(NodeVersion {
                 major: 26,
                 minor: 13,
-                patch: 0
+                patch: 0,
+                prerelease: false
             })
         );
         assert_eq!(
@@ -611,7 +632,8 @@ mod tests {
             Some(NodeVersion {
                 major: 27,
                 minor: 0,
-                patch: 0
+                patch: 0,
+                prerelease: true
             })
         );
         assert_eq!(NodeVersion::parse("not-a-version"), None);
@@ -627,6 +649,10 @@ mod tests {
         assert!(!supported("25.0.0"));
         assert!(supported("24.16.0"));
         assert!(supported("26.1.0"));
+        assert!(!supported("24.16.0-rc.1"));
+        assert!(!supported("24.22.1-rc.1"));
+        assert!(!supported("26.12.1-rc.1"));
+        assert!(supported("27.0.0-head"));
         assert!(supported("27.0.0"));
 
         assert!(!recommended("24.16.0"));
@@ -634,5 +660,6 @@ mod tests {
         assert!(recommended("24.22.1"));
         assert!(!recommended("26.12.0"));
         assert!(recommended("26.12.1"));
+        assert!(!recommended("26.12.1-rc.1"));
     }
 }