Updating

Keep OpenClaw up to date.

Failed-update recovery on Linux restarts an installed Gateway through systemd. If a foreground OpenClaw process owns that service's state directory, recovery checks native restart permission and live identity, requests graceful shutdown, and waits for it to exit before starting the unit. Processes belonging to another supervisor are preserved. An inconclusive readiness check is reported separately from current serving health. This recovery repair is supplied by the candidate CLI; older updaters using gateway restart --preserve-definition can use it without an updater upgrade.

App-owned packages declare their update owner in openclaw-install-owner.json at the package root. For owner: "macos-app", update OpenClaw.app through its app updater to update the bundled Gateway and runtime together. openclaw update, openclaw update repair, and Gateway update requests return the marker's update hint without changing the package or stopping the Gateway; background checks skip package-registry updates. Missing or invalid markers retain normal install behavior, with a warning for an invalid marker.

After a Mac app update, recovery checks the service selected by the connection mode: the local Gateway or, with a remote primary, the Mac node service. If a custom node launcher cannot be inspected, check its node LaunchAgent before retrying. This node inspection failure does not invalidate an already verified local Gateway. Recovery keeps the update receipt for retry, verifies the node after its launcher is repaired, and leaves the custom launcher unchanged.

For standalone builds, update the owning desktop app or replace the complete executable and runtime directory. The standalone CLI refuses package-manager and git updates with a visible next step; mixing artifacts from different builds is unsupported.

For Docker, Podman, and Kubernetes image replacements, see Upgrading container images. The image entrypoint runs Doctor before starting the Gateway and exits if mounted state cannot be repaired safely.

For distro packages and image-based systems (bootc, rpm-ostree), see System-package and image-based installs. Nothing OpenClaw-managed runs Doctor for these, and an image-based host starts the Gateway on the new release before anyone can.

Before upgrading, follow the preflight checklist. Before a significant update, create a verified backup. Automatic config copies and migration recovery originals are not a full-state backup.

Update implementation contract

After candidate Doctor migrates runtime-pin metadata, activation reads that completed intent before rebinding the managed Gateway. Missing metadata at the start of an update no longer forces a restart of the old installation against newly migrated state. Existing native definition and runtime-intent checks still protect operator changes. This requires the installed updater to contain the fix.

Private plugin projection materializes eligible external data-suffixed file links at their logical in-package filenames before recording the final code-link inventory. Both the alias and its inventoried canonical target must have one of the case-sensitive extensions .txt, .json, .yaml, .yml, .toml, .ini, .cfg, .csv, or .xml; the target must be a non-executable regular file outside the alias's nearest package root with a regular inventoried package.json (symlink manifests do not establish this boundary). The existing guarded copy checks source identity, bounds bytes, refuses occupied destinations, and creates an independent private file. Each alias is included in snapshot space accounting.

This is not general symlink flattening or file-content classification. Package scope metadata (package.json), relocation-owned files (.modules.yaml and .bin launchers), executable targets, code/native/unknown extensions, internal links, directory/dependency/host links, and dangling links keep their existing handling. A data-looking alias to a target with a code/native/unknown suffix is not eligible. Non-executable binary bytes (including ELF) with allowed data suffixes are eligible: this is a path/mode contract, not native-content detection. Data that requires symlink identity, shared writes, canonical-parent sibling lookup, or a suffix outside this list is not supported by this normalization. Files mislabeled as ordinary data are not identified by inspecting their contents.

Projection uses only already inventoried entries and edges; it does not discover new paths or grant Doctor additional filesystem authority. Ordinary generation capture already detaches file aliases, so resource bytes and logical filenames, not original lstat, readlink, inode, or shared-write identity, are the supported data contract. Fix representation at this producer boundary instead of carrying exceptions through Doctor and each runtime consumer. Recognized native files retain separate identity and admission rules. After binding validation, a late alias retarget cannot redirect the copy: it uses the inventoried canonical target path, with source identity rechecked by the guarded copier. The runtime performing plugin projection must contain this fix; an older projector does not gain it from a receipt or new environment variable. Existing update/Doctor admission and rollback checks are unchanged.

Candidate Doctor recovers interrupted legacy heartbeat runs through cron's startup recovery owner before converting them to automations, while holding offline maintenance custody. Live or unproved runtime ownership leaves the conversion and configuration pending with an update warning. Runs needing startup notifications are converted with their original run marker, history, and receipt intact so the Gateway can recover them and deliver their notifications without quarantining the retired payload. Conversion preserves pending execution facts even when it disables the monitor; startup still restores the recorded result without re-enabling it. The candidate must contain this fix; published updaters need no new marker or schema change.

Candidate Doctor repairs retained ISO-8601 session endedAt strings before canonical session admission, preserving the original database backup and updating indexed timing together. This repair must be present in the candidate Doctor; the installed updater needs no protocol or schema change.

Engine identification reads the committed SQLite engine anchor in an isolated read-only transaction without copying a healthy live database. Hot rollback journals and incomplete WAL families retain private recovery, and unreadable or invalid anchors still refuse admission. Artifact-preserving inspection scopes and offline maintenance or exclusive source locks also retain private reads so engine identification cannot change retained SHM bytes or borrow another process's native custody. This applies to conditional update capture, engine admission, and version-zero candidate validation probes. The binary performing the probe must contain this fix; a candidate cannot repair an older installed updater's preflight. Strict recovery captures keep their separate artifact-preservation requirements. No schema or worker-version bump is required.

Git-source and immutable updates probe support before passing --no-lazy-fetch. Older Git runs the same inspection commands without that option; partial clones may fetch promised objects. This fix must be present in the installed updater; a downloaded candidate cannot repair an older updater's preflight.

Interactive failed-update triage preserves the invoking operator's PATH, home, and authentication environment before candidate admission enters the managed Gateway environment. Repair agents still receive the latest target installation's state, config, and workspace selectors and require launch confirmation. The installed updater must contain this fix; a downloaded candidate cannot repair the older updater's already-captured environment. No schema or config migration is required.

SQLite header-probe timeouts report the discovery path count and link to the manual package-manager hop. A probe batch that misses its 10-second deadline now splits and retries, so slow or cold storage gets an answer; a path that cannot answer alone still refuses the backup. Backup refusal and rollback safety are unchanged. These changes require the updater performing discovery to contain the fix; a candidate cannot change an older installed updater's probe.

Candidate Doctor prepares plugin setup sources asynchronously before resolving legacy session migrations. Configured external channels can then finish post-plugin Doctor without an unprepared-source refusal blocking later state repairs. Existing plugin selection, activation, and source checks still apply. The candidate must contain this fix; published updaters need no new marker or schema change.

Plugin updates preserve authored environment references when a replacement plugin moves their settings, including single-file includes. The candidate plugin-update command must contain this repair; the installed updater needs no new marker or schema migration. Existing config and plugin-index records remain readable. Previously flattened literals are preserved, not guessed back into references. Config publication, backup, rollback, and deferred data-migration guidance keep their existing owners.

Candidate Gateway rehearsal can prepare strictly valid config in its complete private update namespace even when a newer release wrote the config. It preserves the source writer stamp for installed-updater capture checks; the target's normal validated-downgrade writer records its version before live restart. Ordinary service startup, force/reset actions, invalid config, and paths outside that private namespace retain their future-config refusal. The candidate Gateway must contain this repair; the installed updater needs no change.

Candidate state inventory includes normally discovered global plugins even when there is no install record or explicit load path. Their private copies retain extensions/<name> discovery, including linked plugin directories, so candidate Doctor validates configured slots against the same installed plugins. The candidate snapshot worker must contain this fix; validation remains strict and live plugin configuration is unchanged.

During captured SQLite migrations, candidate Doctor reads current update authority through private snapshots. It does not retain an independent WAL reader that can block its own next migration's exclusive lock. Exec approvals policy, local socket credentials, and verified rollback attribution retain their existing checks. This repair requires the candidate Doctor; the installed updater needs no change.

Gateway cleanup preserves retired managed npm plugin generations referenced by absolute or home-relative paths in startup or current configuration. This keeps explicit executable pins working after an update without rewriting their settings. Removing a startup reference allows reclamation after a Gateway restart; current references protect their files on each cleanup pass. The candidate Gateway must contain this fix. It does not restore generations already deleted or discover references supplied only through environment variables, relative paths, or external symlinks. An incidental path-valued setting can conservatively retain extra files.

The candidate macOS app's narrow credential Doctor also completes pending local service-runtime intent migration before native startup selects a Gateway. This prevents an absent migration receipt from preserving the old seed after credential cutover advances shared state. The daemon migration owner keeps explicit pins and conflict refusals; preparation does not seed a runtime or start a service. Retry also reconciles intent when credential cutover already completed. The candidate must contain this fix; older installed updaters are unchanged.

After draining database readers and writers, candidate Doctor inspects SQLite reclamation mode without copying databases whose WAL is empty or absent and whose rollback journal is absent. Immutable reads preserve source artifacts; databases with recovery content retain the private snapshot path. Conversion still uses the existing maintenance, space, and integrity checks. This requires the candidate Doctor; the installed updater needs no new protocol.

Synchronous integrity workers preserve the migration owner's selected schema-only check, matching the asynchronous worker path. Explicit full verification keeps its full coverage; the candidate must contain this transport fix.

Candidate Doctor prepares its read-only SQLite inspection snapshots asynchronously, including lease and auth inspection and captured session repair planning. Cancellation joins the snapshot child and its cleanup. Snapshot allocation checks the destination's free space against the database, WAL, and rollback journal before copying; unknown capacity retains best-effort behavior. These fixes must be present in the candidate Doctor and snapshot worker; they do not change an older installed updater's inspection. New macOS and Windows agent leases record platform boot identity so a dead owner from the same boot can use existing quick recovery admission. Legacy or unknown provenance still requires the full integrity gate; existing leases are not backfilled.

Pre-update config copies publish through a temporary file and same-directory rename. An interrupted write preserves the previous .pre-update copy, and a later snapshot attempt can retry. Post-update recovery refuses malformed copies and leaves the current config intact. This repair must be present in the updater taking the snapshot; it does not establish power-loss durability.

On macOS, Doctor reports generated service environment values surrounded by literal double quotes. Interactive openclaw doctor can back up the private env file and remove one outer quote pair after confirmation; unrelated bytes stay unchanged. Quotes can be intentional, so unattended Doctor and doctor --fix --yes only report this finding. Restart the affected gateway or node service after repair, and correct inherited shell values before reinstalling. This recovery requires the candidate Doctor; the service writer continues to preserve input values.

Managed systemd Gateway activation also covers packages replaced outside openclaw update. Before ordinary startup admission, the native service reader must identify this process as the running unit's MainPID. Only older database schemas trigger Doctor's exclusive maintenance, verified pre-migration backups, and forward migration owners. The activation adapter does not control services or run the full Doctor health-repair flow on normal restarts. Unverifiable, foreign-owned, and newer state retains its refusal and recovery guidance.

Durable background exec adds an optional, first-use durable_background_processes table through the existing shared-state worker and schema owner. The candidate contains this addition; the installed updater needs no new protocol. Existing databases keep their schema version and records, and startup reads do not create the table. Candidate startup re-adopts retained user units without restarting their commands. Rollback binaries leave the additive table and systemd units alone; inspect and stop those units with the systemd user manager before returning to a binary without durable-process support.

Linux managed updates run in a separate user service and slice, so an agent exec's descendant cleanup, Gateway restarts, and the Gateway unit's memory limit do not own the handoff. If its recorded helper and updater die, update status or startup reconciliation records handoff-terminated with the last phase. An owned npm stage that never reached activation is removed after checking for surviving work; uncertain cleanup leaves a warning and retains the stage. Activation recovery and backups remain with their existing recovery owners. These changes must be present in the installed updater; a newer candidate cannot repair an old launcher.

Candidate Doctor inspects the managed service even after the previous Gateway releases its state lease. On macOS, it unloads a loaded, enabled LaunchAgent between KeepAlive respawns before entering maintenance and records that stop for finalization to restore. Unloaded or disabled services remain stopped. This fix must be present in the candidate; the installed updater does not need it.

If an update driver disappears after the candidate was recorded as installed and serving, reconciliation records success with a driver-loss warning. It preserves plugin warnings and does not invent command exit codes or a current health check. Unverified candidates and recorded failures or recovery keep their failure path. The reconciling candidate must contain this change; it uses observations older updaters already record. A first update from an older release still uses that release's handoff launcher, and previously terminal history is not rewritten.

Managed systemd stops bound the native command by the selected unit's effective stop timeout plus five seconds. Unavailable or infinite policy uses the finite Gateway stop budget with a warning; a command timeout retains its reason code through the existing recovery path. This requires the installed updater to contain the fix. A candidate cannot change an older updater's stop command. Requester notices distinguish restart preparation from update completion. Failed runs describe the failed phase in plain language, retain its reason code, and include the next action. Before activation, a recorded serving observation names the current version still running; after activation, the previous serving version is named only after recorded recovery verifies it. Maintenance refusals remove the known database path before public diagnostic projection so recorded holder details survive redaction and truncation. Claim formats are unchanged.

If an agent database's state lock was removed or replaced, shutdown still releases its native worker and records the lost lock and current holder in a warning. It leaves the replacement lock and unowned lease records alone for recovery; shutdown never treats lost ownership as a clean checkpoint. Failed plugin cleanup keeps the Gateway's process-exit deadline active so a managed update can reach its existing stop-failure recovery instead of waiting indefinitely. These repairs must be present in the old Gateway being stopped, not only in the update candidate.

On Linux, update workers verify their driver's ancestry through kernel procfs identities when the native process helper cannot load, including older-glibc hosts. The candidate worker must contain this fix. The inherited run ID alone never grants continuation: driver liveness, birth identity, and parent birth ordering remain required. If both native inspection and procfs are unavailable, Doctor records ancestry-unverified; restore readable /proc/<pid>/stat or a compatible process helper, wait for the recorded driver to exit, then run openclaw update repair. Doctor reports the native load failure and runtime glibc version when available.

SQLite update backup admission measures database and journal families, reserves the retained backup and writable rollback images, and sizes history scratch from shared state rather than a large agent database. Actual rollback output space is checked again before current databases move. A disk-space refusal retains the required and available capacity and the backup or rollback volume role in the package-swap failure fact without exposing private paths. The candidate worker and installed updater must contain the diagnostic repair; an older updater cannot gain it from a newer candidate alone. If capture refuses before the package changes, final recovery restarts and verifies the previous owned Gateway unless recorded data is at risk.

PostgreSQL update rollback uses a fresh prepared anchor on each attempt. After a prepublication refusal, correcting the reported obstruction allows the same native update restore request to retry without overwriting an earlier recovery preparation. The candidate restore implementation must contain this fix; the supervisor needs no change.

When artifact-preserving SQLite inspection exhausts its stabilization attempts, update failures retain the final consistency reason code and attempt count in openclaw update status and the prepared failure report. The candidate worker must contain this diagnostic change. Snapshot checks and retry limits are unchanged; the reason identifies the failed check, not the writer or underlying cause.

Candidate Doctor preserves same-conversation automation continuations when adopting a stored inference account. It carries forward the original authenticated source only when its old executable revision still matches, then binds that source and existing standing-grant references to the restricted definition. It also records a determinable host-managed account and its explicitly selected Codex runtime; native-owned and model-locked sessions remain unchanged. Stale captures stay stale; runtime authorization, conversation identity and revocation checks remain required. The candidate must contain this repair.

An external supervisor's accepted native update (update migrate, then update finish) is recorded in update history as a succeeded run that started at migration. A later recorded update therefore lets openclaw update cleanup retire rollback originals that earlier migrations left, while the latest update's own originals stay protected. The candidate must contain this change; the supervisor needs none. A failed history write leaves a retry warning in the update finish result. Releases swapped without the native protocol are not recorded.

Background discovery failures are logged and retried at the next scheduled check. Gateway shutdown cancellation stays quiet; unexpected scheduled task failures are reported by the scheduler without restarting the Gateway.

Updates always work (openclaw update finishes best effort everywhere). Changes to update, Doctor, service lifecycle, migrations, plugin loading: state their update behavior. Installed updater runs first, can't be patched; candidate fixes key on markers shipped drivers set; existing operator state = input. Recoverable hiccups → recorded warnings; back up before mutating, let rollback restore it; refuse only for named data risk with previous Gateway kept running. Timeouts and budgets: generous, derived from measured state, sized for slow hardware. Proof: published-driver × candidate cell.

Candidate Doctor imports historical image-project snapshots as non-repository runtime preparation while retaining the original serialized snapshot as evidence. Historical shared-schema-21 placements retain their existing preparation evidence and cleanup custody under current constraints; unsettled worker claims refuse the atomic cutover without advancing either marker. Missing predicate columns are derived from their original JSON before publication. Historical agent-schema-24 recovery envelopes remain archival columns; queued inputs become interrupted before the schema markers advance, never restart replay authority. Both repairs use the existing maintenance transaction and verified backup. Malformed or conflicting image preparation refuses the cutover without discarding its record. The candidate must contain these repairs; the installed updater needs no new protocol. Restore the verified pre-migration database with its matching binary for rollback rather than lowering version markers.

PostgreSQL original-state captures acquire offline custody before using the exact database backup provider. The installed updater must contain this repair.

The pre-migration database backup for PostgreSQL families needs exclusive state ownership, and it runs after activation replaces the install. When ownership is unavailable after the service stop, for example because a Gateway the updater does not manage is still serving, the update now refuses before activation, leaving the install unchanged and the Gateway running. Stop the Gateway through its service owner, then rerun the update. The installed updater must contain this repair. Update-history writes participate in PostgreSQL's generation handoff to Doctor; all other generation checks remain in force. Update status reads history and recovery outcomes through the configured database engine.

The managed update helper owns recovery when its updater exits by signal or without a readable result after either the helper or the updater stopped the Gateway. Both recovery paths use the same update-history evidence of an unfinished stop: the helper's stop step, or a managed handoff followed by the updater's activation phase while the Gateway is currently stopped. The handoff record remains usable after target selection records a package-manager method. Its staged runtime keeps bookkeeping available while the installed package is missing. An untouched publication preparation is retired and the verified original Gateway restored; an interrupted publication completes the recorded candidate, runs post-core repair as the same update's continuation, then restarts and verifies the managed Gateway. A plugin cohort that the killed updater reserved for this update is settled by that continuation before Doctor runs; after a restored original, the original runtime settles it before the Gateway restarts. If that settlement fails, the original Gateway still restarts and update history names openclaw update repair before the next update. The helper never settles a cohort that belongs to another update. Update history records rollback, success with recovery, or an actionable failure. Lost ownership, named data risk, and unverifiable runtime identity still keep the Gateway stopped. The helper that starts the update must contain this change; staging a newer candidate cannot repair an older helper.

During overlapping Gateway restarts, config recovery reads health facts through the same isolated read-only transaction used for startup plugin metadata while the previous database owner is verified alive. It avoids copying unrelated shared state. Offline recovery, retained snapshots, and schema maintenance keep their private snapshot path; config repair still completes before admission.

Update inspection and snapshot workers bind plugin metadata discovery to the selected installation's state directory, including requests from older installed updaters. A different profile's database version must not block that inspection. The candidate worker must contain this repair; an older updater inspecting with its own worker still needs an updated runtime.

Private Doctor and post-core workers validate command fields before entering maintenance. The delegated executor admits its grant data separately and still checks live process and installation ownership before effects. Callbacks and live deadline objects stay in the initiating process; only serializable options cross the migrated-update handoff.

Native openclaw update migrate reports progress while inspecting configuration and schemas, capturing its database backup, and verifying the migrated schemas. Update Doctor omits the standalone pre-shutdown transcript archive warmup because the updater already owns the stopped-Gateway window. Required archive migrations and their integrity and recovery checks still run under maintenance custody. The candidate must contain this change; older installed updater work is unchanged.

Native migration records the advisory checks selected by candidate Doctor in its existing recovery receipt. After the supervisor accepts the serving Gateway, openclaw update finish runs those selected doctor --lint checks and records findings in update history. If readiness, inspection, or history recording fails, the update stays accepted and the pending checks remain retryable with openclaw update finish; the result reports the next action. Migration admission, repairs, backup verification, and recovery fences still complete before startup.

Cold transcript navigation backfill uses about ten minutes of archive work per Doctor invocation, finishing the current archive transaction before stopping. Doctor and the native update receipt report migrated and pending archive counts; pending navigation is a recoverable warning, so it does not fail or roll back the update. openclaw update finish retains the warning in update history. Every later native update runs candidate Doctor again even when database schemas are already current, and resumes the remaining archives. Operators can also run openclaw doctor --fix; pending archives retain their existing cold-restore path.

During a native update, when plugins are unchanged and only deferred model retirement remains, a supporting candidate completes the second Doctor pass with the required config, auth, session, and cron repairs and final validation. Startup, database admission, and config preparation still run in full. Other pending work or incomplete discovery selects the full Doctor flow; older candidates and standalone openclaw update repair continue using the full pass.

When that second pass widens, its diagnostics name the first config eligibility check or retained contribution that required the full flow. These names contain no config values. Gateway verification timing ends at readiness; separate timing steps cover post-ready maintenance, plugin commit, and recovery-artifact cleanup. The candidate supplies Doctor diagnostics, while the installed updater must contain the timing changes.

Stopped update and Doctor database snapshots tolerate concurrent read-only SQLite probes. The transient -shm WAL index is rebuilt privately, never copied or used to detect durable changes. Empty WAL files created by readers count as absent. Changes to the main database, WAL data, or rollback journal still refuse the stopped backup and identify the changed file. This repair must be present in the runtime performing the snapshot, including the candidate worker when the installed updater delegates capture to it.

For checkpointed databases under stopped-update custody, backup identifies the database engine from the retained backup image instead of acquiring a second whole-store image for classification. WAL and rollback-journal captures retain their pre-capture engine inspection. Backup digests, PostgreSQL exports, and source-change refusal still apply. The candidate backup worker must contain this change.

Candidate Doctor also accepts an empty WAL index appearing or disappearing between an older updater's capture and migration admission, provided the database identity and committed contents still match and the index contains no write evidence. This preserves the installed updater's original fingerprint format. Changed committed data or write evidence still refuses migration and automatic restoration. The candidate must contain this repair.

The post-plugin Doctor runs for plugin changes, deferred model retirement, and pending deferred plugin migrations. Before each Doctor, the updater observes its own state database after ledger writes; Doctor then publishes the settled postimage of captured SQLite databases it opened. These receipts keep automatic rollback bound to the update's database generations. As with native Doctor close receipts, raw non-OpenClaw writes during the update window can be absorbed for those databases. Changes to untouched captured databases still block automatic restoration. Both the installed updater and candidate Doctor must contain this repair; a fixed candidate cannot repair an older updater's missing attribution.

When only model retirement remains after plugin convergence, Doctor can use its existing narrow contribution pass. Settling a plugin migration, including a successful state migration, permits that pass when config inputs and the validated config are unchanged. Actual config or validated-setting changes, plugin changes, unresolved migrations, and new findings still require the full pass. An explicit openclaw doctor continues to run the full pass. This correction must be in the candidate Doctor; the installed updater must already support retirement-only requests. Older updaters keep their existing full-pass selection.

Standing advice about a custom Codex executable, enabled Computer Use, or authored native Codex request parameters that Doctor cannot migrate remains visible in Doctor output and update warnings without preventing that narrow pass. Invalid inline command arguments, unfinished repairs, and access-policy warnings still require the full pass, as do redundant service-tier parameters that Doctor can remove. This distinction must be in the candidate Doctor; it does not require another updater change.

When a retirement-only request needs the full pass, the candidate Doctor writes a fixed Retirement-only Doctor widened: reason to stderr for every config blocker, including the specific model-retirement condition and Codex warning source. Updated updaters retain these reasons in step diagnostics and compacted update history. The candidate and installed updater must both contain this diagnostic fix to retain every reason there; older updaters still run the same repairs.

Direct updates from extended-stable 2026.9.33 and 2026.9.34 are supported when the candidate contains the legacy database-generation adapter. Under maintenance custody, candidate Doctor verifies the older updater's entire physical database inventory and derives committed-content generations from the same observation. Migration attribution and final settlement use those committed generations; receipts sent back to the older updater retain its physical fingerprint format. Each Doctor interval verifies its input again. Changed data, intervening commits, replaced files, and tampered backups still refuse automatic restoration. The installed extended-stable updater does not need to contain this repair. The private rehearsal also preserves the source's legacy cron partition identity before migrating the copied state. An unmatched historical partition still needs an explicit Doctor selection.

Within one database-generation observation, update and Doctor workers reuse a verified digest while the file's device, inode, size, and nanosecond birth, modification, and change times remain identical. Each family observation still checks the database, WAL, and rollback journal; private-copy verification and WAL commit checks remain in place. Changed or unavailable identities require hashing again. Reuse ends with that observation and does not cross Doctor invocations. Reuse also requires nanosecond bigint stat fields and modification and change times more than two seconds older than the start of hashing. Recent writes can share a coarse filesystem timestamp even when nanosecond fields are available, so their digests are recomputed. Millisecond-only stats never enable reuse. The runtime performing the observation must contain this change; a newer candidate cannot change an older installed updater's own reads.

Update snapshots and database backups accept a database whose only integrity findings are malformed inverted index reports on canonical, schema-validated agent FTS tables. A Node upgrade that changes SQLite tokenization (for example, SQLite 3.54) produces exactly these findings on an intact database, and the runtime that next admits the copy rebuilds the indexes. The copies keep the original index bytes, so rollback to the previous runtime restores its own index. Unknown FTS definitions and findings mixed with any other damage still refuse the update. The candidate performs the rehearsal snapshot, so this applies from the first update to a candidate with the fix; activation-time backups need the installed updater to contain it.

Memory embedding migrations space maintenance renewals from the completion of each renewal, so slow renewals leave time for conversion work. The candidate must contain this fix; it does not change an older migration already running.

On macOS, reinstall and uninstall reconcile the launchd registration by service label even if its plist was deleted. Reinstall warns when the previous definition is missing; an existing plist and its private environment files remain backed up for rollback if activation fails.

Update-time service reconciliation also removes the historical macOS NODE_EXTRA_CA_CERTS=/etc/ssl/cert.pem setting when the candidate installer retires it. This requires the candidate to contain the repair and the installed updater to delegate service refresh to that candidate. Custom CA bundles at other paths remain preserved, and unknown operator edits still require manual repair.

For existing managed Gateway and node-host services, migration makes a one-time, best-effort copy of eligible operator CA additions into <state directory>/service-ca/<service label>-operator-ca.pem (mode 0600). It reads the installed service's effective CA setting, so its custom trust need not be present in the updater shell. A distinct CA bundle already selected by the service remains preserved when the installer does not explicitly select a different bundle. An explicitly selected distinct bundle takes precedence.

Automatic eligibility is deliberately narrow: the legacy file must retain the complete, byte-identical historical OpenBSD 1.22.2.1 stock prefix (333483 bytes, SHA256 9dae8d76e55cb08991f2b672d58999ea15560d910759c16b544f843bdffbb994), as observed in Apple's sealed macOS 27.0.1 template, followed by appended PEM certificates. Only appended self-signed CA roots with recognized clean native trust results are eligible. Self-signature alone does not establish provenance. Stock keys, known compromised keys and any explicit macOS distrust are excluded, including alternate certificates with the same public key. Native checks include user, administrator and system trust settings and offline Basic X509 evaluation. Other stock revisions, replaced or reordered bundles, intermediate-only additions, unknown native results and unresolvable distrust require manual review.

Migration never changes /etc/ssl/cert.pem or overwrites a conflicting operator file. The CLI reports successful, unnecessary, ambiguous or failed migration, including partial migration where some additions cannot be established as eligible. Ambiguity, unavailable provenance or a write failure does not block the update: the obsolete override remains retired, and dependent private HTTPS or WSS connections may stop working. Review the guidance before relying on automatic recovery. Previously working connections that require compromised keys intentionally remain rejected.

After migration, rotate legitimate private CAs in the maintained bundle and restart the service. OpenClaw does not synchronize future changes from the retired file or continuously rescreen this operator-owned bundle against OS trust changes. For manual recovery, create a distinct maintained PEM bundle, select its absolute path with NODE_EXTRA_CA_CERTS, then run openclaw gateway install --force or openclaw node install --force from that environment. Never restore the entire obsolete stock bundle or disable certificate verification to recover connectivity.

When reconciliation replaces the service's Node executable, its leading runtime directory in PATH can move to the selected Node directory. Every other existing PATH entry must remain in order; this does not discard custom directories.

When an updater stops a macOS LaunchAgent, it waits for both launchd's process and the verified serving Gateway child to exit before continuing. An unloaded job or a closed listener does not prove that the child has released its agent databases. Pending process cleanup produces a warning and shares the existing bounded stop deadline; other processes using the state still receive Doctor's maintenance refusal. The updater performing the stop must contain this fix.

Candidate state workers drop advisory progress when stderr is temporarily full. Dropped writes do not consume the legacy progress budget, so reporting resumes when the pipe becomes writable. The worker must contain this repair; it does not change an older worker that is already running.

Package verification checks file hashes, sizes, and required executability. When a non-executable dist file gains execute bits, verification continues with one warning listing the affected file count, provided it has no group/world write or setuid/setgid/sticky bits. Other permission differences retain their existing behavior, including owner-only recovery modes. File permissions are left unchanged. Missing required executability, changed content, and unsafe file types still fail verification. The installed updater must contain this fix; a newer candidate cannot change an older updater's package verification.

Content-inventory diagnostics distinguish malformed metadata, content mismatches, and executable-permission mismatches in local errors and prepared public reports. They identify the failed check, not the underlying cause or affected file. Public reports still omit private paths and hash values. The installed updater must contain this diagnostic change; older updaters and recorded generic errors keep their original diagnostics.

Supervisor-managed migrations also validate Doctor's repairable projection before rejecting retired config fields such as agents.defaults.heartbeat. They preserve the original config and database backups before Doctor migrates the state and converts heartbeats to Automations. Unknown keys and invalid heartbeat settings still refuse admission. Repeating the migration preserves the converted jobs and does not repeat the heartbeat delivery notice.

Before replacing a Git checkout's build or an installed package, the updater retains its running runtime. Late module imports and background workers keep using that generation through finalization, rollback, and CLI cleanup, even when the new build has different chunk filenames. The new Gateway starts from the activated build.

This retention covers Node and Bun late imports, including CommonJS dependencies and JSON. Module state already loaded by the updater stays shared through cleanup; imports outside that retained generation continue using the active installation.

Source updates qualify the installed pnpm launcher outside the checkout so even its version probe cannot rewrite the checkout's lockfile. If another version is needed, the updater uses a temporary Corepack shim or npm-installed pnpm matching the checkout's pin. This requires the installed updater to contain the fix; staging a newer candidate does not change an older updater's initial probe.

Candidate pnpm installs use a project-local virtual dependency graph while reusing the configured package store. This also applies when pnpm uses hoisted links: pnpm 12 can otherwise materialize unpatched package bytes from a global graph despite recording a patch hash. After source exposure changes dependency topology, the updater refreshes bundled plugin links before final candidate validation. The refresh links the packages it finds in each plugin's node_modules. A link whose target is missing produces a warning and is skipped when the plugin declares that package optional; any other broken link or filesystem error stops preflight. The refresh does not check for dependencies that were never installed. These preparation changes require the installed updater to contain the fix; staging a newer candidate cannot change an older updater's initial install.

Native pnpm package swaps preserve platform-filtered optional dependencies as absent. On Windows, a dangling link declared in its owner's optionalDependencies is removed from the staged copy instead of failing activation; missing required dependencies and other filesystem errors still fail. This requires the installed updater to contain the repair. A failed swap before any installation or service mutation records the previous Gateway observation without restart verification, including with --no-restart.

Source candidates bound the native declaration compiler with the shared Go runtime policy used by local checks. Node's heap limit does not cover that compiler. Explicit GOMEMLIMIT, GOGC, and GOMAXPROCS tuning remains in effect.

Managed update helpers route diagnostic logs to stderr so debug logging cannot interrupt their control handshake. This applies to the installed updater; a newer candidate cannot change an older updater's pre-activation handshake.

If native service inspection becomes unavailable after admission, the updater refuses activation before stopping the Gateway or replacing its package. When inspection is unavailable initially, a live or unverified Gateway state owner also blocks package replacement, even if the process title no longer contains its installation path. The refusal leaves the installation unchanged and names the service inspection and stop commands to use before retrying.

Before stopping a managed Gateway, the updater waits up to 30 seconds for foreign SQLite maintenance to finish. If it remains busy, activation is deferred and the Gateway stays running. Recovery checks after shutdown use the same bounded wait; if maintenance still does not finish, the existing rollback path restores the previous build. The refusal names the maintenance process and tells you to let it finish before retrying openclaw update. An explicit update timeout and cancellation still bound these waits; live ownership and recovery checks remain required before activation.

The updater retains its admitted SQLite writer wait allowance through finalization, including candidate handoff and standalone repair. A writer that outlasts SQLite's ordinary wait can finish before required recovery evidence and the final outcome are recorded. Optional history bookkeeping still uses its short wait and warns without stopping the update. This applies to the installed updater; the candidate also preserves the step allowance passed by older installed updaters.

openclaw update status reports confirmed driver loss without changing the recorded run, and names openclaw update repair as the next action. Repair or the next update's admission can record the failed outcome without waiting for the inactivity grace period. Live or unverifiable drivers and retained recovery continue to preserve their ownership.

If an explicit update timeout expires during preparation, the original updater records a failed outcome after its child work settles, while it still owns bookkeeping. Expiration during activation, unresolved child work, or lost ownership retains recovery custody instead. A timeout does not authorize a new process to take over an unresolved update.

When both the managed-update helper and updater are proven dead, explicit openclaw update repair can reclaim their handoff immediately; unknown custody keeps the 45-minute (or longer recorded) grace. The descendant census still refuses live or unverified work. After finalization succeeds, repair starts and verifies the managed Gateway only when update history records that the helper or updater stopped it without a subsequent start, running observation, completed managed restart, or settled run. Both recovery owners use this same decision. A Gateway stopped by its operator stays stopped. A recorded named data risk prevents automatic startup. The repairing CLI must contain this fix; older managed-service activation records can establish the stop without a new stop-time receipt.

Explicit repair also settles version-2 triage/repair leases left in closing after their owners die, even without recovery metadata. Native triage still requires proof that its systemd scope is closed. Repair warns when reclaiming a lease; if an owner, descendant, or scope remains live or unverified, it fails with the retained lease's owner, version, phase, last activity, and recovery guidance. The repairing CLI must contain this fix; a downloaded update candidate cannot repair an older updater's blocked admission.

A successful foreground update hands completion to the replacement Gateway. Automatic history reconciliation preserves that handoff while startup verifies the running build. If the replacement never starts, openclaw update repair can recover the abandoned handoff explicitly.

Handoff repair uses recorded boot sessions and process creation times to exclude prior-boot families and unrelated processes with reused parent PIDs. On Windows, a legacy handoff without a boot identity also qualifies as prior-boot when its durable write is more than five minutes before the current boot started. Unverified descendants and incomplete process censuses block settlement to prevent overlapping updaters. Positive handoff descendants, OpenClaw identities, and retained-runtime path holders also block repair. This does not relax Doctor's artifact-custody checks or remove retained recovery data.

Authenticated readiness probes recheck the update's live ownership before opening their transport and sending RPC frames, including deferred authentication and startup retries. Losing ownership stops those probes.

If the retained verifier cannot authenticate to the restarted Gateway, it stops retrying that rejection. Local HTTP readiness and runtime version/build identity can verify activation instead, with an RPC authentication warning recorded in the update result. This does not change Gateway authentication or pairing. The retained verifier runs the previous package, so an update that changes the Gateway protocol version, in either direction, gets the same HTTP identity check with an RPC protocol warning instead of waiting for an RPC handshake that cannot succeed. When readiness never settles, the recorded timeout names both the read the budget interrupted and the last health probe error, such as an RPC rejection.

Channel outages are warnings once the expected Gateway build is running and its core readiness is verified. Detailed /readyz responses report coreReady separately while preserving HTTP 503, ready: false, and failing channel names. Update history retains those channel and HTTP facts. Startup, state and agent database admission, child-runtime, and plugin-replacement failures still prevent core readiness; an older HTTP 503 without explicit core proof remains unverified. Run openclaw channels status --probe to investigate channel warnings. This requires the repaired installed updater; a new candidate cannot change the checks of an updater already running.

Before post-core plugin work, the updater releases its temporary Doctor database ownership before rechecking profile-backed requester authority. Service custody remains with the updater; the next Doctor acquires its own database ownership. This avoids refusing the updater's own policy reads during its maintenance window.

Plugin lifecycle work in update finalization and repair renews its lease from a worker, so a blocked main thread cannot expire the lease. Native Doctor and plugin install/update operations share this renewal behavior. Ownership checks, cancellation, and release still apply. The runtime holding the lease must contain this fix; a newer candidate cannot change an already-running lease owner.

When standalone Doctor stops its managed Gateway, it reserves Gateway restoration before releasing database maintenance. CLI schema preparation waits while Doctor restores and verifies the Gateway; Gateway bootstrap keeps its normal ownership checks. Doctor and competing CLI processes must contain this repair. Already-running older processes cannot observe the reservation.

Candidate-side predecessor shutdown retains its durable recovery receipt inside Doctor's original database-write capture. The ledger writer includes its own native connection close before publishing that write; the following Doctor rechecks the database before reacquiring native custody. Unrelated writes before or after the receipt still refuse migration rather than becoming a new baseline. A completed stop keeps its recovery receipt even when that refusal prevents Doctor from continuing. A loaded supervised service between crashed processes still goes through native service-ownership inspection, even without a live lease. This is candidate-side behavior; it does not change an already-running older updater.

After a Doctor child settles, the updater drains its retained handles for the affected shared-state database and revokes their schema admission, even when Doctor exits unsuccessfully. The next parent access admits the resulting schema again and refuses a version newer than the running updater supports.

Before Doctor admits the installed updater's database capture, plugin rollback journal discovery preserves the original SQLite WAL/SHM family. Older updaters can then verify their physical fingerprints without a false source-change refusal.

Plugin rollback reservation acquires its lease against the existing shared-state schema, then database capture records the settled reservation writes. Credential migration remains owned by candidate Doctor's backed-up maintenance. Starting or restarting an unchanged service does not require migrating runtime-pin metadata; definition rewrites still preserve existing runtime intent. Failed split-install activation also keeps recovery results valid when restoring the original service is unverified. These fixes must be in the installed updater; downloading a candidate cannot change the older driver's reservation or reporting.

After Doctor backs up and admits shared-state maintenance reads, native Codex assignment detection reads one database transaction snapshot. Lease renewals and other maintenance writes can continue without requiring the database files to stop changing for a private copy. Inspection without that admission still uses an artifact-preserving copy and refuses an inconsistent source. This is candidate-side behavior; the installed updater runs first with its shipped checks.

During update finalization, disposable plugin source copies and private SQLite inspection snapshots use the candidate helper's absolute TMPDIR (including when an older installed updater starts that helper). Normal Gateway cache placement is unchanged. Installed plugin projects, retained native admissions, and recovery or migration backups remain with their existing durable owners; TMPDIR does not relocate those writes or remove the need for free space on the installation and state filesystems.

Plugin source capture repairs stale dependency links without changing real dependency directories. POSIX replacements are staged before publication; Windows removes only the junction or symlink before recreating and verifying it. A failed link leaves that plugin unprepared with a named error. Doctor retains its pending migration obligation while other plugins' migrations continue. This repair applies when the candidate loads plugin contracts during Doctor.

Migration integrity checks

SQLite upgrades default to a whole-database quick_check, a full integrity_check of the tables the migration rewrites or re-indexes, and the existing foreign-key checks. This avoids checking every unrelated index against its table during a routine upgrade. Structural corruption anywhere in the database and corruption in the migration's affected tables still refuse the migration; quarantine and rollback behavior are unchanged. Historical upgrades use the same default even when recovery requires a full-file backup. Automatic original-state captures and disposable update rehearsals also honor the requested check, including same-version Doctor repairs. Automatic rollback images, restore validation, explicit Doctor recovery, and legacy transformed recovery archives retain full integrity checks.

To request full integrity checking across every table and index during migration:

openclaw update --full-integrity-checkopenclaw doctor --fix --full-integrity-check

The default can miss an index/table mismatch in an untouched table. Use the full check when you need that coverage; it can take considerably longer on large databases. A successful quick check is never recorded as a full verification. Ordinary post-migration Doctor/update opens with no seal use bounded admission when the agent schema is current and there is no corruption evidence. They retain that file-bound admission across same-process reopens, including an incomplete checkpoint, without claiming a full verification or publishing a seal. The next Gateway startup runs full integrity and foreign-key verification in the background; readiness does not wait for it. Proven corruption revokes admission. Required index repairs, rejected proof, crash recovery, revoked validation, and explicit FULL policy retain their required checks. Whole-file checks required by synchronous agent openers run in the integrity child. Pending migrations still require their scoped pre-mutation checks, and update canaries retain foreground verification. The flag selects migration checks; it does not turn an already-current database into a separate verification job. Explicit database verification, backup verification, Doctor recovery, and compaction retain their existing checks.

The installed updater runs first. Its own captures and checks keep their shipped behavior; the more efficient default begins when the candidate runs its migrations. An older installed CLI does not recognize the new flag. For that first upgrade, update normally to receive the candidate's new default, or run the candidate's doctor --fix --full-integrity-check through your manual upgrade workflow.

Post-activation schema verification preserves agent databases Doctor holds after deletion. These stores may keep an older schema without failing the update; Doctor's held-store warning remains visible. Configured agents required by the Gateway must still pass runtime admission: Doctor fails if a recovery hold leaves a required store unusable. Active databases and pending deletions require the candidate schema, and held stores remain part of rollback verification. Retained plugin databases, including plugin shared-state stores, are not checked against the agent schema. Their plugin owns migration; they remain in the snapshot and rollback inventory even when the plugin is disabled. The primary shared-state database is checked against the shared-state schema.

The local client credential cutover preserves private identities and cached tokens in client/credentials.sqlite, separate from shared Gateway state. The preparatory release does not create that file. Earlier SQLite drivers capture the shared credential tables before the cutover and restore them on automatic rollback; the old version ignores the remaining local file. Credentials issued between upgrade and rollback are lost, and those clients must pair again. A later upgrade rebuilds that stale local file from restored shared state instead of merging it. PostgreSQL installations use an engine-aware driver with local-family capture support, so rollback restores the shared and local stores together. See credential migration and recovery.

Updates started by 2026.10.4 keep the client credential store's independent schema out of the older updater's agent-schema check. Credential-aware updaters verify that store against its own schema, and both paths retain its backup and recovery coverage.

Independent native credential sources remain unchanged during import and remain readable by the previous app after rollback. Reusing the same source preserves local refreshes; a changed or restored source rebuilds its local copy while retaining consumed legacy-JSON claims.

OpenClaw.app runs plugin convergence through the selected runtime's Doctor while the app owns Gateway activation. This aligns managed official npm plugins with the new core before plugin migrations, repairs host peer links, and refreshes the plugin registry. Unavailable replacements remain nonblocking: the app's recovery diagnostics include the remaining version or peer-link warning and the exact repair command. Retry Gateway setup in the app to repeat this owned repair.

Retired tenant-container management

The experimental openclaw fleet command has been removed. Updating the host CLI leaves existing tenant containers, networks, mounted data, and registry records untouched; it does not update their container images.

Before updating, back up each tenant and record its container identity, runtime, image, ports, mounts, resource limits, and environment. Protect that record as credentials: container environments can contain Gateway tokens. Transfer lifecycle, image updates, backups, and cleanup to your Docker or Podman deployment tooling. Verify each tenant through its existing endpoint before retiring recovery copies or removing resources. Keep separate state and credentials for each trust boundary.

See container image updates, backups, and the downgrade limitation before changing images or restoring an older OpenClaw version.

Upgrading very old versions

Current Doctor can migrate pre-July cron jobs, Voice Wake settings, conversation bindings, and OAuth credentials directly. It archives obsolete delivery queues, plugin indexes, sandbox registries, and runtime notifications, preserving original bytes and reporting recovery instructions. Run openclaw doctor --fix; these JSON formats do not require an intermediate release. See Doctor state migrations.

The following bridge instructions apply to other retired formats and config keys.

For installations older than July 2026, upgrade to 2026.9.5 first, run its Doctor migrations, and then upgrade to latest. The bridge release still imports the old tasks/runs.sqlite, flows/registry.sqlite, and plugin-state/state.sqlite databases and pre-June plugin JSON state, repairs retired agent and channel config keys, and includes the old runtime aliases. The retired plugin imports cover Telegram, iMessage, Active Memory, Nostr, and Microsoft Teams; see legacy state migration. Current releases leave those retired state files untouched. If you already installed the latest version, Doctor stops before rewriting config that still contains these retired keys and directs you through the same bridge.

The retired same-file memory index (meta, files, and chunks) is also refused before current tables are created. Preserve the original state and configuration, then use 2026.9.7 to migrate a compatible copy of that index before retrying. Unrelated tables with these generic names remain untouched.

If a newer release has already upgraded your SQLite databases, use a compatible pre-update backup for the bridge. Older releases cannot open newer database schemas; follow downgrade recovery before running either bridge release against that state.

Back up the state first and use a supported Node version: Node 24.16.0+ on the 24.x line, or Node 26.1.0+. Node 24.22.1+/26.12.1+ is strongly recommended for security; older compatible releases warn without blocking the update. Keep the same owning account, installation prefix, profile, and state/configuration paths throughout.

For an npm installation with an OpenClaw-managed Gateway service, run this first stage from a terminal:

openclaw gateway stop &&  npm install -g [email protected] --allow-scripts=openclaw &&  openclaw --version &&  openclaw doctor --fix

Confirm that the version output is 2026.9.5 and that Doctor imported the old task, flow, plugin, and channel state you need. Resolve any failed or conflicting imports before continuing. Doctor imports channel state only for enabled channels and accounts. If needed, temporarily enable those channels while the Gateway is stopped, rerun the bridge Doctor, then restore their previous enabled settings. Install the affected plugins before running their migrations. Then install the current release with the manual update procedure. The Gateway is already stopped, and the backup above covers its first step.

The npm command above is for npm 12 or npm 11.16+; on npm 11.15 and earlier, omit --allow-scripts=openclaw. For a pnpm-owned installation, replace the bridge install command with pnpm add -g --allow-build=openclaw [email protected]. For Bun, use bun add -g --trust [email protected]. Keep any normal --profile selector on every openclaw command. For a custom service or foreground Gateway, stop and start it through its actual owner instead of the managed-service commands above.

Recommended: openclaw update

Detects your install type (npm, pnpm, Bun, or git), checks the new version while the old Gateway serves, then activates and verifies the update.

Use openclaw update for a managed Gateway so the updater coordinates the package and the service definition. To update the service's existing installation in place, run the CLI from the install root shown by openclaw gateway status. Writable Node services can instead move to the invoking CLI's updated installation, as described below; externally managed installations retain their deployment owner.

A bare npm install -g openclaw@<version> uses the global prefix of the Node/npm selected by your shell. Switching Node versions can install a second OpenClaw without changing the service's entrypoint. openclaw --version then reports only the shell's CLI version. Check openclaw status, openclaw doctor, or openclaw gateway status for both install roots and versions, then run openclaw update or use the CLI from the service's install root. Changing only the Node executable in a service definition does not update its OpenClaw package.

openclaw update

Starting with the release that adds candidate-owned admission, package updates privately stage the target and let its code judge configuration, database schema, Node requirements, and plugin availability before activation. Later releases can therefore correct these admission decisions for users already on a supporting updater. The installed updater retains managed-service ownership and ancestry checks and every mutation. Older installed updaters keep their pre-staging refusals; a newer candidate cannot repair that first hop. Targets without the capability marker fall back to installed checks, as do --admission installed and --dry-run (which never stages a package). Admission selection is CLI-only: --admission auto is the default, and there is no environment-variable override.

Windows candidates accept lease identities from the 2026.9.6 updater even when NTFS file IDs exceed JavaScript's exact numeric range. After validating the handoff, the candidate retains exact file and parent-directory identities; later replacement still stops the update. Lease read failures report their underlying cause instead of a parent-binding mismatch.

Service backups and interrupted agent cleanup also retain exact file identities. Older rounded receipts remain readable and upgrade after verification on their next write.

Post-install Doctor also accepts older updaters, including 2026.8.2, that do not provide an update run ID. Its commands retain invocation-specific custody without requiring an environment-variable workaround.

Doctor keeps a command's captured birth identity through native custody binding. If a command finishes before that identity can be captured, its original spawning owner still joins the command and confirms its process group has exited before releasing the reservation. A live or unreadable command remains protected.

When the installed 2026.9.2 updater runs the candidate's early Doctor check, shared-state and agent schema changes are rehearsed on private copies. Plugin inspection cannot publish native admission metadata to live state during this check. A refused rehearsal leaves live database schemas unchanged for package rollback; successful checks defer migration to the fresh post-core updater.

Managed-service inspection is best effort. If the service manager is unavailable, including Linux hosts without systemd, the update continues and records a warning. It leaves unverified service definitions unchanged and skips their automatic restart. Restart the Gateway you launched manually after the update, or use its actual supervisor. Doctor still checks for active state writers before migrations.

Git updates also check persisted Gateway ownership before replacing checkout or runtime files. When native service discovery misses a live or unverifiable owner, the update continues with a warning in the terminal, JSON result, and update history. The warning names the PID and installation root when known: the Gateway keeps running the previous runtime and may fail to load lazily loaded chunks until restarted. A Gateway that detects replacement of its runtime may stop itself and require relaunch. Restart it through its actual service manager, or press Ctrl+C in its original terminal and rerun its Gateway command. Positively identified disjoint installations stay silent. Existing managed-service and database-capture refusals still apply. The installed update driver must contain this warning behavior; a newer candidate cannot change an older driver's publication behavior.

On Linux, unmask a managed systemd unit before updating. A masked unit (masked or masked-runtime), RefuseManualStart=yes, or a disabled and inactive unit with no start path causes preflight to refuse before replacing files or running migrations. For the default user service:

systemctl --user unmask openclaw-gateway.serviceopenclaw update

Use the unit and scope reported by openclaw gateway status --deep for a custom profile or system service. If an operator applies a mask or another start restriction during the update, OpenClaw retains the activated candidate and reports a service-definition warning instead of rolling back because systemd refused to start it. Gateway readiness is still unverified; remove the reported restriction, run openclaw gateway start, then check openclaw gateway status --deep. These checks belong to the installed updater; unmask before updating from an older release too. See Linux maintenance holds.

Service membership uses the running Gateway's process ancestry and native supervisor facts. An external terminal that inherited service environment markers can still update after native membership is verified as external. Reparented children remain inside when they share the Gateway's macOS process group or launchd job, or its systemd unit cgroup. On macOS, verified external launchd membership is sufficient even when a root-owned login process prevents a complete ancestry walk, including in integrated terminals. An already-current core update never refuses for service membership. When membership cannot be verified as external, it completes with already-current and a warning that plugin, runtime, and service maintenance was deferred, before that maintenance can change files or stop the Gateway. An explicit channel change is also left unapplied and named in the warning so it can be retried. Real updates retain the containment checks. Present but unreadable native membership refuses with service-membership-unverified; confirmed native membership uses inside-gateway-service. Windows currently uses verified ancestry and the inherited-marker fallback because job-object membership is not available to the runtime. A genuine Gateway descendant must use the managed update handoff or an independent terminal.

Linux supports both cgroup v2 and the named systemd v1 hierarchy. When readable native observations establish that this host has no service containment tree or launchd job, a complete external ancestry walk and a distinct process group allow the updater to stop, update, and start the managed service itself. The service definition must still belong to this installation. The report and openclaw update status --json record a warning: Service membership unverifiable on this host; using managed stop/update/start.

Permission failures, conflicting, incomplete or malformed observations, and known service members do not use this fallback. Reparented callers in the Gateway's process group remain inside even when there is no native unit tree. When native facts exist but cannot be read, run this sequence from an interactive external shell not started by the Gateway service, under the installation's owning account:

openclaw gateway stop && openclaw update --yes && openclaw gateway start

Stopping the Gateway removes the live containment ambiguity. Keep the same account, profile, and state/configuration paths throughout, and repeat any requested --channel or --tag on the update command. If the update reports an error, follow its recovery guidance before starting the Gateway. With native helper support, openclaw gateway call update.run --params '{}', the Gateway tool's update.run action, and /update can instead perform a managed handoff. Linux transient user handoffs require systemd-run; an emulated manager without it cannot use that route. See Automation and SSH.

Managed-service refusals retain a specific code, such as inside-gateway-process-tree or service-definition-changed, in the failure report and openclaw update status --json. Shared reports preserve that code and recovery guidance while removing private paths and process IDs. These checks run in the installed updater: a new candidate cannot repair an older driver's refusal before package replacement, or recover detail an older report already discarded.

Package-swap reports distinguish package-recovery-permissions-unsafe (recovery artifact permissions or link count) from managed-handoff-lease-identity-changed (a recorded lease database path, file, or parent directory changed). Shared reports retain these closed reason codes while redacting private diagnostics. Other package failures keep the global-install-failed reason. These diagnostics do not change refusal, backup, or rollback behavior and require an updated driver.

Generated failure reports name recognized candidate startup causes, including plugin loading, port conflicts, schema migration, native-module compatibility, readiness timeouts, and process signals. Plugin names appear only when they belong to the shipped public catalog. Config errors retain schema field names and fixed validation kinds; user-defined map keys become <id> and unknown keys become <key>. Arbitrary error text and rejected values stay out of public reports.

Control UI updates use a verified helper to stop and restart the managed Gateway. On macOS, the helper carries its live update ownership into LaunchAgent activation; ordinary commands inside the Gateway still cannot stop their own service. If an older installed updater reports managed-service-stop-failed before activation, the candidate has not replaced that updater. Update from an external terminal using the same installation owner, then retry the Control UI update.

After package replacement, compatibility config reads from older updaters run in a fresh process using the updated package and its dependencies. This also applies to updates driven by 2026.9.4. If an optional read fails, the updater prints candidate-config-read-failed with the reader's error or exit reason and leaves the service definition unchanged. The reader's stderr is not echoed. Reads follow the restored package after a rollback. After the update finishes, inspect the reported problem with the updated CLI, then run openclaw gateway install --force with the same --profile or --dev option as the update to refresh the service definition. Node and Bun readers run only one child per read. An attempted nested reader stops before spawning and records candidate-config-read-recursion. Both runtimes use the same result channel for synchronous and asynchronous reads; config diagnostics stay separate from the result.

Bun-hosted updates from 2026.9.7 can finish candidate Doctor and restart the Gateway after package replacement. Idle candidate workers release their IPC references after native work closes, so a completed Doctor does not leave the installed updater waiting indefinitely for its exit. This fix runs in the updated package; the published updater and its handoff markers are unchanged.

After a native service starts, restart preparation allows its verified process up to the normal startup deadline to replace missing or dead Gateway ownership before signaling it. This avoids an intermittent restart-unhealthy result when an older updater starts the updated service before asking the new installation to restart it. The fix runs in the new installation, so it also applies to the next update from 2026.8.35. Missing ownership after the deadline and unrelated process locks still refuse the restart.

The running Gateway retains its shutdown code before an in-place update can replace the package's bundled files. Transcript shutdown drains captures and persists rule-based notes without starting optional model inference. This protection applies to updates from a release containing the shutdown fix. Older running Gateways, including 2026.9.6, can still fail their first shutdown with ERR_MODULE_NOT_FOUND after package replacement; installing a fixed candidate cannot change code already running in that process. Start the updated Gateway with its installation owner if the old process exits without restarting.

When a writable managed Node Gateway service points at another global installation, the update keeps the active CLI's installation as its target and refreshes the service through gateway install --force before verifying the restarted Gateway. The old service command remains the recovery identity until that handoff succeeds. Reconciliation failures are recorded as warnings with a manual repair command. The code update can report success while service reconciliation remains pending; a stopped service stays stopped until repaired. On Linux, regeneration preserves the order of retained PATH entries and prepends newly added managed entries. Paths carried over solely from the old definition still pass the existing safety filters. If the definition cannot be preserved, reconciliation requires manual repair. Deployment-owned definitions retain their existing installation owner.

An owned managed Bun Gateway at a different package root uses the existing service-root update route: only the Gateway installation advances, and the invoking CLI installation stays unchanged. The updater validates the service's actual Bun executable against the Bun 1.4.4+ and WAL-safe node:sqlite requirements; Bun's emulated Node version is not checked against engines.node. If the updater runs on Node, its Node must also satisfy the target package's engine and SQLite requirements before package replacement, because finalization uses that runtime. Bun-owned package-manager checks and installs use that verified executable, and the existing install/restart path retains the recorded runtime pin. A path under ~/.openclaw alone does not establish Bun package-manager ownership. See Bun-only installs.

Doctor and openclaw update repair do not move a Bun Gateway onto a different CLI installation. A repair invoked from that other installation reports the drift and refuses service maintenance before stopping the Gateway. Run repair from the Gateway's own installation, for example <bun> <service-root>/openclaw.mjs update repair, or use openclaw update to advance its installation in place.

The installed updater runs first. In a Linux split-root fixture, published 2026.9.6 refused early with ENOENT when Bun was absent from PATH, leaving the Gateway and both installations unchanged. With the fork Bun on PATH, that published driver updated the Gateway installation in place and restarted it healthy while leaving the invoking CLI unchanged. The routing and explicit Bun selection described above apply only when the updater driving the update contains this fix. Installing a newer candidate cannot change that first hop.

Pending package-publication recovery in either the CLI or selected service installation is checked before writable preparation. The updater settles eligible lost-lease recovery automatically; other unfinished operations still require the reported recovery command. Doctor does not clear those artifacts.

During an uninterrupted package update, the freshly installed private candidate is checked by directory identity, package version, and launchers instead of repeated full-tree scans. Content changes inside that private candidate during publication are not detected. Its full fingerprint is retained for recovery; resumed publication and repair still verify package contents. This optimization applies when the installed updater contains it; older updaters keep their checks.

pnpm updates use the installation's own pnpm home and bin directory, even when macOS service PATH excludes pnpm or a version manager puts another pnpm first. Both pnpm 10's home-level shim and pnpm 11's bin/ shim are supported, and the child PATH includes both locations. The installed updater must contain this fix; installing a newer candidate cannot repair an older updater's preflight.

Native pnpm updates also relocate pnpm 12 launcher paths before publishing them. After activation, unresolved launcher targets produce a warning with repair guidance without rolling back the updated package. These protections require the installed updater to contain the fix. If an older updater left openclaw pointing into a missing .openclaw-update-native-* directory, reinstall the same version with pnpm add -g --force openclaw@<installed-version> using the same account and global directories to recreate the launcher. Back up first and follow the manual package-manager procedure.

If a pnpm-owned install fails with IO error: not a terminal, the installed updater may be triggering an interactive pnpm build-approval prompt while capturing its output. A newer candidate cannot repair that first update. Follow the manual package-manager procedure, preserving the owning account, prefix, and state/configuration. Back up and stop the Gateway through its actual owner before replacing the package. For the installation step in a POSIX shell, supply noninteractive input:

pnpm add -g --allow-build=openclaw openclaw@VERSION </dev/null

Replace VERSION with a release containing this fix. Then run Doctor and restart through the same owner as described in the manual procedure. Updates driven by the fixed version supply noninteractive input to pnpm themselves. The recovery command permits OpenClaw's own install scripts without approving additional dependencies.

The installed 2026.9.4 updater can refuse with managed-service-preflight before the target code runs. To reach a release containing this repair, use the manual package-manager procedure with the same owning package manager, prefix, and state/configuration. Back up first, stop the Gateway through its actual supervisor or foreground process owner, replace the package, run Doctor, and restart through that same owner. --no-restart cannot repair the old admission check.

Updaters without the admission fix first shipped in 2026.7.2-beta.5, including 2026.6.34–2026.6.35 and the 2026.7.33–2026.7.35 extended-stable line, refuse before staging with plugins.load.paths: plugin path not found when a configured plugin path is missing. Restore the custom plugin directory or remove its configured path, then update. openclaw doctor --fix repairs recognized bundled-path aliases but preserves unrelated custom paths.

Registry package updates inspect the exact target's Node requirement before staging or running package lifecycle scripts. An incompatible Gateway runtime produces preflight-node-runtime-incompatible, with the target version, required engine range, selected Node version, and an upgrade command. The updater prefers the inspected managed service's Node executable. A compatible service Node is retained even when a different Node on PATH cannot run the target. If the service's runtime has changed (for example, a Homebrew symlink now selects another version), an owned, writable service can use a compatible updater or PATH Node when the update will refresh its definition. Refusals name the service and updater runtimes, the PATH executable, and the inspected Gateway installation root. A protected definition or --no-restart still requires its pinned runtime to be compatible; changing the shell's Node alone does not change that service. The updater keeps the requested OpenClaw target and does not select another release automatically. Later runtime capability checks can still produce node-runtime-preflight. This selection repair must be present in the installed updater. A 2026.10.7 driver that refuses before staging cannot obtain it from a newer candidate; use the manual package-manager update once, preserving the installation owner and service account/state selectors. If the managed helper exits before acknowledging startup, the update report includes a bounded, redacted tail of its startup errors. The Gateway keeps serving. This diagnostic capture must be present in the installed updater; a newer candidate cannot repair an older updater's missing startup diagnostics. npm directory permission failures produce global-install-permission-denied, naming the directory, its owner when available, and the next action. Dry-run JSON includes these outcomes in failures; the update report and Doctor's update history retain recorded failures. The serving Gateway stays in place during these preflight checks.

After an external reinstall changes the OpenClaw installation root, such as installing a newer Node version with nvm, mise, or Homebrew and reinstalling OpenClaw, Gateway startup repairs managed plugin host links before checking plugin availability. Stale or dangling links are rebound to the current installation, with a warning showing the old and new targets. Developer-owned path installs and links outside the plugin system's owned locations are left unchanged. If filesystem permissions prevent repair, startup reports the affected plugin and keeps it unavailable until the links can be repaired with openclaw doctor --fix.

System-package ownership inspection treats missing package-manager executables as inapplicable without warning. Unavailable backend results are reused across update phases of one update run and command search path; other query failures warn once per run. The next update always probes again, including in a long-lived Gateway. Successful inventories stay fresh before installation effects to protect files claimed by a system package manager. This behavior requires the updated updater.

Directory permission checks remain in the installed updater. Older updaters cannot gain new admission behavior from the candidate they have not staged yet. If upgrading from an older release, check Node requirements and the npm prefix's permissions first; see update troubleshooting.

An already-installed registry package version or Git target SHA still runs plugin maintenance, repairs eligible old OpenClaw release pins, and restarts a running managed Gateway when plugins change or its service points at another installation, unless --no-restart is set. Unchanged runs finish as skipped / already-current.

Plugin maintenance does not fail an otherwise successful core update. If a plugin cannot be updated, OpenClaw continues with the remaining plugins, keeps the previous installation where possible, and prints a short next action. A running updated Gateway can also report a plugin that did not load without turning the core update into a failure. Individual plugin outcomes remain available in --json output. When ClawHub has not published a version-matched official runtime plugin, the updater tries its declared trusted npm source for that same version, honoring catalog pins. Security and integrity refusals do not permit a source fallback. If neither source can serve the release, a compatible working installation stays in place with a version-skew warning and an openclaw plugins update <id> retry instruction.

Unfinished plugin migrations retain their settings and state inputs while plugins install, plugins update, doctor --fix, and update repair repair the package. A verified replacement can be installed before its remaining data migration completes; pending migration still guards runtime activation. Explicit config unset plugins.entries.<id> can remove that entry, with the normal config backup preserved. Removing the entry does not settle its pending data migration.

Failures to install core, repair required configuration or state, or start the updated Gateway remain update failures, except for the service-definition refusals described above. Local copies selected through plugins.load.paths are operator-managed. Updates and openclaw update repair retain the selected copy and any npm install it shadows, and record a plugin-operator-managed warning in the outcome and update history. Verify that copy against the updated OpenClaw version, or remove its path from plugins.load.paths to use the managed installation again. This does not grant the local copy trusted plugin privileges. An explicit package artifact (for example, a tarball path or URL) is validated and installed even when its version matches; matching versions do not prove that two artifacts contain the same code. An explicit --channel choice still becomes the saved update channel. For versions that support checks before installation, health checks, config and plugin planning, and a test Gateway boot on copied state finish before the service stops. The stopped interval contains the swap, required migrations, plugin downloads and convergence, and service start. Plugin work uses the installed target without requiring a serving Gateway. Changed plugins, pending plugin migrations, or deferred model retirement run fresh Doctor repairs before restart; required repair failures still block startup. After the candidate takes ownership of finalization, optional diagnostics with complete lint coverage can run after verified readiness. Their warnings and retry commands remain in the update report while the Gateway serves. Missing diagnostic selectors cause the checks to run before startup instead. If post-plugin lint execution cannot finish because of lock contention, a timeout, or an inspection failure, the verified core update continues with a recorded warning and the original lint diagnostics. Run openclaw update repair to retry those checks, stopping the Gateway first when the repair asks for exclusive state access. Concrete readiness findings and unverified process cleanup still block completion. The final report records downtime through convergence and final verification, plus verification results. See Validation and activation for the checks.

Post-update configuration and settlement reads wait for temporary SQLite maintenance custody within the existing update allowance. If that wait expires, contention alone preserves automatic Gateway recovery; an actual data-at-risk refusal still blocks recovery. Doctor publishes its completion result only after its maintenance resources have been released.

Gateway process respawn and launchd restart scheduling respect active offline maintenance ownership. During Doctor restoration, a busy port still refuses an unverified listener, but the preserved LaunchAgent is reloaded so launchd can retry after that listener exits. This requires the Gateway and restoring CLI to contain the fix; an already scheduled restart helper is not cancelled by it.

Source updates also admit build-artifact ownership and runtime staging access in the installed checkout before stopping the Gateway. A retained .artifacts/dist-artifacts.lock refuses the update with the recorded owner, timestamp, and exact recovery command while the serving Gateway stays running. Verify that all associated build/check processes, including detached descendants, have stopped before releasing that lock; a dead owner PID alone is insufficient. The updater keeps that ownership until its work has settled and carries the prepared runtime result into completion. Already-current repairs reuse the admitted ownership; promoted runtime outputs do not need regeneration. Published updaters that pass the source build-cache location, including 2026.9.6, also receive the installed-checkout check during candidate builds.

Git updates support a .artifacts directory redirected by a symlink, including to another volume. Database snapshots use its physical directory so the backup's parent-directory durability check can complete. The installed updater must contain this fix; a newer candidate cannot repair an older updater's capture.

The canary uses a temporary loopback Gateway port and suppresses background listeners, including the MCP Apps sandbox, browser control, and channel services. This lets validation run while the serving Gateway keeps its configured ports. Doctor and policy checks use the copied deployment settings, so an accepted policy attestation remains valid for an unchanged deployment. Only after these checks finish does the canary apply its temporary token, disable Tailscale and Control UI, and suppress background services for Gateway startup. Genuine policy drift still fails validation; no attestation pin is changed or skipped. The updater running the rehearsal must contain this fix; a newer candidate cannot undo configuration overrides already applied by an older updater. Doctor omits the onboarding URL warning derived from that temporary loopback binding during rehearsal; other findings remain visible. The activated Gateway retains your normal listener settings. Candidate startup progress is emitted only when the driving updater announces support, so older updaters, including 2026.9.5 and 2026.9.6, retain actual startup errors instead of mistaking a progress marker for the failure reason. While waiting for canary HTTP readiness, the updater observes live update authority about once per second. Cancellation, process exit, and startup deadlines remain checked at every poll. Authority is checked again before accepting each ready endpoint or recording a startup warning. Revocation may therefore take about one second to stop an idle wait, without authorizing an intervening effect. The updater running the canary must contain this change; a newer candidate does not change an older installed updater's polling.

The internal progress-capable launch repeats the existing --update-canary boolean marker; legacy launches contain it once. This is an internal updater-to-candidate contract, with no operator configuration setting. Startup failure reports retain the last meaningful stderr diagnostic and the end of bounded log lines, with secrets redacted. Canary progress markers do not replace the failure reason. The installed updater owns this reporting, so an older updater can retain its earlier diagnostic behavior on the first update. During private rehearsal, exec SecretRef providers are deferred and their owners start cold with a recorded warning. Provider prerequisites such as a 1Password service-account token stay in the serving state directory; rehearsal does not copy them or run a resolver against that directory. SecretRefs remain references in the copied configuration. Credential availability is checked by the normally activated Gateway. This repair must be present in the candidate; it also applies to older updaters that supply the complete private-rehearsal environment.

The canary verifies the copied plugin payloads without downloading replacements. It warns when plugin refresh is deferred; live update finalization owns that refresh, so a slow registry cannot consume the canary's startup budget. This candidate-side behavior also applies when the installed updater is 2026.9.3. That older updater still caps the entire validation sequence at five minutes; its --timeout option cannot increase this cap.

Plugin rehearsal copies are temporary and rebuilt after interruption. Copying uses up to four concurrent file copies and avoids a disk flush for every file. Failures to remove private candidate copies or Git inspection worktrees are warnings that identify the cleanup path and error class. They preserve the original candidate result and the installed runtime's recovery verdict. Unverified process cleanup still requires its recovery owner. If a copy fails, active copies finish before cleanup; link publication and verification run only after all file copies succeed. Each private copy or inspection uses one generous absolute allowance derived from its inventoried size, with the caller's larger allowance preserved. Progress remains diagnostic and does not renew the allowance. Exceptionally slow storage may require another update attempt after a visible timeout. Stored state and recovery backups retain their existing durability guarantees. An older installed updater keeps its initial snapshot behavior until you launch an update from the newer version.

Candidate validation uses separate size-aware allowances for snapshots and each runtime check. Slow snapshots and Doctor no longer consume the next check's allowance or trigger an additional 30-minute limit for the whole validation. An explicit --timeout still bounds the overall update from admission; phases do not reset it. Cancellation settles accepted child processes and writers before recovery. This correction must be present in the installed updater; staging a newer candidate cannot change the older driver's validation deadline. Update-history writes retry a timed-out commit admission at most three times, releasing the SQLite writer between attempts. Ordinary progress that still cannot be recorded, including a worker queue-capacity refusal before dispatch, produces a warning and validation continues. Snapshot progress keeps one write in flight and coalesces pending observations to the latest progress. Required recovery and terminal records report a failure instead of retrying forever. These limits apply when the newer installed updater runs; staging it cannot change an older driver's already-running progress writer.

If the 2026.10.4 updater stops with candidate-snapshot-failed and SQLite worker queue capacity reached, staging a newer candidate does not replace that progress writer. Preserve a verified state backup and follow the manual package-manager procedure to install a release containing the fix, stopping and starting the Gateway through its actual service owner. Keep the same account, installation prefix, profile, and state paths; do not delete databases or disable consistency checks.

Runtime retention looks for hoisted dependencies within the package manager's owning installation. Missing optional peers do not cause it to copy unrelated ancestor installations. Explicitly linked dependencies retain their own resolution. This improvement applies after the newer updater is installed; it cannot shorten the retention phase already running in an older updater.

Post-activation schema inspection preserves captured SQLite database, WAL, and shared-memory artifacts so the final Doctor can verify the same migration source.

Database rehearsal also avoids a second full backup of each private snapshot. Candidate inventory reads database registrations and the installed plugin index in one read-only transaction instead of copying the whole shared database just for metadata. Sources requiring private recovery keep the snapshot path. The candidate worker must contain this improvement; snapshot publication, integrity checks, and rollback verification are unchanged. Update schema inspection and rehearsal use SQLite online backup with a pinned read transaction, so a busy Gateway can keep writing while the copy includes committed WAL data. Each acquisition makes one copy instead of retrying until the database becomes quiet. On rollback-journal volumes, SQLite can delay writer commits until the consistent read finishes. Rehearsal records copied pages, bytes, and elapsed time in the update ledger, then checks and publishes the private copy with row IDs preserved for validation. Source databases and recovery backups retain their existing protection; the faster preparation takes effect when the newer updater runs.

Package updates also check npm availability for enabled configured plugins before stopping the serving Gateway or replacing the installed core. Registry targets are checked early; explicit package artifacts are checked using the privately staged package version before private validation, live-state preparation, or activation. The check uses the same plugin version rules as post-update synchronization, including release-cohort tracking, beta selection, and extended-stable targets. A missing plugin version or registry error produces a warning naming the affected plugin; the core update can continue. Registry-target --dry-run includes those warnings. For explicit artifacts, --dry-run does not stage the package and reports that plugin availability checking remains pending. Extended-stable does not accept --tag. Bundled and path-installed plugins do not require registry requests.

This metadata check does not reserve downloads. Plugin-only download, install, or load failures remain actionable warnings after an otherwise successful core update. Snapshot inventory runs from the staged candidate package, so it uses the target version's plugin inspector. Snapshot inventory and candidate Doctor share plugin source inspection. An unparseable entry produces a warning with the plugin ID, source path, and parser error while its files are copied unchanged and other entries are checked. Valid ESM plugins can use import.meta during dependency inspection. The updater preserves recorded choices and retains the previous plugin payload where possible. Follow the reported openclaw plugins update <id> command for a failed install or update, or openclaw doctor --fix for a load problem. Invalid configuration or state, ownership errors, and failed core startup or readiness checks still prevent completion.

Shell completion-cache refresh is best effort. If it times out and its process cleanup is verified, finalization records the failed cache phase and deadline warning while allowing the update to finish. Run openclaw completion --write-state to refresh it manually. Unverified process cleanup still blocks finalization; the updater does not report success while owned work may remain active.

npm plugin rollback

Updaters with plugin-cohort recovery keep the previous npm plugin artifacts, installation records, and matching settings until candidate activation is verified. If activation fails, rollback restores that cohort before restarting the previous Gateway. Backups precede plugin maintenance. After an interrupted update, openclaw update repair resumes the recorded plugin settlement under current ownership. It preserves later independent changes. When a plugin's install record, data/settings upgrade obligation, package files, source snapshot, or a config file the update wrote changed after the update, rollback keeps that later change, restores everything that still matches, and completes. It records the kept items in an update warning that repair prints and openclaw doctor shows. Recovery still stops for a config file whose path was replaced, for config that fails validation or secret resolution, and for a corrupt recovery journal. The updater performing the operation must contain this support; installing a newer candidate does not add it to an older parent. When recovery stays pending, the update prints the first failure below the unfinished-recovery refusal and names openclaw update repair when it can settle that plugin cohort. When a legacy Doctor fails or is interrupted, package rollback leaves compatible databases in place. Database restoration still requires the existing schema and write-generation checks; later independent changes prevent an unsafe restore.

Package-publication recovery

Supported POSIX npm updates print a recovery command using the selected external Node or Bun executable before transferring the staged package into recovery custody. Keep the printed commands; each names one operation with required --anchor and --operation arguments. The initial journal and helper are published together in a private control directory only after both are complete. A later update first prints a temporary staging command, then the stable command after the helper has moved. The staging command is valid only before that move; an earlier operation's command cannot select a later operation. The helper verifies its own recorded path, identity and content before using that journal. It is outside the live package and disposable recovery directory. status reads the operation, repair resumes only its recorded package publication, and retire removes only its recorded obsolete objects. These commands do not replace post-update plugin, migration or service recovery. Keep other package managers stopped while recovering the operation.

If an updater-owned recovery directory, helper, or journal gains group or other permissions, the updater restores owner-only access and warns with the path, observed mode, and link count. On Linux, this also clears the effective POSIX ACL mask; named ACL entries can remain but no longer grant access. When getfacl is available, the warning identifies detected ACL entries. Foreign ownership, symlinks, unexpected object types, multiply linked files, and permissions that cannot be repaired still require intervention. Repairing these private objects does not change package-content fingerprints or authorize recovery of modified package files. If recovery still refuses, automatic update and managed-service handoff reports retain its reason code and diagnostic message in the failed phase.

On FreeBSD, repair and retire read process identity through the recorded installation's own @openclaw/proc-safe dependency and its FreeBSD platform addon: the live package, or the copy the operation retains beside it during publication. Helpers written by older updaters cannot repair or retire on FreeBSD; status still reports the operation.

Bun recovery requires a supported Bun runtime with WAL-reset-safe SQLite and can run without Node installed. The installed updater controls the first upgrade: older releases may omit the recovery command on Bun or refuse a Bun recovery runtime. Installing a newer candidate does not change that first-hop behavior; subsequent updates use the candidate's recovery support.

Retirement records removal of the disposable directory before recording the helper's final unlink intent. The helper is then removed. The bounded last receipt remains in the control directory and is readable through openclaw update status --json as packageActivation, even after helper removal. A completed receipt is replaced only by a newly admitted update under current ownership; it is not authority to mutate an installation. Historical filesystem or executor-store identities do not have to match today's identities. Reboots, remounts, or removal of already-retained evidence do not reopen a closed operation. Reading a completed receipt does not rewrite it. A new update archives the completed receipt before preparing its own operation, preserving the journal and any leftover helpers or recovery directories as evidence.

Explicit repair preserves settled evidence, including the entire control journal, inside the operation's retained recovery directory. The completed journal leaves the active admission path, so an older updater does not need to understand a newer settlement reason. Ordinary successful retirement retains the last receipt until the next update archives it. Explicit repair verifies an installed candidate under current executor ownership, even when the old lease store disappeared or was replaced. It does not execute the old helper, so a changed or missing helper and changed retained directories are preserved as evidence rather than required as proof of the live package. An unfinished rollback still requires recovery while its package or published launchers remain installed.

If an external install replaced both recorded package generations and every published launcher, the next update retires the stale publication journal with a warning. It preserves the journal, helper, and retained package trees for diagnostics, including when the control directory or journal was copied. It does not restore or delete the current installation. Recorded generation inodes are excluded even across device-number changes, so a remount alone cannot qualify. The updater performing admission must contain this fix; an already-blocked older updater needs a manual package install first. Recovery runtime compatibility is checked before creating a publication journal.

openclaw update uses the same settlement before admission when the recorded lease database is missing or its identity has changed and the live installation is still the recorded previous or candidate package. Candidate content and launchers must pass verification. Settlement preserves recovery evidence, reports a warning, and does not restart the Gateway or install a package. --dry-run verifies and reports the planned settlement without changing the journal, lease database, or recovery evidence. Other pending operations still require openclaw update repair or the recorded package recovery command. The lease database stays at its existing location.

If a reboot or temporary-directory cleanup removes the lease database before publication starts, recovery can retire a prepared journal with no publication intent or published launchers. It first checks that the live package, launcher directory, and every launcher still have their recorded previous identities. Update admission, repair, and a separately staged recovery helper share this settlement. They warn and rename the journal, control directory, candidate, and the operation's remaining npm update stage into retained evidence; they do not delete them. Other stages are left with their owners. Changed identities, publication intent, or another phase do not qualify for this recovery path. Recovery status is read-only and can report an unfinished operation even when the lease database is missing or replaced.

The managed-update lease store still uses the shared per-user temporary location. Moving it to a state directory requires a coordinated migration: older updaters continue acquiring leases in the temporary location, and separate profiles can update the same installation. Copying the database would create competing lease owners; file symlinks and hard links do not satisfy the existing store contract. Durable placement remains follow-up work. These recovery changes must be present in the updater or separately staged helper that executes them; an older sealed helper does not gain the new behavior.

After the transaction verifies its selected installation, cleanup failures are warnings. Changed old package trees, old helpers, and unexpected backup contents are preserved, not restored or deleted. The updater durably closes their recovery operation and attempts to archive the evidence. If completed evidence cannot be archived, a later update retains it and uses the ordinary package-swap path without standalone publication recovery. Its warning names that limitation.

These rules do not mark an unverified publication as a successful update. Missing, legacy, corrupt, or still-applicable identity-mismatched unfinished recovery artifacts still require their recovery owner. Live ownership conflicts, changed selected packages or launchers, and pending restoration remain refusals. Preserve those artifacts; do not recreate the journal or remove them to bypass recovery.

These admission and cleanup fixes must be present in the updater executing them. A newer candidate cannot run before an already-blocked older updater downloads it. The candidate's dependency inventory can, however, avoid modifying old recovery artifacts during an update that has already passed admission.

Recover an unfinished publication after a remount

An older updater can reject an unfinished journal before downloading a fix when filesystem device numbers change after a reboot or remount. With a version containing this fix installed, run openclaw update repair from an independent terminal. Repair can settle prepared, publishing, publication-complete, and superseded operations when the journal's inodes still match under a consistent device-number mapping. Ordinary update admission stays strict.

This settlement first shipped in 2026.10.5. Earlier releases, including the 2026.9 extended-stable line, refuse with Package publication journal does not match its installation and cannot settle the change themselves; starting with 2026.10.7, the message also names the changed bindings. From an earlier release, install 2026.10.5 or newer with the manual npm procedure, then run openclaw update repair --yes from the new installation. See #170031.

If the installed updater cannot read the journal, a separately installed OpenClaw version containing this fix provides the same settlement-only path:

node /path/to/recovery-openclaw/dist/package-update-activation-recovery.mjs \  --anchor '/absolute/path/to/.openclaw.package-activation-<key>' \  --operation '<recorded-operation-id>' repair

Use the original anchor and operation ID with a supported external Node or Bun runtime. Keep other updaters and package managers stopped. Ordinary status and update admission remain strict for unfinished identity-mismatched journals.

The helper can refuse when retained launcher evidence is missing. In one report, the 2026.10.5 helper refused a 2026.9.33 publication-complete journal whose anchor held only previous, with ENOENT on <anchor>/launchers. No supported procedure covers that layout yet. Preserve the journal, anchor, and retained generation, and report the exact output.

If publication never started and the previous package is still installed, repair verifies its full tree fingerprint and unchanged launchers under the same device mapping, then settles the operation as publication-not-started. The candidate is retained as evidence; the installed package is unchanged. A previous package with unfinished publication intent or launcher receipts still requires its original recovery owner and is not silently archived.

For an already installed candidate, repair requires the staging path to be absent, consistent device-number changes with matching object inodes, the original intact helper and retained previous generation, a matching full candidate-tree fingerprint, valid package inventories and manifest, and unchanged launchers. Device projection applies only to digest verification: historical identities in the journal are not rewritten. Version or inode matches alone do not qualify; changed content, unsafe journal permissions or links, active update ownership, and unfinished rollback remain refusals.

Symlink launchers may have different recorded permission modes (for example, 0755 and 0700) if their targets and required identities still match. Regular-file launcher modes and package-tree integrity checks remain enforced.

If a manual installation has replaced the candidate with a newer version, repair verifies that installation's manifest, dist inventories, entry targets, and launchers before archiving the old operation as superseded-by-manual-install. Old package trees and helpers remain preserved as evidence; they do not have to pass the old candidate's fingerprint checks.

For the recorded candidate, under fresh executor ownership, repair records publication-settled-external-change and preserves the entire journal and recovery evidence in the reported archive. Removing that closed receipt from the active admission path lets the older updater continue without interpreting a new receipt kind. If archival fails while the active receipt remains, resolve the reported error and rerun the same command. If the helper reports an unconfirmed archive after moving the control directory, preserve and inspect the reported archive; the original command no longer has an active journal to reopen. The helper does not republish or roll back a package, delete retained generations, or restart or verify the Gateway. It does not execute the original helper. Other unfinished layouts still require their original recovery owner.

Recover a completed receipt with an older updater

An installed 2026.9.8 or 2026.9.9 updater can reject a completed anchor-retired receipt before downloading a fix when saved filesystem device numbers change. Use a separately installed OpenClaw version containing the completed-receipt recovery fix. Its standalone helper can archive completed history for the original installation while that installation's Gateway keeps running:

node /path/to/recovery-openclaw/dist/package-update-activation-recovery.mjs \  --anchor '/absolute/path/to/.openclaw.package-activation-<key>' \  --operation '<recorded-operation-id>' statusnode /path/to/recovery-openclaw/dist/package-update-activation-recovery.mjs \  --anchor '/absolute/path/to/.openclaw.package-activation-<key>' \  --operation '<recorded-operation-id>' retire

Use the anchor and operation ID from the original journal, with a supported external Node or Bun runtime. Keep other updaters and package managers stopped. status must report complete; it does not modify the receipt. retire acquires fresh update ownership, verifies that the inspected completed receipt is still current, and moves its control directory into the printed .superseded-<id> archive. It preserves the journal bytes and saved identities, installed package, launchers, and application state. It does not run Doctor or plugin migrations. After successful archival, retry openclaw update using the original installation.

If archival fails and the active receipt remains, the command exits unsuccessfully and names the next step. Preserve both the receipt and any existing archive while resolving that error. An unfinished, foreign, or invalid operation still requires its original recovery owner; the independent helper cannot authorize publication or rollback for it. Do not rewrite identities or delete recovery artifacts.

Unfinished publication and rollback

openclaw update automatically settles a prepared, publishing, or publication-complete operation when the live candidate passes the same verification as repair, even when the update lease is unchanged. It also retires an untouched preparation after verifying the original package and launchers. This does not republish files beneath a running Gateway. A dry run previews settlement without changing recovery artifacts. Unfinished publication that still needs file changes, pending rollback, and failed verification retain their recovery artifacts and report the repair command.

After a managed-service update fails before stopping the original Gateway, the handoff checks whether that original version is still serving and records the outcome. A stopped Gateway or unavailable health check is reported with its reason. This observation does not restart the service or mark the attempted update successful.

To explicitly settle an external-helper operation stuck at prepared, publishing, or publication-complete whose live package already serves the candidate, run openclaw update repair from an independent terminal. Repair verifies the installed candidate's dist content inventory, manifest, launchers, and current update ownership before settling the operation. It archives the remaining helper and retained package evidence, including a changed previous tree, without restoring or deleting that tree. Failed verification leaves recovery armed and blocks the next update. Older updater versions without this settlement path still require their original recovery owner.

SQLite recovery and rollback custody verify file identity, size, and content. Timestamp-only changes are accepted after verifying identical bytes; replaced files or changed database or journal bytes still require recovery by their owner. Snapshot publication uses the same checks, including on older Linux kernels where reported file creation time changes after ordinary writes or hard-link removal.

For older in-directory activation journals, openclaw update status --json reports the recorded phase and the original helper's status command. The current updater only inspects these journals; use their original helper to recover or retire the operation before starting another update.

Package recovery does not replay a full-state checkpoint or reverse database migrations. Automatic rollback keeps compatible databases in place, preserving newer writes. If the previous runtime cannot read the current databases, the updater retains the candidate and recovery artifacts and reports why rollback was refused.

After migration, recovery checks the installed candidate's schemas before restarting a Gateway stopped by the update, even when normal Doctor completion did not need a process-settlement receipt. A later verification error does not make the previous package compatible with migrated state. Obsolete package backup cleanup is best effort: locked files or denied renames produce warnings with the retained path and filesystem cause, without failing verified activation.

Rollback snapshots settle local SQLite writers under maintenance ownership before capture, so writer shutdown during rollback is not mistaken for intervening writes. The installed updater owns snapshot capture; staging a newer candidate cannot change that behavior in an already-running older updater.

Switch channels or target a specific version:

openclaw update --channel betaopenclaw update --channel extended-stableopenclaw update --channel devopenclaw update --dry-run   # preview without applying

openclaw update has no --verbose flag (the installer does). For diagnostics use --dry-run to preview planned actions, --json for structured results, or openclaw update status --json to inspect channel and availability state.

--channel beta selects the newest version by semantic version order from the beta and latest npm dist-tags. Use --tag beta for a one-off package update pinned to the raw npm beta dist-tag instead.

A saved update.channel remains the channel for future updates, automatic checks, and update status. For example, a one-off beta package on a saved stable channel keeps checking stable afterward. Use --channel beta to subscribe to beta updates. Plugins still follow the installed core version where required for compatibility.

--channel extended-stable is package-only, and installation remains foreground-only. OpenClaw reads the public npm extended-stable selector, verifies the selected exact package, and installs that exact version. Missing or inconsistent registry data stops the update; it never falls back to latest. If the selected version is older than the installed version, the normal downgrade confirmation still applies. The CLI persists the channel after a successful core update; a direct npm install -g openclaw@extended-stable --allow-scripts=openclaw does not update update.channel, but a final extended-stable package version still checks only the verified extended-stable selector for update availability. That direct command is for npm 12 or npm 11.16+. On npm 11.15 and earlier, omit --allow-scripts=openclaw. After the core swap, eligible official npm and trusted official ClawHub plugins with bare/default or latest intent converge to that exact core version. Eligible older OpenClaw release pins resume that default update policy. Explicit non-latest tags, independently versioned pins, third-party plugins, custom ClawHub registries, and other sources retain their existing behavior. Version-bound runtime plugins converge to the base release cohort when the core is a correction release (for example, YYYY.M.P-2 uses plugin YYYY.M.P). openclaw plugins update uses the same host-matching targets. Known-incompatible official runtime versions, such as Codex releases before 2026.9.7, are reported as unavailable before they can register or serve turns. Compatible versions remain loadable even when they are older than the host. Run openclaw update repair, or openclaw plugins update codex, then restart the Gateway. Newer explicit pins and independently versioned plugins retain their existing compatibility behavior. Catalog installs created by current OpenClaw versions retain that default intent. Verified OpenClaw-owned packages recorded at an exact OpenClaw release no newer than core resume their catalog's default selector after a successful update. This includes old automatic and manual pins. Their recorded registry and plugin settings are preserved, and subsequent updates continue following the selected channel. A version explicitly supplied to a plugin update command still applies to that operation.

--channel dev gives a persistent moving GitHub main checkout for npm-owned package installs and existing Git checkouts. Package installs reject the --tag main shorthand because the workspace checkout is not a self-contained package artifact. Use openclaw update --channel dev to switch to the supported checkout and build flow. Other explicit package specs keep their package-manager behavior. Dev target inspection fetches only the selected upstream source, respecting the repository's ref mappings and exclusions. It does not download unrelated branches or change the repository's shallow boundary. Stable and beta target inspection fetches release tags only, without refreshing remote branches. An implicit dev-channel switch from a detached release-tag checkout can use the fetched main commit even when the configured fetch refspecs only map tags. The updater leaves those mappings unchanged and still honors explicit branch exclusions. When it creates main, it records the selected remote and merge source so later dev updates remain managed. It does not take over an existing unmanaged main.

On source installs, Doctor and plugin updates keep plugins built with the host. A registry plugin with the same version string can target a different SDK, so it does not replace the source build without matching SDK build evidence. Existing registry generations remain on disk; convergence reports the bundled selection and skips their refresh. OPENCLAW_DEV_SOURCE_ROOT is not required.

Managed npm plugins on the beta channel use the same newest-of-beta/latest selection, including official plugins such as @openclaw/codex. An older beta tag cannot hold a plugin behind the current stable release. Startup repair leaves already-current packages in place so a no-op refresh does not require another restart.

See Release channels for channel semantics.

Updating from 2026.9.2 across a schema bump

Updates driven by OpenClaw 2026.9.2 can cross a shared-state schema bump normally. The target applies the migration content while retaining the old published schema version, so the old updater can finish its ledger writes and final report. Doctor explains that schema content is applied and version publication is deferred. The new Gateway runs on the migrated content during this interval.

Publication waits until every affected update run has been terminal for at least five minutes. A running row that has not changed for more than 30 minutes counts as abandoned for publication purposes only; this does not terminalize an identityless update-history row. The Gateway watcher publishes after the deadline; a later database open can also publish it. See the precise timing and residual old-CLI limitation in Database schemas.

When agent databases also need migration, the candidate first rehearses Doctor on private copies while the published updater can still roll back its package. After package commit, the fresh post-core process acquires current executor authority and delegates Doctor. Doctor verifies a retained recovery archive covering each agent database before migrating live state. The updater then restarts the Gateway.

Missing state metadata or unverified backup coverage can still produce update-schema-bump-unfenced with database versions and recovery instructions. If npm postinstall emits this typed refusal, the updater reports it without retrying the install with optional dependencies omitted. Other install failures retain their existing retry behavior. Before package commit, let the failed update finish restoring the previous package. OpenClaw 2026.9.2 leaves the Gateway service stopped after failed post-install verification. After package commit, the old package backup is gone: finish openclaw doctor --fix with the installed compatible build, then run openclaw gateway start. Package rollback cannot undo migrated state.

If the compatible package still needs installation, follow the manual update procedure from a shell outside the Gateway, using the exact target version from the refusal instead of latest.

Same-schema updates, earlier ledger-less updaters such as 2026.9.1, and fenced transactional updaters from 2026.9.3 onward keep their existing behavior. The fallback does not undo an earlier migration; if the database is already newer than the restored package, install a compatible target and finish Doctor before starting the Gateway.

For a Git checkout updated by 2026.9.2, a Doctor refusal before state writes prints source recovery commands when the checkout's reflog identifies the previous commit unambiguously. Wait for the updater to exit, then follow the printed checkout, pnpm install, pnpm build, and service-start guidance from an independent shell. If the previous commit cannot be verified, Doctor points you to the reflog instead. A refusal after state repairs keeps the migration owner's instructions: restoring source alone does not restore state. These diagnostics also enter the warning log, subject to normal logging settings and rotation. After resolving the refusal cause, retry the update. Once the upgrade succeeds, subsequent updates check the new version before activation.

From chat

In the Control UI, expand Update available in the Inbox to check the latest Dev Git target. The card checks again before opening update confirmation. While checking, it hides the previous SHA and disables the update action. A failed check shows an error; retry the action to check again. Opening the card does not start an update.

Update confirmation belongs to the Gateway and profile that opened it. Switching Gateways or profiles retires the pending confirmation; open it again on the intended Gateway. Native updates also check current administrator access when you confirm and show an access error if it was revoked. Once an update starts, its progress report remains available through that Gateway's restart.

Ask the agent to update OpenClaw, or send /update from Discord or another connected chat. Natural-language requests use the existing gateway tool's update.run action. The same tool exposes restart for a runtime-coordinated safe restart and update.cleanup for explicit recovery cleanup without stopping the Gateway. The minimal, coding, and messaging profiles expose these maintenance actions without granting configuration reads. Explicit tool restrictions still apply.

On an explicit owner request, the agent performs the supported action itself; it does not send the owner to a slash command or terminal. Restart requests can be deferred until active work settles; an accepted schedule is not a completed restart. Cleanup uses the serving Gateway's owner-bound worker and the existing manual verification, eligibility, and dependency checks. It permanently removes eligible rollback copies, so it requires a cleanup request. Set dryRun: true to preview. It does not select unmanifested paths or stop/restart the Gateway.

Operator-created scheduled automations can also call gateway → update.run without a chat owner identity. The Gateway uses the active scheduled run's authority; a notification destination does not become its requester. Jobs created by external chat users and webhook turns do not gain this authority. External chat update requests still require current command-owner authority.

/update is the model-independent fallback: it works without a functioning model or access to the gateway tool. The tool, slash command, and Control UI all use the same Gateway update handler and current authorization checks.

The new version is checked while the old Gateway serves. An already-current update restarts a running Gateway when plugins change or its service points at a different installation. Update runs can send these notices in that chat as the Gateway observes the recorded milestones:

1. An acknowledgement when the update is accepted.
2. ⏳ Preparing to restart OpenClaw… The update is not complete yet. before the managed Gateway stops.
3. 🔁 Checking that OpenClaw is ready… during Gateway verification.
4. The final report, including successful updates.

External update and restart notices go to destinations listed in commands.ownerAllowFrom or a linked administrator's direct conversation. The channel resolves a direct recipient to its stable sender identity before checking the administrator link; group and channel targets do not inherit a person's administrator authority. Selecting a non-owner chat in the Control UI does not authorize notices to that contact. If no owner destination resolves, OpenClaw logs the skipped notice and keeps the update outcome in the run record and Control UI; it does not redirect the notice to another chat or wake the rejected session with diagnostics.

Update lifecycle notices also honor the destination account's actions.sendMessage policy. An explicit account setting overrides the channel default; when neither sets the flag, notices are allowed. Disabled sends are recorded as skipped notices without preventing the update or its Control UI report.

Managed systemd or launchd updates can stop the Gateway before an intermediate notice is delivered. The complete four-message sequence is not guaranteed for those installations; the durable run report remains available after reconnect.

Runs with an internal origin session, including Control UI and webchat, receive these notices directly in that session's transcript. Passing only sessionKey is enough; the caller does not need to supply deliveryContext. Before stopping the managed service, the updater waits for the serving Gateway to finish its restart notice attempt. That wait is capped at 10 seconds so a stalled notice cannot block activation.

The report includes the outcome, recorded phase durations, failed steps, verification facts, and the next action when needed. Failed-step summaries preserve the initiating cause ahead of trailing recovery advice, using recorded failure facts when available. Local run history retains verification findings and backup recovery paths separately from the excerpt. A run sends each notice at most once; an update that stops before restart sends only the notices for phases it reached. Restart recovery reuses an already-recorded completion notice even if later verification changes the outcome. The run report remains the current source for that outcome. A milestone with no eligible delivery target is recorded as skipped instead of retried on every recovery check.

If the update cannot start, the bot records and explains why and provides the manual command when available. The agent relays the returned recovery instructions to the operator. Manual update commands run in a terminal outside the Gateway service; the agent must not execute them in the shell of the Gateway hosting its session. A missing owner permission requires owner setup, and an externally supervised installation uses its deployment owner's update workflow.

For installations updated by OpenClaw itself, chat, CLI, Control UI, and automatic updates share a durable run ID. Use openclaw update status to read the active or latest report, including after a restart; --json exposes the activeRun and lastRun records. See Run history and reports for Gateway history queries.

The sender must be in commands.ownerAllowFrom or have a verified channel link to a current Gateway administrator. Being allowed to chat does not grant owner permissions. If your account is not an owner, the reply explains how the Gateway operator can connect it. Channel setup and pairing distinguish owner access from chat access; existing allowed users are not automatically promoted. Chat updates retain the original authorization source across managed handoffs, repair workers, and Doctor runs. Each worker checks the original installation's current policy and profile state before acting. A repair worker's inference turn checks them before each model attempt, each tool call and its effects, and before it reports a result; its run-preparation checks verify update ownership, the updater connection, and cancellation. Reassigning a channel account to another administrator does not transfer an update already in progress; a current owner must start a new update. Older updater handoffs without a captured profile source retain their configured-owner checks and cannot acquire linked-profile authority during recovery. External-chat updates through /update or the tool require commands.restart (enabled by default), including managed installations. The slash command also follows command-access restrictions; tool calls follow tool policy. Chat updates use the hosting installation's configured update channel and install method. Agents use runtime-supervised maintenance rather than an unsupervised shell stop/update/start sequence or package swap. The runtime retains restart ownership before stopping the Gateway. Non-owner requests remain refused, and chat restarts honor commands.restart just like chat updates. Cleanup does not depend on that flag because it does not restart the Gateway.

Inspect FreeBSD service discovery

The standalone scripts/freebsd-service-inspect.mjs diagnostic reports which openclaw rc.d definitions the native configuration selects. It requires a root-owned Node installation, script, and shared discovery helper. It does not require the OpenClaw Ports service package.

From an existing root shell, install the script from a trusted OpenClaw package:

install -d -o root -g wheel -m 0755 /usr/local/libexec/libinstall -o root -g wheel -m 0644 /path/to/openclaw/scripts/freebsd-service-inspect.mjs /usr/local/libexec/openclaw-service-inspect.mjsinstall -o root -g wheel -m 0644 /path/to/openclaw/scripts/lib/freebsd-service-discovery.mjs /usr/local/libexec/lib/freebsd-service-discovery.mjs(cd / && /usr/bin/env -i HOME=/ PATH=/sbin:/bin:/usr/sbin:/usr/bin LC_ALL=C /usr/local/bin/node /usr/local/libexec/openclaw-service-inspect.mjs)

Use your root-owned Node path if it differs. Clear the environment before Node starts, as shown, to exclude Node preload options. The command accepts no arguments. It reads native administrator shell configuration as root and requests no service lifecycle operation. Administrator configuration is trusted shell code, not a sandboxed data format.

The result includes the exact clean environment and working directory used for discovery. It corresponds to service invoked with that same context. Configuration that depends on another environment or directory can select different services.

The single JSON result reports absent, present, or unknown. Present results include executable and non-executable definitions, their native search order, and the first executable definition. Symlinks, unsafe ownership, incomplete inspection, or unexpected configuration output produce unknown and exit 1. Configuration contents and subprocess errors are not included in the result.

This is a diagnostic observation. It does not establish process or package ownership, authorize an update, or enable CLI-managed rc.d service updates. Continue to use the installation owner's update procedure above.

Stale update history

Untouched, identityless legacy admissions older than 24 hours can expire automatically during Gateway startup or a status check. The row is retained as failed with reason legacy-driver-expired and retry advice; no explicit repair is needed for that shape.

If update status stays in progress while the Gateway is healthy, check that no update is still running. On the updated installation, run:

openclaw update repairopenclaw update status

Standalone repair reports the repairing phase while Doctor and plugin maintenance run. Its finalize:* history steps identify the current operation. Before maintenance, repair marks confirmed dead drivers as abandoned while preserving their history. Completing maintenance is acknowledged separately, so a later repair failure does not leave those exited drivers recorded as running. Runs with retained recovery custody stay with their recovery owner.

For an inactive legacy row older than 30 minutes, repair verifies that the running Gateway matches the installed version and build, then clears the stale run without maintenance or a service restart. A new explicit openclaw update can also supersede a single stale identityless row. Recent rows and recorded live drivers are protected. Identityless rows outside the legacy-expiry shape require explicit recovery; the Control UI's configuration-write suspension clears after reconciliation.

Repair started within the owning update can continue with a matching inherited run ID and live process identity; the run records that continuation. Repair still refuses an unrelated live or stalled updater. The error identifies its run, phase, driver PID, host, start and last-activity ages, and observed liveness. Wait for that update to finish, or stop the named driver on its host and rerun repair after it exits. See Update repair for maintenance and recovery behavior.

An empty update history does not mean the installation is free. If openclaw update reports that another update executor owns the installation and names cancelled update custody, an earlier cancelled updater exited without releasing it. Run openclaw update repair; it settles that custody once the updater and its descendants are proven gone, and otherwise reports the blocker, exits with code 2, and leaves the next update blocked. See Update repair.

OpenClaw 2026.9.2 does not reject a new CLI update because an older running row exists: its admission path creates a new run, and its ledger checks only for a duplicate run ID. Upgrade normally, then use the updated openclaw update repair if the old history remains. A package-manager escape is not required for this ledger defect. See Update run history.

Retire update recovery data

Once you have verified the update and your conversations, ask the agent to clean up update recovery copies. The gateway tool's update.cleanup action runs under the serving Gateway's ownership; no stop is needed. It also accepts dryRun: true for a preview. The standalone CLI keeps its offline apply requirement below.

To preview retained migration originals from a terminal:

openclaw update cleanup --dry-run

Use the same profile and state/config overrides as the update, and check the state directory printed in the report. The metadata-only preview can run while the Gateway is active. To apply, stop that Gateway yourself, wait for other SQLite maintenance to finish, and stop database readers such as session-listing watchers. Keep them stopped until openclaw update cleanup exits; read-only connections can change WAL/SHM sidecars and invalidate verification. Cleanup never stops or restarts the Gateway. Confirmation defaults to No; automation must explicitly pass --yes, including when using --json.

Cleanup permanently gives up rollback to eligible originals, including repaired branches and old provider metadata. Current SQLite history, operator backups, and protected or unknown artifacts remain. It is not a substitute for a pre-update backup. See Update cleanup for eligibility, JSON output, and resuming interrupted deletion. Private package, command-shim, and Git runtime backups remain owned by the update transaction and are outside this migration cleanup. An interrupted entry in update history does not block cleanup of otherwise eligible migration archives.

After updating

Successful managed openclaw update runs already restart and verify the Gateway. Use these steps after a manual installation or when checking a reported problem.

openclaw doctor

openclaw gateway restart

openclaw health

Background exec notifications after an update

Background-command completions can trigger follow-up turns in their originating session even when recurring automations are disabled. To keep background exec without these extra model calls, set tools.exec.notifyOnExit: false and check per-agent overrides at agents.entries.<id>.tools.exec.notifyOnExit. Use process poll to collect results. See Background exec notifications for when the setting takes effect.

Detailed topics

• Switch between npm and git installs
• Source-checkout servers (reference script)
• Alternative: re-run the installer
• Alternative: manual npm, pnpm, or bun
  • Package lifecycle and operator state
  • Advanced npm install topics
    • Read-only package tree
    • Hardened systemd units
    • Disk-space preflight
• Auto-updater
  • Update campaigns
• Downgrade
  • Full-state recovery requires a backup
  • Automatic schema-neutral rollback
  • Before updating: create a verified backup
• If you are stuck
  • Unattended repair on your own inference

Related

• Install overview: all installation methods.
• Doctor: health checks after updates.
• Migrating: major version migration guides.