openclaw update

Update OpenClaw and switch between stable/extended-stable/beta/dev channels.

If you installed via npm/pnpm/bun (global install, no git metadata), updates go through the package-manager flow described in Updating.

Custom npm prefixes such as ~/.npm-global are recognized from npm's configured prefix and the installed OpenClaw launcher. A prefix configured in ~/.npmrc does not need a matching NPM_CONFIG_PREFIX environment variable. If no owner can be identified, the CLI includes the inspected package, prefix, and launcher paths and the package-manager probe results in its guidance. Installation inspection also reports the root, Git metadata, node_modules layout, and service unit target (or why it was not inspected). An unrecognized root skips target preflight and gives commands to locate the owning installation.

An older updater that stops before staging cannot use this repair. For a known npm installation, supply its configured prefix explicitly for that update: NPM_CONFIG_PREFIX="$(npm prefix -g)" openclaw update.

An installation without a detected package-manager owner records a skipped update, exits successfully, and leaves the Gateway running. For Docker/container images, pull or build the new image and recreate the container with the same state/config mounts. For a standalone or extracted tarball installation, reinstall using the original method; Yarn global installations must be updated with Yarn. The CLI displays this next action. Existing profiles also record it in update history and include it in JSON as run.origin.nextAction. With --json, a fresh profile emits the guidance to stderr and does not create a state database for a skipped update. These non-outcomes do not run rollback verification or offer an update failure report.

Usage

openclaw updateopenclaw update statusopenclaw update repairopenclaw update cleanup --dry-runopenclaw update wizardopenclaw update --channel extended-stableopenclaw update --channel betaopenclaw update --channel devopenclaw update --tag betaopenclaw update --dry-runopenclaw update --no-restartopenclaw update --yesopenclaw update --accept-capabilitiesopenclaw update --jsonopenclaw --update

openclaw --update rewrites to openclaw update (useful for shells and launcher scripts).

Invalid or unreadable configuration reports invalid-config before database schema inspection. The diagnostic identifies invalid fields and recommends openclaw doctor --fix, followed by correcting any remaining errors. A dry run keeps this guidance in its JSON notes without changing the configuration. Guided recovery recognizes the saved config failure after a later successful update and still verifies the installed runtime and Gateway readiness.

The 2026.9.4 updater reports this condition as database-schema-preflight and can show mode: unknown even after resolving an npm target. Before another update or dry run replaces the latest history, run openclaw update status --json and inspect lastRun.origin.nextAction and lastRun.target for the recorded reason and target. A candidate release cannot repair an installed updater that refuses before staging it; correct the configuration before retrying.

Update admission recognizes orphan task_delivery_state rows whose parent tasks are missing as repairable. When it can acquire Doctor's ownership fences, it runs the same preservation-first recovery before creating update history. Recovery and its ledger entry commit together; the entry records the row count and recovery directory. A live Gateway owner, read-only store, or failed preservation prevents repair and reports openclaw doctor --fix as the next action. Other foreign-key violations and structural damage still refuse admission. --dry-run reports the repairable condition without recovering rows or creating an update ledger entry for that refused preview.

The installed 2026.9.4 updater cannot use this recovery before updating itself. If it refuses with a database integrity error, install the corrective release manually and run openclaw doctor --fix.

Failed update and repair attempts enter recovery triage after service recovery and cleanup finish. Preflight and finalization join admitted command cleanup before handing off ownership or reporting completion. If cleanup cannot confirm that work stopped, the updater retains any acquired ownership and recovery artifacts and skips automatic service compensation and repair. Inspect openclaw update status and resolve the pending execution before retrying. A verified rollback does not automatically start triage: the previous generation is running again, and the report keeps the failing check as the reason. An interactive update offers the diagnose/report menu with Exit selected by default. Declining or cancelling preserves the failed update's nonzero exit status. JSON, non-interactive, --yes, and managed-service handoff invocations do not prompt after rollback.

Update completion prints the terminal outcome and a local Markdown report path before exiting, including unexpected failures. Failed runs keep rollback-facing diagnostic JSON within the released 8 KiB limit. That file links a separate artifact containing every individually bounded Doctor finding; the Markdown report also retains the complete inventory. JSON output includes reportPath; a report-write failure prints a warning and preserves the update outcome.

After a final interactive update failure, Diagnose update failure and Report update failure are separate choices. Reporting first shows the exact sanitized issue body and defaults confirmation to No. After confirmation, OpenClaw checks the GitHub CLI's active github.com account with a silent, read-only request before issue creation. Fallback and pending outcomes retain the sanitized report locally; a confirmed issue keeps only its durable issue URL. If the CLI is missing or that check cannot confirm authentication, OpenClaw provides a prefilled issue link without starting issue creation. If the exact report exceeds the browser URL limit, OpenClaw keeps the sanitized body locally and returns to the action menu, where reporting can be chosen and confirmed again. A report preparation or submission error also returns to that menu; Diagnose runs only when selected explicitly. In the Control UI, an interrupted pre-create preparation becomes retryable after its local reservation expires. After an uncertain creation result, OpenClaw checks for an issue matching the exact report. If neither a verified issue URL nor a definitive rejection is available, the report stays pending with no replay link because an issue may already exist. --yes, --json, non-interactive runs, and managed-service handoffs never submit a report.

For admitted updates, unexpected exceptions retain a bounded, redacted error identity and source location in update history, along with the operation reached and the installation and target facts resolved so far. Failure reports include the initiating action and the owner's recorded rollback outcome. A failure during installation or target resolution keeps that resolution step visible. Older updater processes cannot recover details they already discarded; a report generated by newer code only includes facts that were recorded by the updater that handled the failure.

Automation and SSH

For an authorized update on another host, use the target installation's owning account and a non-interactive SSH command:

ssh -T user@gateway-host 'openclaw update --yes' </dev/null

Ensure openclaw resolves to the intended installation in that account's SSH environment. Add the existing global --profile <name> before update when targeting a named profile.

An active chat session alone does not prevent an explicit update. --yes skips confirmation and optional shell-completion prompts. Without it, ordinary upgrades can still run with piped input, but an operation requiring confirmation, such as a downgrade, fails promptly. Failure-report menus and triage consent prompts do not wait for input when stdin is not a terminal. --yes does not grant exec approval or accept changed plugin capabilities.

An agent updating the Gateway that hosts its own session should use the gateway tool's update.run action when available. The SSH recipe is for another host; verify that the destination is not that same Gateway. Normal execution approvals and deployment ownership still apply.

Native service commands during updates

Native service install, restart, and stop commands launched by the updater through the target CLI retain the original update owner while their child processes settle. A command whose owner exits or loses its lease cannot start another native mutation or commit its pending config changes. A new update remains excluded while a registered child or its process group is still alive.

The target runtime must support this ownership handoff. Candidate validation checks that support before stopping the Gateway or activating its replacement. A missing target CLI or an older target without support is refused; the updater does not invoke the old runtime installer as a substitute. Authorized installation-root changes bind the destination CLI separately while retaining the original update owner. Update-owned commands also refuse unmanaged restart/stop and detached restart or Windows Startup-folder fallbacks that cannot retain this ownership. Ordinary user-invoked openclaw gateway commands keep their existing behavior.

On Windows, capability probes stay alive until the updater finishes binding their process identity. If Windows cannot supply a process creation timestamp, the updater retains the identity established by the live parent or uses the child's recorded launcher identity, with a warning in the run history and diagnostic logs. A different observed identity still refuses the handoff. Scheduled Tasks using InteractiveToken remain supported; this does not require storing a task password.

This target-CLI protection does not cover every Doctor or plugin child, the in-process service preparation before package mutation, or the separate deferred-install activation checks.

Options

Post-core repair Doctor and openclaw update finalize run without a separate per-Doctor deadline unless the operator supplies --timeout. A fresh post-core process receives the operator choice separately from its internal step allowance. Older targets retain their existing allowance and deadline behavior.

When --timeout is omitted, current CLI and RPC finalization do not add an aggregate activation deadline. Explicit operator limits and inherited activation allowances still apply; older or unrecognized handoffs retain their existing finite-deadline behavior. Independent install, build, plugin-operation, readiness, and cleanup bounds still apply. An explicit --timeout <seconds> limits each finalization phase and its child commands. Admission and config phases scale with shared SQLite state.

Post-plugin config validation and readiness checks use the measured shared and agent database sizes after Doctor finishes, including WAL files. Serial plugin operations retain individual deadlines. When an aggregate activation budget is present, it uses the measured database sizes, observed candidate startup, plugin count, and the caller's step allowance. Migrated finalization preserves explicit or inherited allowances. Aggregate expiry reports update-activation-timeout and retains ownership until writers settle; it does not authorize rollback or restart. Use openclaw update status and Doctor for recovery guidance.

There is no --verbose flag. Use --dry-run to preview planned actions, --json for machine-readable results, and openclaw update status --json for channel, availability, and the latest durable update report. Gateway console verbosity (--verbose) and file log level (logging.level: "debug"/"trace") are independent knobs; see Gateway logging.

Interactive updates show phase transitions, the current step, and elapsed time. The phases match the Control UI: requested, staging, validating, optional repairing, activating, restarting, verifying, and finished. When output is piped or captured in a log, progress prints without animation. repairing can follow failed candidate validation or failed post-activation verification when rollback is unsafe or has failed; successful repair returns to validation or verification. The Control UI shows this optional phase only after it starts. Failed steps include the final diagnostics from both output streams; timeouts are labeled explicitly. The final report includes the outcome, recorded phase durations, failed steps, verification facts, and recovery guidance. --json keeps stdout machine-readable and does not print progress steps.

When switching from a dev checkout to a package, the updater replaces npm's install link and leaves the external checkout untouched. If activation fails, restoring that link and its launchers does not verify the mutable checkout's runtime. Recovery stays unverified and does not authorize an automatic restart; inspect the checkout and recovery report before restarting it.

For a profile without a runtime database, an older npm target initializes its compatible state before the updater records history. The selected release's Doctor runs before activation, including when npm's install hooks already created the database. Existing databases retain their downgrade protections.

If database schema preflight cannot inspect the configured paths because the config is invalid, its refusal lists the config file and invalid fields. Run openclaw doctor --fix to repair retired or unrecognized fields, correct any remaining errors, and retry the update. Preflight leaves the config unchanged.

Explicit package specs on a fresh profile first stage with a temporary OpenClaw profile. The updater inspects the staged runtime's declared schema and Node requirements before admitting changes to the selected profile. Artifacts without declared schema support are refused without creating the profile's runtime database. Preparation uses the original package spec and owning package manager.

A fresh-profile --dry-run leaves the database absent and does not record a run. For package targets, it checks the exact target's Node requirements using the same runtime planner as a real update. Text output and JSON notes report Would refuse update when no usable runtime is available, or Would replace when the updater can refresh its owned managed service to a compatible Node. The preview still exits successfully and does not install a package or change the service. If package metadata cannot be resolved, retry with an exact published --tag; failed target selection does not initialize the profile with the updater's schema. Metadata failures retain the detected update mode and a specific failure fact for registry lookup, dist-tag resolution, version mismatch, schema declarations, or Git target inspection. The summary and openclaw update status --json include the reason and next step; the bounded failure report includes the same public description without publishing local paths or registry response text. Existing updaters cannot gain these diagnostics until the candidate has been installed.

--dry-run --json reports the known installed version in currentVersion for package and Git installs, including a saved dev channel that selects conversion to Git. If the target version is unresolved, targetVersion remains null and the additive targetVersionReason field explains why. Resolved targets omit this field. The text preview also shows the installed version and explains unresolved targets.

--yes also skips the optional shell-completion setup prompt. Existing completion profiles and caches are still repaired when needed; installing completion in a new shell profile remains an interactive choice.

--tag changes only this package update. A saved update.channel continues to govern later foreground and automatic updates, even after a one-off beta install. Use --channel to change that policy.

For explicit package artifacts, configured plugin availability is checked against the privately staged package version before rehearsal or activation. --dry-run does not stage the artifact and reports that this check remains pending.

Managed update handoffs preserve the selected artifact, including already-current repeats, so target checks use that artifact's database schema and runtime requirements.

For source checkouts, --dry-run previews the update flow without fetching Git refs or checking working-tree changes. The real update checks for uncommitted changes before modifying the checkout. Use openclaw update status to inspect the current branch, version, and update availability.

update wizard

Interactive flow to pick an update channel and confirm whether to restart the Gateway afterward (defaults to restart). Selecting dev without a git checkout offers to create one.

The channel picker reads the local install identity without checking Git freshness or dependencies. Those checks run when you apply the update; use openclaw update status to inspect availability first.

Detailed topics

• Recover a failed update
• update status
• Run history and reports
• update repair
• update cleanup
• What it does
• Validation and activation
• Recovery limits
• Compatibility-checked package rollback
• Restart handoff
• Control-plane response shape
• Git checkout flow
• Channel selection
• Update steps
  • Verify clean worktree
  • Resolve the target
  • Build a candidate
  • Validate the candidate
  • Activate and verify
  • Sync plugins
• Plugin sync details

Related

• openclaw doctor (offers to run update first on git checkouts)
• Development channels
• Updating
• CLI reference