Recover from Failed OpenClaw Updates: Control UI & CLI

Start from Control UI → Settings → Updates. That screen pulls the most recent update attempt recorded by the connected Gateway and displays its timestamp, target, reason code, failed step, and a limited amount of diagnostic information.

Remediation through the Control UI relies exclusively on typed product actions. It begins with an authenticated Gateway or native action whenever the connected UI possesses the necessary capability and scope, keeps confirmations in place for disruptive operations, and treats terminal commands as a secondary fallback on the host side. Localized guidance is never parsed, and arbitrary command strings are never executed.

Recover in the Control UI

1. Choose Check status if the Gateway restarted, lost its connection, or failed to deliver a final result. This action reads update.status; it does not trigger a fresh update. While the check is in progress, recovery controls remain disabled, and a rejected request shows up as an error on the page.
2. Open View details and tackle the step that failed. Diagnostic text is capped and scrubbed for display; turn to Gateway logs when you need deeper context.
3. Click Retry update only once the underlying cause has been fixed. The Control UI follows the standard confirmed update process and notes that active sessions get interrupted while the Gateway restarts.

These controls depend on a connected Gateway, support for the matching typed Gateway method, and administrator privileges. If any of those are missing, fall back to the CLI on the Gateway host.

Reason codes

• dirty, no-upstream: fix the source checkout before attempting again.
• deps-install-failed, build-failed, ui-build-failed: look at the failing step, correct the dependency or build issue, then try again.
• global-install-failed: retry after verifying package-manager ownership and permissions. If the package install is partial, rerun the installer.
• doctor-failed: execute Doctor on the Gateway host, address whatever it reports, then retry.
• restart-disabled, restart-unavailable: bring back a supported supervisor or allow Gateway restarts before retrying.
• restart-unhealthy, restart-revision-mismatch, restart-revision-unavailable: check Gateway service health and its install root before retrying.
• managed-service-handoff-*: check status first. If the handoff stopped, run the CLI on the Gateway host to keep the full diagnostic output.

Unknown reason codes stay visible. Consult the Gateway logs prior to retrying.

CLI fallback

Execute these commands on the Gateway host, not on the machine that only has the Control UI open:

openclaw update status --json
openclaw doctor --non-interactive
openclaw update

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

Rollback boundary

Do not make state restoration your first move after an update failure. Start by reinstalling known-good code while keeping the current state intact. Only restore a verified pre-update state snapshot when older code cannot read the current config or database. See Rollback.

Support diagnostics

Gather the following without sharing 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 from View details;
• openclaw update status --json;
• openclaw gateway status --deep --json;
• relevant redacted Gateway log lines.