Update troubleshooting

Failed updates enter built-in triage after update recovery settles. In an interactive terminal, OpenClaw shows the selected agent, saved prompt path when available, and use of your own account/tokens, then asks before launching triage. Enter or y proceeds, n preserves diagnostics and prints handoff commands, and no answer within 30 seconds proceeds as Yes with a notice. With --yes, --json, or no interactive terminal, it prepares diagnostics and handoff commands without launching an agent. The original update failure and exit status remain authoritative; diagnostics do not turn a failed update into a successful one.

In the Control UI, a failed attempt opens Ask OpenClaw with its recorded details and asks it to investigate before retrying. A lost connection or verification timeout is presented as an unknown outcome. The tab remembers the latest 32 investigated attempt identities, scoped to their Gateway and profile. Status checks, switching between those scopes, and reloading the same tab do not automatically send those investigations again. If the browser cannot read or save that history, the failure details remain visible without an automatic diagnostic request. Ask OpenClaw manually or run openclaw triage on the host. If the Gateway or agent is unavailable, use openclaw triage on the Gateway host. Automatic diagnosis keeps your unsent composer draft, including when its conversation session must restart.

Control UI → Settings → Updates keeps the latest recorded attempt visible, including its time, before/after identities, reason code, failing step, and bounded diagnostic detail. A version or revision verification failure stays visible when a status check rereads the same attempt. An unknown verification outcome resolves when the expected version or revision arrives, or when the same attempt reports its final failure or cancellation. A newer recorded attempt can also replace it. Intentional cancellations, already-current installs, and updates still in progress do not start triage.

For a final failed attempt, Report update failure is separate from Retry and Ask OpenClaw. It previews a bounded report containing the OpenClaw version, platform, update target, failed phase, sanitized diagnostics, and verified rollback outcome. The report excludes secrets, tokens, chat content, raw logs, private absolute paths, and recovery commands. Nothing is submitted until an administrator confirms that preview. OpenClaw then uses the existing GitHub CLI issue flow. Fallback and pending outcomes retain the sanitized report locally; a confirmed issue keeps only its durable issue URL. OpenClaw first makes a silent, read-only request with the active github.com account. A missing CLI or a failed, unavailable, or timed-out authentication check returns a prefilled issue link without starting issue creation. In the Control UI, an interrupted preparation for the recorded attempt can be retried after its local reservation expires. Once issue creation starts, a timeout, signal, nonzero exit, or malformed response without a verified issue URL leaves the attempt pending without a replay link, because the issue-creation outcome may be unknown. The action is tied to one update-attempt identity and cannot submit that attempt twice; reconnecting or refreshing status never reports it automatically. A CLI reporting error returns to the explicit action menu and never starts diagnosis on the user's behalf.

Control UI remediation uses typed product actions only. It leads with an authenticated Gateway or native action when the connected UI has the required capability and scope, preserves confirmations for disruptive operations, and keeps terminal commands as secondary host-side fallbacks. It never parses localized guidance or executes an arbitrary command string.

Recover in the Control UI

1. Select Check status when the Gateway restarted, disconnected, or did not report a final result. This reads update.status; it does not start another update. Recovery controls stay disabled while the check is pending, and a rejected request appears as an error on the page.
2. Open View details and address the recorded failing step. Diagnostic text is bounded and redacted for display; use Gateway logs when more context is required.
3. Select Retry update only after the cause is resolved. The Control UI uses the normal confirmed update flow and states that running sessions are interrupted while the Gateway restarts.

The controls require a connected Gateway, support for the corresponding typed Gateway method, and administrator scope. When those conditions are not met, use the CLI fallback on the Gateway host.

Reason codes

• dirty, no-upstream: repair the source checkout before retrying.
• plugin-target-unavailable: an enabled configured npm plugin has no resolvable target for the selected core, or its registry metadata could not be read. The refusal identifies the plugin, package target, and registry error before the serving Gateway stops or the core package changes. Retry after publication or registry recovery, use openclaw update --tag <older-version>, or disable the affected plugin and retry. If the core version is unknown, select an exact registry version. Extended-stable rejects --tag; retry later or explicitly switch channels. --dry-run performs the same availability check.
• preflight-insufficient-space: free space on the filesystems containing preflight staging (the checkout's .artifacts area on POSIX) and the package-manager store, then retry. The updater stops on confirmed ENOSPC instead of trying older commits; it does not delete shared package-manager stores. See Git checkout flow for staging placement and the older published-updater limitation.
• deps-install-failed, build-failed, ui-build-failed: inspect the failing step, fix the dependency or build error, then retry.
• global-install-failed: retry after checking package-manager ownership and permissions. Re-run the installer if the package install is incomplete.
• doctor-failed: run openclaw doctor on the Gateway host, resolve its findings, then retry. See Doctor for the check list and --fix behavior.
• restart-disabled, restart-unavailable: restore a supported supervisor or enable Gateway restarts before retrying.
• restart-unhealthy, restart-revision-mismatch, restart-revision-unavailable: inspect Gateway service health and its install root before retrying.
• managed-service-handoff-*: check status first. If the handoff stopped, use the CLI on the Gateway host to preserve the full diagnostic output.

Unknown reason codes remain visible. Check the Gateway logs before retrying.

CLI fallback

Run these commands on the Gateway host, not on the computer that merely has the Control UI open:

openclaw update status --jsonopenclaw triage

Use openclaw update --dry-run to preview a new attempt. If a package update failed after installation began, follow the installer recovery steps in Updating.

If the installed CLI is damaged or the filesystem cannot write diagnostics, automatic triage reports that failure and preserves the original update error. Repair the installed command, then run openclaw triage. Managed updates retain their detached helper log even when the Gateway cannot start; the recorded outcome points to the available diagnostics or the failed collection attempt. Restart notices summarize the diagnostic outcome. Saved artifact paths and exact, installation-specific recovery commands remain in the host command output or managed update helper log rather than the notice sent to an agent or channel.

If the updater crashes or is killed after the Gateway stops, the Gateway stays stopped unless the updater completed and verified recovery. Inspect openclaw gateway status --deep, repair the reported dependency or installation failure, and rerun openclaw update. A failed Git dependency install restores and rebuilds the previous runtime before allowing an automatic restart. Restarts after verified recovery still check the installed configuration, service ownership, and Gateway health.

Rollback boundary

Do not restore state as the first response to an update failure. First reinstall known-good code while preserving current state. Restore a verified pre-update state snapshot only when older code cannot read the current config or database. See Rollback.

Support diagnostics

Collect the following without posting credentials, raw config, or unredacted process output:

• OpenClaw version and install type;
• update timestamp, target, phase, and reason code from Settings → Updates;
• the bounded failure detail shown by View details;
• openclaw update status --json;
• openclaw gateway status --deep --json;
• relevant redacted Gateway log lines.