What this page covers: channels, leftovers, and rollback
If OpeClaw used to run, but “Check for updates” fails, the progress bar stalls, the version never changes, or the first launch after update crashes—you are usually dealing with the update channel and config leftovers, not first-install antivirus blocks.
The won’t-open guide covers antivirus, .NET/VC++, and Gatekeeper. This article stays on failed updates, post-update breakage, version checks, rollback, and clean reinstall. 401/429 still go to the API key article; package source stays on the download page.
On update failure, verify version and channel first
From About or Settings, note the current version and build date, then compare with the download page’s release status. If the client shows 1.x while the download page lists another build—and in-app update still fails—the channel is often unreachable or the package failed verification, not “the app is corrupted.”
Fixed order: stop rapid retries → read whether the toast is timeout, checksum failure, or permissions → open the download page in a normal browser for the matching platform installer. Corporate networks that block update hosts make in-app updates fail forever; a manual install is often more stable.
If the version already matches yet the client still offers an update, an old manifest may be cached. Quit and relaunch, or wait for the manifest refresh—do not keep overlay-installing half packages.
- Record current version and platform (Windows / macOS / Linux).
- Compare with download-page status: should you update, and to which build?
- Separate “channel failed” from “package landed but launch is broken.”
After update: leftovers beat “just install again”
Update finishes but the app won’t open, settings are blank, Skills are gray, or Providers vanish—often the old config directory no longer matches new fields, or the updater swapped the binary while leaving a half cache.
Do not uninstall yet: export or copy API keys, prompt paths, and Skill source notes. Quit the client, check for leftover updater processes locking files, then relaunch once and confirm the version actually changed.
If the version is new but the UI is still wrong, back up and clear the config directory before starting again (same paths as the won’t-open guide: Windows `%AppData%/OpeClaw`, macOS `~/Library/Application Support/OpeClaw`) so the new build can write a clean profile. That beats looping auto-update.
Rollback: when to stop updating and return to a known build
If the new build crashes immediately or kills your core workflow—and an older install or installer still exists—roll back for productivity first, then debug the channel. Rollback is not a forever ban on updates; it puts “works” ahead of “newest.”
Uninstall the broken build (or overlay-install a known-good older package) → confirm About shows the expected version → restore Providers and required paths from backup. If the old package is gone, check whether the download page still lists that platform entry; do not pull mystery builds from random drives.
After rollback, model-only failures go to API key / quota; a UI that never starts should be read alongside the won’t-open runtime and permission steps—without rewriting the full antivirus primer here.
Clean reinstall: clear leftovers, then take the package from Download
When auto-update fails repeatedly, rollback still misbehaves, or the config directory is too messy to reason about: uninstall → delete config leftovers (after backing up keys) → fetch the current platform installer from the download page → after install, run one short test before re-adding Skills and long workflows.
Clean reinstall fixes client/config consistency. It does not fix vendor quota, proxy certificates, or antivirus quarantine. If double-click still does nothing, use the won’t-open guide; if the UI works but you see 401/429, use the API key article.
Trust size and checksum notes on the download page. Chat-group “latest cracked update packs” break version checks and mix update failure with tampered binaries.
How this splits from “won’t open”
Never launched successfully, antivirus quarantine, missing runtimes, Gatekeeper “damaged” → won’t-open troubleshooting.
Used to work; failure is on check-for-update / applying update / first launch after update → stay here: verify version, clear leftovers, roll back, or clean-reinstall.
Update succeeded, UI fine, only cloud calls fail → API key & quota. Platform package entry → download page; scenarios and permission boundaries → FAQ.
Update-failure checklist (no new claims)
This table only restates the splits above. It does not change “verify version before reinstall,” “leftover config before blind overwrite,” or “antivirus/runtime detail lives on the won’t-open guide.”
| Symptom | Do this first | Common mistake |
|---|---|---|
| Check for updates fails / times out | Stop retries; compare download page and network path | Retry loops that scramble half packages |
| Version unchanged after “update” | Confirm install finished; check locking processes | Assume success and keep a bad cache |
| Crash or blank settings after update | Back up, clear config, relaunch | Delete keys and Skills with no backup |
| New build unusable, old build exists | Roll back to a known-good build | Grab “older cracked packs” from unknown mirrors |
| Still won’t launch after reinstall | Won’t-open guide (AV / runtimes) | Stay only inside the update channel |
| 401/429 only after reinstall | API key & quota article | Clean-reinstall again hoping to fix billing |
Menu labels and paths follow the current client and download page; this article does not promise forced update pushes or support SLAs.
Update failure & clean reinstall FAQ
Can I keep using the old build after an OpeClaw update fails?
Usually yes. Confirm the old install and config are intact before deciding to roll back. Do not hammer “Retry” on a half-finished update and scramble leftover files.
Is “won’t open after update” the same checklist as “won’t open after install”?
Not quite. Fresh install failures lean antivirus, runtimes, and Gatekeeper. Post-update failures lean version checks, update channels, and leftover config—then a clean reinstall. Use the won’t-open guide for the antivirus deep dive.
Should a clean reinstall delete my API keys?
No. Back up or copy Provider settings first, clear client leftovers, then paste the same keys after reinstall. Persistent 401/429 belongs on the API key & quota article—not another reinstall loop.
Where should I get packages for rollback or clean reinstall?
Return to this site’s download page for current release status and platform builds. Avoid chat-forwarded short links or unknown mirrors when versions do not match.
Use this with an OpeClaw workflow
Check the current OpeClaw download status first, then save this guide as part of your setup, review, or troubleshooting workflow.