OpenClaw update failed

When an OpenClaw update fails, the docs’ answer is not a retry button but a sequence: recovery settles, then a built-in triage offers to investigate, and only after the cause is addressed does a retry make sense. The design is careful about authority, diagnostics never turn a failed update into a successful one, and about consent, nothing is launched or reported without a yes. Here is what the triage does in a terminal and in the Control UI, the three recovery controls, the failure report, and the reason codes with what each one asks you to fix.

The original update failure and exit status remain authoritative; diagnostics do not turn a failed update into a successful one.

The triage

• In an interactive terminal, OpenClaw shows the selected agent, the saved prompt path and the fact that your own account and tokens will be used, then asks before launching triage; only an explicit yes proceeds, and no answer within thirty seconds preserves the diagnostics and a manual recovery command instead.
• With the yes or JSON flags, or no terminal, eligible failures can start one owned automatic repair; other failures keep their diagnostics and hand-off commands, and the triage agent can be chosen with a flag.
• In the Control UI, a failed attempt opens Ask OpenClaw with its recorded details; a lost connection or a verification timeout is presented as an unknown outcome, and the tab remembers the last thirty-two investigated attempts per Gateway and profile so status checks and reloads do not resend them.

The attempt record and the report

The updates settings page keeps the latest recorded attempt visible: its time, the identities before and after, the reason code, the failing step and bounded diagnostic detail; an unknown verification outcome resolves when the expected version arrives or the attempt reports its final failure. For a final failed attempt, reporting is a separate action from retrying: it previews a bounded report with the version, platform, target, failed phase, sanitized diagnostics and verified rollback outcome, excludes secrets, chat content, raw logs, private paths and recovery commands, and submits nothing until an administrator confirms, through the existing GitHub CLI issue flow. Remediation uses typed product actions only, never a parsed command string.

Recovering

• Check status when the Gateway restarted, disconnected or never reported a final result; it reads the update status and does not start another update.
• View details and address the recorded failing step; diagnostic text is bounded and redacted, so use the Gateway logs for more.
• Retry update only after the cause is resolved; the Control UI uses the normal confirmed flow and warns that running sessions are interrupted while the Gateway restarts.
• The controls need a connected Gateway, support for the typed method and administrator scope; otherwise the CLI on the Gateway host is the fallback.

Updating OpenClaw is the ordinary update path this page sits behind, and OpenClaw logs explains where the fuller diagnostics live.

The reason codes

Each code names its fix: a dirty checkout or no upstream means repairing the source checkout; an unavailable plugin target means an enabled npm plugin has no resolvable target for the selected core, so retry after publication, pin an older tag or disable the plugin; insufficient preflight space means freeing the staging and package-store filesystems, because the updater stops on a confirmed out-of-space rather than trying older commits; dependency, build or UI build failures mean fixing that step; a failed global install means checking package-manager ownership or re-running the installer; a failed doctor means resolving its findings; and the restart codes mean restoring a supported supervisor or inspecting service health. OpenClaw plugins covers the allowlist rule behind the plugin code.

On Diali

On Diali an update that fails is our problem before it is yours: releases are tested on our own assistants first, rolled out per instance, and rolled back by us, so the triage in this post is the path you do not have to walk. Hosted OpenClaw on Diali is the assistant.

• Triage asks first; a failed update stays failed until it is fixed.
• Check status, view details, retry, in that order.
• The reason code is the fix list.