feat(update): add core auto-updater and dry-run preview

docs/cli/update.md

@@ -21,6 +21,7 @@ openclaw update wizard
 openclaw update --channel beta
 openclaw update --channel dev
 openclaw update --tag beta
+openclaw update --dry-run
 openclaw update --no-restart
 openclaw update --json
 openclaw --update
@@ -31,6 +32,7 @@ openclaw --update
 - `--no-restart`: skip restarting the Gateway service after a successful update.
 - `--channel <stable|beta|dev>`: set the update channel (git + npm; persisted in config).
 - `--tag <dist-tag|version>`: override the npm dist-tag or version for this update only.
+- `--dry-run`: preview planned update actions (channel/tag/target/restart flow) without writing config, installing, syncing plugins, or restarting.
 - `--json`: print machine-readable `UpdateRunResult` JSON.
 - `--timeout <seconds>`: per-step timeout (default is 1200s).
 
@@ -66,6 +68,8 @@ install method aligned:
   updates it, and installs the global CLI from that checkout.
 - `stable`/`beta` → installs from npm using the matching dist-tag.
 
+The Gateway core auto-updater (when enabled via config) reuses this same update path.
+
 ## Git checkout flow
 
 Channels:

docs/install/updating.md

@@ -71,6 +71,32 @@ See [Development channels](/install/development-channels) for channel semantics
 
 Note: on npm installs, the gateway logs an update hint on startup (checks the current channel tag). Disable via `update.checkOnStart: false`.
 
+### Core auto-updater (optional)
+
+Auto-updater is **off by default** and is a core Gateway feature (not a plugin).
+
+```json
+{
+  "update": {
+    "channel": "stable",
+    "auto": {
+      "enabled": true,
+      "stableDelayHours": 6,
+      "stableJitterHours": 12,
+      "betaCheckIntervalHours": 1
+    }
+  }
+}
+```
+
+Behavior:
+
+- `stable`: when a new version is seen, OpenClaw waits `stableDelayHours` and then applies a deterministic per-install jitter in `stableJitterHours` (spread rollout).
+- `beta`: checks on `betaCheckIntervalHours` cadence (default: hourly) and applies when an update is available.
+- `dev`: no automatic apply; use manual `openclaw update`.
+
+Use `openclaw update --dry-run` to preview update actions before enabling automation.
+
 Then:
 
 ```bash