From c441db7e13cd822b32b4447bceb3e24d0c33cb68 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Sat, 4 Apr 2026 11:14:51 +0100
Subject: [PATCH] docs: refresh update channel references

---
 docs/cli/update.md                   |  7 +++++--
 docs/install/development-channels.md | 14 +++++++++++---
 docs/install/updating.md             |  4 ++++
 3 files changed, 20 insertions(+), 5 deletions(-)

diff --git a/docs/cli/update.md b/docs/cli/update.md
index dc19fbafbfa..9ddc7ce1ed0 100644
--- a/docs/cli/update.md
+++ b/docs/cli/update.md
@@ -73,7 +73,9 @@ install method aligned:
 
 - `dev` → ensures a git checkout (default: `~/openclaw`, override with `OPENCLAW_GIT_DIR`),
   updates it, and installs the global CLI from that checkout.
-- `stable`/`beta` → installs from npm using the matching dist-tag.
+- `stable` → installs from npm using `latest`.
+- `beta` → prefers npm dist-tag `beta`, but falls back to `latest` when beta is
+  missing or older than the current stable release.
 
 The Gateway core auto-updater (when enabled via config) reuses this same update path.
 
@@ -82,7 +84,8 @@ The Gateway core auto-updater (when enabled via config) reuses this same update
 Channels:
 
 - `stable`: checkout the latest non-beta tag, then build + doctor.
-- `beta`: checkout the latest `-beta` tag, then build + doctor.
+- `beta`: prefer the latest `-beta` tag, but fall back to the latest stable tag
+  when beta is missing or older.
 - `dev`: checkout `main`, then fetch + rebase.
 
 High-level:
diff --git a/docs/install/development-channels.md b/docs/install/development-channels.md
index 37491eb6da1..b8d42c0e49e 100644
--- a/docs/install/development-channels.md
+++ b/docs/install/development-channels.md
@@ -13,7 +13,8 @@ sidebarTitle: "Release Channels"
 OpenClaw ships three update channels:
 
 - **stable**: npm dist-tag `latest`. Recommended for most users.
-- **beta**: npm dist-tag `beta` (builds under test).
+- **beta**: npm dist-tag `beta` when it is current; if beta is missing or older than
+  the latest stable release, the update flow falls back to `latest`.
 - **dev**: moving head of `main` (git). npm dist-tag: `dev` (when published).
   The `main` branch is for experimentation and active development. It may contain
   incomplete features or breaking changes. Do not use it for production gateways.
@@ -35,8 +36,12 @@ openclaw update --channel dev
 `--channel` persists your choice in config (`update.channel`) and aligns the
 install method:
 
-- **`stable`/`beta`** (package installs): updates via the matching npm dist-tag.
-- **`stable`/`beta`** (git installs): checks out the latest matching git tag.
+- **`stable`** (package installs): updates via npm dist-tag `latest`.
+- **`beta`** (package installs): prefers npm dist-tag `beta`, but falls back to
+  `latest` when `beta` is missing or older than the current stable tag.
+- **`stable`** (git installs): checks out the latest stable git tag.
+- **`beta`** (git installs): prefers the latest beta git tag, but falls back to
+  the latest stable git tag when beta is missing or older.
 - **`dev`**: ensures a git checkout (default `~/openclaw`, override with
   `OPENCLAW_GIT_DIR`), switches to `main`, rebases on upstream, builds, and
   installs the global CLI from that checkout.
@@ -70,6 +75,9 @@ Notes:
   channel as usual.
 - Downgrade protection: if the target version is older than your current version,
   OpenClaw prompts for confirmation (skip with `--yes`).
+- `--channel beta` is different from `--tag beta`: the channel flow can fall back
+  to stable/latest when beta is missing or older, while `--tag beta` targets the
+  raw `beta` dist-tag for that one run.
 
 ## Dry run
 
diff --git a/docs/install/updating.md b/docs/install/updating.md
index 6e6b6956daa..7806dc80991 100644
--- a/docs/install/updating.md
+++ b/docs/install/updating.md
@@ -26,6 +26,10 @@ openclaw update --tag main
 openclaw update --dry-run   # preview without applying
 ```
 
+`--channel beta` prefers beta, but the runtime falls back to stable/latest when
+the beta tag is missing or older than the latest stable release. Use `--tag beta`
+if you want the raw npm beta dist-tag for a one-off package update.
+
 See [Development channels](/install/development-channels) for channel semantics.
 
 ## Alternative: re-run the installer