What this page covers: backup and machine moves, not update channels
Searches for “OpeClaw config backup” or “migrate to a new PC” usually mean a working workflow already exists, and the risk is losing Providers, prompt paths, and Skills source notes after a reinstall or hardware swap.
This article covers: what to keep from the local config directory, how to copy safely or use export/import if your current build offers it, and the restore order that brings workflows back. Update failures, half-finished updates, and version mismatches → update-fail guide. Local folder reads failing → workspace guide.
It does not invent unpublished “one-click cloud sync for all settings.” Whether export exists, what the button is called, and how fields are named all follow your current Settings and About pages.
Before backup: list what must travel with you
A minimum list usually includes: API / Provider keys or placeholders (prefer a password manager—never paste into chat groups), notes on custom prompt or template paths, Skills sources and version notes you rely on, absolute workspace paths to rebuild on the new machine, and the About-page version string.
Config locations commonly match those used when clearing leftovers: Windows often `%AppData%/OpeClaw`, macOS often `~/Library/Application Support/OpeClaw`. If your machine differs, trust the current build’s docs or an “Open config folder” style entry—do not guess paths hard-coded in third-party scripts.
Installer source and which build to install start on the download page. Backup means recoverable settings—not carrying an unknown installer package.
- Quit the client fully before copying the config folder to avoid half-written files.
- Keep keys separate from the config archive so a lost USB stick does not leak both.
- Record old workspace paths; the new machine will often need a fresh folder pick.
Export / copy: follow the current build’s entry points
If Settings offers export, backup, or migrate-style wizards, follow those dialogs and finish before you shut down or uninstall. If no such entry exists, copy the whole config folder with the OS file manager onto encrypted media—that is a local backup, not a claim that account-based cloud sync exists.
After copying, spot-check: settings files present, archive size not suspiciously tiny (empty shell). Do not edit settings while a copy is in progress on a running client.
On managed PCs that block Application Support / AppData, ask IT or export to an allowed user folder. Disabling security tools to force a copy is outside this guide’s recommendations.
After reinstall or a new machine: restore order beats blind overwrite
Fixed order: install the current same-platform build from the download page → first launch without long workflows → import if the UI offers it, otherwise quit and place the config folder back → relaunch and confirm About version plus Providers.
Then run a minimum proof: one short chat or one read-only local-file step. Only then re-enable Skills and full workflows. Overwriting a still-running or half-broken directory mixes old and new fields.
If the client will not open after restore, separate corrupt config from install/antivirus issues: won’t-open guide for launch failures; update-fail if the channel is the problem. Do not spam Check for Update as a migration fix.
Workflow recovery: paths, permissions, and splits
Config restored but project files still unread—usually the path changed or grants were never re-approved. Re-select the folder and finish permission dialogs per the local workspace guide; do not delete the backup you just restored.
Skills listed but inert: verify source and whether the OS blocks them on the new machine—details on the Skills article. Model 401/429 → API key guide; proxy reachability → proxy guide.
Whether a local assistant fits your scenario and permission boundaries → FAQ. Success means the short proof passes, not merely that files were copied.
How this splits from update-fail, clean uninstall, and workspace
Planned machine move, backup before reinstall, export-then-install → stay on this page.
Check-for-update failures, post-update crashes, half packages, version mismatch → update-fail / clean reinstall; still take a backup first when you can.
Want a clean remove, verify AppData / Application Support leftovers, wipe before reinstall without keeping settings → clean-uninstall guide. Only a folder will not read, or permission prompts → local workspace. Installer entry → Download. Scenario boundaries → FAQ.
Config backup / migrate table (no new claims)
This table only restates the order above. It does not change “local config folder + current UI entries,” “no invented cloud sync,” or the split that keeps update-channel problems on the update-fail URL.
| Symptom | Safer action | Common mistake |
|---|---|---|
| Fear losing workflows on a new PC | List items; copy config / use export if present | Assuming unpublished cloud sync |
| Providers empty after reinstall | Quit client, then restore the config folder | Overwriting half-written files while running |
| Config OK, files unread | Workspace guide: re-pick path and grants | Deleting the backup hoping a reset restores files |
| Restore works but updates fail | Update-fail guide | Reusing migration backups as update patches |
| Unsure which build to install | Match Download page release status | Chat-group “migration cracked packages” |
Menu names, export entries, and real config paths follow the current client; this page does not promise unpublished sync or support SLAs.
Config backup & migrate FAQ
Does OpeClaw offer official cloud sync so a new PC restores config automatically?
This guide does not assume unpublished cloud sync. Treat migration as a local config-folder copy, plus any export/import entry your current build exposes, and hand-copied keys. Menu labels follow the build you have installed.
Is backing up the same as clearing leftovers after a failed update?
No. Clearing leftovers is a repair step when an update goes wrong. Backup/migrate is a deliberate save before you reinstall or switch machines. Channel stalls, half-finished packages, and version mismatches belong on the update-fail guide; a deliberate clean wipe before reinstall belongs on the clean-uninstall guide—do not treat “delete config and hope” as migration.
I restored the config folder but still cannot read project files—why?
Config usually stores path references, not the whole project tree. On the new machine, re-select the real folder and complete permission dialogs. Path and grant details stay on the local workspace guide.
Where should I get the installer after migrating?
Use this site’s download page to match platform release status and packages—avoid chat-group short links. Restore config after install, then run a short proof. Scenario boundaries → FAQ.
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.