vilvona 1.0.0

package/docs/cli/tasks.md

@@ -0,0 +1,111 @@
+---
+summary: "CLI reference for `openclaw tasks` (background task ledger and Task Flow state)"
+read_when:
+  - You want to inspect, audit, or cancel background task records
+  - You are documenting Task Flow commands under `openclaw tasks flow`
+title: "`openclaw tasks`"
+---
+
+Inspect durable background tasks and Task Flow state. With no subcommand,
+`openclaw tasks` is equivalent to `openclaw tasks list`.
+
+See [Background Tasks](/automation/tasks) for the lifecycle and delivery model.
+
+## Usage
+
+```bash
+openclaw tasks
+openclaw tasks list
+openclaw tasks list --runtime acp
+openclaw tasks list --status running
+openclaw tasks show <lookup>
+openclaw tasks notify <lookup> state_changes
+openclaw tasks cancel <lookup>
+openclaw tasks audit
+openclaw tasks maintenance
+openclaw tasks maintenance --apply
+openclaw tasks flow list
+openclaw tasks flow show <lookup>
+openclaw tasks flow cancel <lookup>
+```
+
+## Root Options
+
+- `--json`: output JSON.
+- `--runtime <name>`: filter by kind: `subagent`, `acp`, `cron`, or `cli`.
+- `--status <name>`: filter by status: `queued`, `running`, `succeeded`, `failed`, `timed_out`, `cancelled`, or `lost`.
+
+## Subcommands
+
+### `list`
+
+```bash
+openclaw tasks list [--runtime <name>] [--status <name>] [--json]
+```
+
+Lists tracked background tasks newest first.
+
+### `show`
+
+```bash
+openclaw tasks show <lookup> [--json]
+```
+
+Shows one task by task ID, run ID, or session key.
+
+### `notify`
+
+```bash
+openclaw tasks notify <lookup> <done_only|state_changes|silent>
+```
+
+Changes the notification policy for a running task.
+
+### `cancel`
+
+```bash
+openclaw tasks cancel <lookup>
+```
+
+Cancels a running background task.
+
+### `audit`
+
+```bash
+openclaw tasks audit [--severity <warn|error>] [--code <name>] [--limit <n>] [--json]
+```
+
+Surfaces stale, lost, delivery-failed, or otherwise inconsistent task and Task Flow records. Lost tasks retained until `cleanupAfter` are warnings; expired or unstamped lost tasks are errors.
+
+### `maintenance`
+
+```bash
+openclaw tasks maintenance [--apply] [--json]
+```
+
+Previews or applies task and Task Flow reconciliation, cleanup stamping, pruning,
+and stale cron run session registry cleanup.
+For cron tasks, reconciliation uses persisted run logs/job state before marking an
+old active task `lost`, so completed cron runs do not become false audit errors
+just because the in-memory Gateway runtime state is gone. Offline CLI audit is
+not authoritative for the Gateway's process-local cron active-job set. CLI tasks
+with a run id/source id are marked `lost` when their live Gateway run context is
+gone, even if an old child-session row remains.
+When applied, maintenance also prunes `cron:<jobId>:run:<uuid>` session registry
+rows older than 7 days while preserving currently running cron jobs and leaving
+non-cron session rows untouched.
+
+### `flow`
+
+```bash
+openclaw tasks flow list [--status <name>] [--json]
+openclaw tasks flow show <lookup> [--json]
+openclaw tasks flow cancel <lookup>
+```
+
+Inspects or cancels durable Task Flow state under the task ledger.
+
+## Related
+
+- [CLI reference](/cli)
+- [Background tasks](/automation/tasks)

package/docs/cli/transcripts.md

@@ -0,0 +1,151 @@
+---
+summary: "CLI reference for `openclaw transcripts` (list, show, and locate stored transcripts)"
+read_when:
+  - You want to read stored transcript summaries from the terminal
+  - You need the path to a transcripts markdown summary
+  - You are debugging the core transcripts storage layout
+title: "Transcripts CLI"
+---
+
+# `openclaw transcripts`
+
+Inspect transcripts written by OpenClaw's core `transcripts` tool. This CLI is
+read-only; capture, import, and summarization are owned by the agent tool and
+configured auto-start sources.
+
+Use the CLI when you want to find yesterday's notes, open the Markdown file in
+an editor, feed a transcript to another tool, or debug where a session landed on
+disk. It does not start or stop capture.
+
+Artifacts live under the OpenClaw state directory:
+
+```text
+$OPENCLAW_STATE_DIR/transcripts/YYYY-MM-DD/<session>/
+  metadata.json
+  transcript.jsonl
+  summary.json
+  summary.md
+```
+
+The default state directory is `~/.openclaw`; set `OPENCLAW_STATE_DIR` to use a
+different one. The date directory comes from the session start time, and the
+session directory is a safe filesystem segment derived from the session id.
+
+## Commands
+
+```bash
+openclaw transcripts list
+openclaw transcripts show <session>
+openclaw transcripts show YYYY-MM-DD/<session>
+openclaw transcripts path <session>
+openclaw transcripts path YYYY-MM-DD/<session>
+openclaw transcripts path <session> --dir
+openclaw transcripts path <session> --metadata
+openclaw transcripts path <session> --transcript
+openclaw transcripts list --json
+openclaw transcripts show <session> --json
+openclaw transcripts path <session> --json
+```
+
+- `list`: list stored sessions, date-qualified selector, start time, title, and `summary.md` path.
+- `show <session>`: print the stored `summary.md`.
+- `path <session>`: print the `summary.md` path.
+- `path <session> --dir`: print the session directory.
+- `path <session> --metadata`: print `metadata.json`.
+- `path <session> --transcript`: print `transcript.jsonl`.
+- `--json`: print machine-readable output.
+
+When a human session id repeats across days, use the date-qualified selector
+from `list`, for example `openclaw transcripts show 2026-05-22/standup`.
+Default session ids include a timestamp and random suffix; configure fixed
+session ids only when they are unique within the day.
+
+## Output
+
+`list` prints one session per line:
+
+```text
+2026-05-22/standup  2026-05-22T09:00:00.000Z  Weekly standup  /Users/alex/.openclaw/transcripts/2026-05-22/standup/summary.md
+```
+
+The output is tab-separated. The columns are selector, start time, title, and
+summary path. The selector is the safest value to pass back to `show` or `path`.
+
+`list --json` prints objects with:
+
+- `sessionId`
+- `selector`
+- `date`
+- `title`
+- `startedAt`
+- `stoppedAt`
+- `source`
+- `path`
+- `summaryPath`
+- `hasSummary`
+
+`show --json` returns the stored session metadata, selector, session directory,
+summary path, and summary Markdown text. `path --json` returns the selected path
+and whether that file exists.
+
+## Many meetings per day
+
+Transcripts groups sessions by date, then by session id. Ten meetings on one
+day become ten sibling folders:
+
+```text
+~/.openclaw/transcripts/2026-05-22/
+  transcript-2026-05-22T09-00-00-000Z-a1b2c3d4/
+  transcript-2026-05-22T10-30-00-000Z-b2c3d4e5/
+  standup/
+```
+
+Use default generated ids for most automation. Use a fixed id such as `standup`
+only when the same id will not be used twice on the same date.
+
+## Missing summaries
+
+Live sessions write `summary.md` when the session stops. Imported transcripts
+write `summary.md` immediately after import. A session can still appear in
+`list` without a summary when capture is active, a provider failed during stop,
+or metadata was written before any utterances arrived.
+
+Use `path <session> --transcript` to inspect the append-only transcript, and use
+the `transcripts` tool action `summarize` to regenerate the Markdown summary.
+
+## Configuration
+
+Transcript capture is opt-in because live sources can join and record meeting
+audio. Enable the tool with top-level `transcripts.enabled`:
+
+```json
+{
+  "transcripts": {
+    "enabled": true,
+    "maxUtterances": 2000
+  }
+}
+```
+
+Configure auto-start sources with `transcripts.autoStart` in `openclaw.json`.
+Each entry is enabled by being present; omit an entry to disable that source.
+
+```json
+{
+  "transcripts": {
+    "enabled": true,
+    "autoStart": [
+      {
+        "providerId": "discord-voice",
+        "guildId": "1234567890",
+        "channelId": "2345678901"
+      },
+      {
+        "providerId": "slack-huddle",
+        "accountId": "workspace",
+        "channelId": "C123"
+      }
+    ]
+  }
+}
+```

package/docs/cli/tui.md

@@ -0,0 +1,92 @@
+---
+summary: "CLI reference for `openclaw tui` (Gateway-backed or local embedded terminal UI)"
+read_when:
+  - You want a terminal UI for the Gateway (remote-friendly)
+  - You want to pass url/token/session from scripts
+  - You want to run the TUI in local embedded mode without a Gateway
+  - You want to use openclaw chat or openclaw tui --local
+title: "TUI"
+---
+
+# `openclaw tui`
+
+Open the terminal UI connected to the Gateway, or run it in local embedded
+mode.
+
+Related:
+
+- TUI guide: [TUI](/web/tui)
+
+## Options
+
+| Flag                  | Default                                   | Description                                                                        |
+| --------------------- | ----------------------------------------- | ---------------------------------------------------------------------------------- |
+| `--local`             | `false`                                   | Run against the local embedded agent runtime instead of a Gateway.                 |
+| `--url <url>`         | `gateway.remote.url` from config          | Gateway WebSocket URL.                                                             |
+| `--token <token>`     | (none)                                    | Gateway token if required.                                                         |
+| `--password <pass>`   | (none)                                    | Gateway password if required.                                                      |
+| `--session <key>`     | `main` (or `global` when scope is global) | Session key. Inside an agent workspace it auto-selects that agent unless prefixed. |
+| `--deliver`           | `false`                                   | Deliver assistant replies through configured channels.                             |
+| `--thinking <level>`  | (model default)                           | Thinking level override.                                                           |
+| `--message <text>`    | (none)                                    | Send an initial message after connecting.                                          |
+| `--timeout-ms <ms>`   | `agents.defaults.timeoutSeconds`          | Agent timeout. Invalid values log a warning and are ignored.                       |
+| `--history-limit <n>` | `200`                                     | History entries to load on attach.                                                 |
+
+Aliases: `openclaw chat` and `openclaw terminal` invoke the same command with `--local` implied.
+
+Notes:
+
+- `chat` and `terminal` are aliases for `openclaw tui --local`.
+- `--local` cannot be combined with `--url`, `--token`, or `--password`.
+- `tui` resolves configured gateway auth SecretRefs for token/password auth when possible (`env`/`file`/`exec` providers).
+- When launched from inside a configured agent workspace directory, TUI auto-selects that agent for the session key default (unless `--session` is explicitly `agent:<id>:...`).
+- To show the Gateway hostname in the footer for non-local URL-backed connections, run `openclaw config set tui.footer.showRemoteHost true`. The host label is off by default and never appears for loopback or embedded local connections.
+- Local mode uses the embedded agent runtime directly. Most local tools work, but Gateway-only features are unavailable.
+- Local mode adds `/auth [provider]` inside the TUI command surface.
+- Plugin approval gates still apply in local mode. Tools that require approval prompt for a decision in the terminal; nothing is silently auto-approved because the Gateway is not involved.
+- Session [goals](/tools/goal) appear in the footer and can be managed with `/goal`.
+
+## Examples
+
+```bash
+openclaw chat
+openclaw tui --local
+openclaw tui
+openclaw tui --url ws://127.0.0.1:18789 --token <token>
+openclaw tui --session main --deliver
+openclaw chat --message "Compare my config to the docs and tell me what to fix"
+# when run inside an agent workspace, infers that agent automatically
+openclaw tui --session bugfix
+```
+
+## Config repair loop
+
+Use local mode when the current config already validates and you want the
+embedded agent to inspect it, compare it against the docs, and help repair it
+from the same terminal:
+
+If `openclaw config validate` is already failing, use `openclaw configure` or
+`openclaw doctor --fix` first. `openclaw chat` does not bypass the invalid-
+config guard.
+
+```bash
+openclaw chat
+```
+
+Then inside the TUI:
+
+```text
+!openclaw config file
+!openclaw docs gateway auth token secretref
+!openclaw config validate
+!openclaw doctor
+```
+
+Apply targeted fixes with `openclaw config set` or `openclaw configure`, then
+rerun `openclaw config validate`. See [TUI](/web/tui) and [Config](/cli/config).
+
+## Related
+
+- [CLI reference](/cli)
+- [TUI](/web/tui)
+- [Goal](/tools/goal)

package/docs/cli/uninstall.md

@@ -0,0 +1,45 @@
+---
+summary: "CLI reference for `openclaw uninstall` (remove gateway service + local data)"
+read_when:
+  - You want to remove the gateway service and/or local state
+  - You want a dry-run first
+title: "Uninstall"
+---
+
+# `openclaw uninstall`
+
+Uninstall the gateway service + local data (CLI remains).
+
+Options:
+
+- `--service`: remove the gateway service
+- `--state`: remove state and config
+- `--workspace`: remove workspace directories
+- `--app`: remove the macOS app
+- `--all`: remove service, state, workspace, and app
+- `--yes`: skip confirmation prompts
+- `--non-interactive`: disable prompts; requires `--yes`
+- `--dry-run`: print actions without removing files
+
+Examples:
+
+```bash
+openclaw backup create
+openclaw uninstall
+openclaw uninstall --service --yes --non-interactive
+openclaw uninstall --state --workspace --yes --non-interactive
+openclaw uninstall --all --yes
+openclaw uninstall --dry-run
+```
+
+Notes:
+
+- Run `openclaw backup create` first if you want a restorable snapshot before removing state or workspaces.
+- `--state` preserves configured workspace directories unless `--workspace` is also selected.
+- `--all` is shorthand for removing service, state, workspace, and app together.
+- `--non-interactive` requires `--yes`.
+
+## Related
+
+- [CLI reference](/cli)
+- [Uninstall](/install/uninstall)

package/docs/cli/update.md

@@ -0,0 +1,283 @@
+---
+summary: "CLI reference for `openclaw update` (safe-ish source update + gateway auto-restart)"
+read_when:
+  - You want to update a source checkout safely
+  - You are debugging `openclaw update` output or options
+  - You need to understand `--update` shorthand behavior
+title: "Update"
+---
+
+# `openclaw update`
+
+Safely update OpenClaw and switch between stable/beta/dev channels.
+
+If you installed via **npm/pnpm/bun** (global install, no git metadata),
+updates happen via the package-manager flow in [Updating](/install/updating).
+
+## Usage
+
+```bash
+openclaw update
+openclaw update status
+openclaw update repair
+openclaw update wizard
+openclaw update --channel beta
+openclaw update --channel dev
+openclaw update --tag beta
+openclaw update --tag main
+openclaw update --dry-run
+openclaw update --no-restart
+openclaw update --yes
+openclaw update --json
+openclaw --update
+```
+
+## Options
+
+- `--no-restart`: skip restarting the Gateway service after a successful update. Package-manager updates that do restart the Gateway verify the restarted service reports the expected updated version before the command succeeds.
+- `--channel <stable|beta|dev>`: set the update channel (git + npm; persisted in config).
+- `--tag <dist-tag|version|spec>`: override the package target for this update only. For package installs, `main` maps to `github:openclaw/openclaw#main`; GitHub/git source specs are packed into a temporary tarball before the staged global npm install.
+- `--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, including
+  `postUpdate.plugins.warnings` when corrupt or unloadable managed plugins need
+  repair after the core update succeeds, beta-channel plugin fallback details
+  when a plugin has no beta release, and `postUpdate.plugins.integrityDrifts`
+  when npm plugin artifact drift is detected during post-update plugin sync.
+- `--timeout <seconds>`: per-step timeout (default is 1800s).
+- `--yes`: skip confirmation prompts (for example downgrade confirmation).
+
+`openclaw update` does not have a `--verbose` flag. Use `--dry-run` to preview
+the planned channel/tag/install/restart actions, `--json` for machine-readable
+results, and `openclaw update status --json` when you only need channel and
+availability details. If you are debugging Gateway logs around an update,
+console verbosity and file log level are separate: Gateway `--verbose` affects
+terminal/WebSocket output, while file logs require `logging.level: "debug"` or
+`"trace"` in config. See [Gateway logging](/gateway/logging).
+
+<Note>
+In Nix mode (`OPENCLAW_NIX_MODE=1`), mutating `openclaw update` runs are disabled. Update the Nix source or flake input for this install instead; for nix-openclaw, use the agent-first [Quick Start](https://github.com/openclaw/nix-openclaw#quick-start). `openclaw update status` and `openclaw update --dry-run` remain read-only.
+</Note>
+
+<Warning>
+Downgrades require confirmation because older versions can break configuration.
+</Warning>
+
+## `update status`
+
+Show the active update channel + git tag/branch/SHA (for source checkouts), plus update availability.
+
+```bash
+openclaw update status
+openclaw update status --json
+openclaw update status --timeout 10
+```
+
+Options:
+
+- `--json`: print machine-readable status JSON.
+- `--timeout <seconds>`: timeout for checks (default is 3s).
+
+## `update repair`
+
+Rerun update finalization after the core package already changed but later
+repair work did not finish cleanly. This is the supported recovery path when
+`openclaw update` installed the new core package but post-core plugin sync,
+managed npm plugin metadata, registry refresh, or doctor repair still needs to
+converge.
+
+```bash
+openclaw update repair
+openclaw update repair --channel beta
+openclaw update repair --json
+```
+
+Options:
+
+- `--channel <stable|beta|dev>`: persist the update channel before repair and
+  run plugin convergence against that channel.
+- `--json`: print machine-readable finalization JSON.
+- `--timeout <seconds>`: timeout for repair steps (default `1800`).
+- `--yes`: skip confirmation prompts.
+- `--no-restart`: accepted for update command parity; repair never restarts the
+  Gateway.
+
+`openclaw update repair` runs `openclaw doctor --fix`, reloads the repaired
+config and install records, syncs tracked plugins for the active update channel,
+updates managed npm plugin installs, repairs missing configured plugin payloads,
+refreshes the plugin registry, and writes the converged install-record metadata.
+It does not install a new core package and does not restart the Gateway.
+
+## `update wizard`
+
+Interactive flow to pick an update channel and confirm whether to restart the Gateway
+after updating (default is to restart). If you select `dev` without a git checkout, it
+offers to create one.
+
+Options:
+
+- `--timeout <seconds>`: timeout for each update step (default `1800`)
+
+## What it does
+
+When you switch channels explicitly (`--channel ...`), OpenClaw also keeps the
+install method aligned:
+
+- `dev` → ensures a git checkout (default: `~/openclaw`, or `$OPENCLAW_HOME/openclaw` when
+  `OPENCLAW_HOME` is set; override with `OPENCLAW_GIT_DIR`),
+  updates it, and installs the global CLI from that checkout.
+- `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) launches the CLI update path
+outside the live Gateway request handler. Control-plane `update.run`
+package-manager updates and supervised git-checkout updates also use a
+managed-service handoff instead of replacing the package tree or rebuilding
+`dist/` inside the live Gateway process. The Gateway starts a detached helper,
+exits, and the helper runs the normal `openclaw update --yes --json` CLI path
+from outside the Gateway process tree. If that handoff is unavailable,
+`update.run` returns a structured response with the safe shell command to run
+manually.
+
+For package-manager installs, `openclaw update` resolves the target package
+version before invoking the package manager. npm global installs use a staged
+install: OpenClaw installs the new package into a temporary npm prefix, verifies
+the packaged `dist` inventory there, then swaps that clean package tree into the
+real global prefix. If verification fails, post-update doctor, plugin sync, and
+restart work do not run from the suspect tree. Even when the installed version
+already matches the target, the command refreshes the global package install,
+then runs plugin sync, a core-command completion refresh, and restart work. This
+keeps packaged sidecars and channel-owned plugin records aligned with the
+installed OpenClaw build while leaving full plugin-command completion rebuilds to
+explicit `openclaw completion --write-state` runs.
+
+When a local managed Gateway service is installed and restart is enabled,
+package-manager and git-checkout updates stop the running service before
+replacing the package tree or mutating the checkout/build output. The updater
+then refreshes the service metadata from the updated install, restarts the
+service, and verifies the restarted Gateway before reporting
+`Gateway: restarted and verified.`. Package-manager updates additionally verify
+the restarted Gateway reports the expected package version; git-checkout updates
+verify gateway health and service readiness after the rebuild. On macOS, the
+post-update check also verifies the LaunchAgent is loaded/running for the active
+profile and the configured loopback port is healthy. If the plist is installed
+but launchd is not supervising it, OpenClaw re-bootstraps the LaunchAgent
+automatically, then reruns the health/version/channel readiness checks. A fresh
+bootstrap loads the RunAtLoad job directly, so update recovery does not
+immediately `kickstart -k` the newly spawned Gateway. If the Gateway still does
+not become healthy, the command exits non-zero and prints the restart log path
+plus explicit restart, reinstall, and package rollback instructions. If restart
+cannot run, the command prints `Gateway: restart skipped (...)` or
+`Gateway: restart failed: ...` with a manual `openclaw gateway restart` hint.
+With `--no-restart`, package replacement or git rebuild still runs but the
+managed service is not stopped or restarted, so the running Gateway may keep old
+code until you restart it manually.
+
+### Control-plane response shape
+
+When `update.run` is invoked through the Gateway control plane on a
+package-manager install or supervised git checkout, the handler reports the
+handoff initiation separately from the CLI update that continues after the
+Gateway exits:
+
+- `ok: true`, `result.status: "skipped"`,
+  `result.reason: "managed-service-handoff-started"`, and
+  `handoff.status: "started"` mean the Gateway created the managed-service
+  handoff and scheduled its own restart so the detached helper can run
+  `openclaw update --yes --json` outside the live service process.
+- `ok: false`, `result.reason: "managed-service-handoff-unavailable"`, and
+  `handoff.status: "unavailable"` mean OpenClaw could not find a supervising
+  service boundary and durable service identity for a safe handoff. For
+  example, systemd handoff requires the OpenClaw unit identity
+  (`OPENCLAW_SYSTEMD_UNIT`), not only ambient systemd process markers. The
+  response includes `handoff.command`, the shell command to run from outside the
+  Gateway.
+- `ok: false`, `result.reason: "managed-service-handoff-failed"` means the
+  Gateway tried to create the handoff but could not spawn the detached helper.
+
+The `sentinel` payload is still written before the Gateway exits, and the CLI
+handoff updates the same restart sentinel after the managed-service restart
+health checks complete. During the handoff, the sentinel can carry
+`stats.reason: "restart-health-pending"` with no success continuation; the
+restarted Gateway keeps polling it and only fires the continuation after the CLI
+has verified service health and rewritten the sentinel with the final `ok`
+result. `openclaw status` and `openclaw status --all` show an `Update restart`
+row while that sentinel is pending or failed, and `update.status` refreshes and
+returns the latest sentinel.
+
+## Git checkout flow
+
+### Channel selection
+
+- `stable`: checkout the latest non-beta tag, then build and 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 and rebase.
+
+### Update steps
+
+<Steps>
+  <Step title="Verify clean worktree">
+    Requires no uncommitted changes.
+  </Step>
+  <Step title="Switch channel">
+    Switches to the selected channel (tag or branch).
+  </Step>
+  <Step title="Fetch upstream">
+    Dev only.
+  </Step>
+  <Step title="Preflight build (dev only)">
+    Runs the TypeScript build in a temp worktree. If the tip fails, walks back up to 10 commits to find the newest buildable commit. Set `OPENCLAW_UPDATE_PREFLIGHT_LINT=1` to also run lint during this preflight; lint runs in constrained serial mode because user update hosts are often smaller than CI runners.
+  </Step>
+  <Step title="Rebase">
+    Rebases onto the selected commit (dev only).
+  </Step>
+  <Step title="Install dependencies">
+    Uses the repo package manager. For pnpm checkouts, the updater bootstraps `pnpm` on demand (via `corepack` first, then a temporary `npm install pnpm@11` fallback) instead of running `npm run build` inside a pnpm workspace.
+  </Step>
+  <Step title="Build Control UI">
+    Builds the gateway and the Control UI.
+  </Step>
+  <Step title="Run doctor">
+    `openclaw doctor` runs as the final safe-update check.
+  </Step>
+  <Step title="Sync plugins">
+    Syncs plugins to the active channel. Dev uses bundled plugins; stable and beta use npm. Updates tracked plugin installs.
+  </Step>
+</Steps>
+
+On the beta update channel, tracked npm and ClawHub plugin installs that follow
+the default/latest line try a plugin `@beta` release first. If the plugin has no
+beta release, OpenClaw falls back to the recorded default/latest spec and reports
+that as a warning. For npm plugins, OpenClaw also falls back when the beta
+package exists but fails install validation. These plugin fallback warnings do
+not make the core update fail. Exact versions and explicit tags are not
+rewritten.
+
+<Warning>
+If an exact pinned npm plugin update resolves to an artifact whose integrity differs from the stored install record, `openclaw update` aborts that plugin artifact update instead of installing it. Reinstall or update the plugin explicitly only after verifying that you trust the new artifact.
+</Warning>
+
+<Note>
+Post-update plugin sync failures that are scoped to a managed plugin and that the sync path can route around (e.g. an unreachable npm registry for a non-essential plugin) are reported as warnings after the core update succeeds. The JSON result keeps the top-level update `status: "ok"` and reports `postUpdate.plugins.status: "warning"` with `openclaw update repair` and `openclaw plugins inspect <id> --runtime --json` guidance. Unexpected updater or sync exceptions still fail the update result. Fix the plugin install or update error, then rerun `openclaw update repair`.
+
+After the per-plugin sync step, `openclaw update` runs a mandatory **post-core convergence** pass before the gateway is restarted: it repairs missing configured plugin payloads, validates each _active_ tracked install record on disk, and statically verifies its `package.json` is parseable (and any explicitly-declared `main` exists). Failures from this pass — and an invalid OpenClaw config snapshot — return `postUpdate.plugins.status: "error"` and flip the top-level update `status` to `"error"`, so `openclaw update` exits non-zero and the gateway is _not_ restarted with an unverified plugin set. The error includes structured `postUpdate.plugins.warnings[].guidance` lines pointing at `openclaw update repair` and `openclaw plugins inspect <id> --runtime --json` for follow-up. Disabled plugin entries and records that are not trusted-source-linked official sync targets are skipped here, mirroring the `skipDisabledPlugins` policy used by the missing-payload check, so a stale disabled plugin record cannot block an otherwise valid update.
+
+When the updated Gateway starts, plugin loading is verify-only: startup does not
+run package managers or mutate dependency trees. Package-manager `update.run`
+restarts are handed to the CLI managed-service path, so the package swap happens
+outside the old Gateway process and the service health checks decide whether the
+update can be reported as complete.
+
+If pnpm bootstrap still fails, the updater stops early with a package-manager-specific error instead of trying `npm run build` inside the checkout.
+</Note>
+
+## `--update` shorthand
+
+`openclaw --update` rewrites to `openclaw update` (useful for shells and launcher scripts).
+
+## Related
+
+- `openclaw doctor` (offers to run update first on git checkouts)
+- [Development channels](/install/development-channels)
+- [Updating](/install/updating)
+- [CLI reference](/cli)