Updating and Migrating OpenClaw Safely (No Surprises)

What this guide helps you finish

By the end of this guide, you should be able to update or migrate OpenClaw without losing credentials, sessions, or gateway service continuity, and know exactly how to roll back if the change goes bad.

Who this is for (and not for)

This guide is for operators changing versions, runtimes, or machines while trying to keep a working OpenClaw instance intact.

It is not the best page if the system is already broken in one narrow way and you need symptom-first troubleshooting.

Before you touch the install: collect these four facts

Before you update or migrate, write down:

1. where the real state directory lives,
2. which install method currently owns the running gateway,
3. which version/channel you can roll back to if needed,
4. one real workflow you will use as the post-change verification test.

That turns the change from “upgrade and hope” into a recoverable operation.

Why updates break (and how to avoid it)

OpenClaw moves fast. Most “update regressions” are actually one of these:

• You updated the binary but your gateway service is still pointing at an old path/runtime.
• You have multiple installs (brew/node version manager) and launchd/systemd is using a different PATH.
• You partially migrated state (copied config but not credentials/sessions).

And if the breakage shows up specifically in:

• custom provider / relay traffic, read /guides/openclaw-relay-and-api-proxy-troubleshooting
• host exec / node-host command behavior, read /guides/openclaw-exec-approvals-and-safe-bins

Official references:

• Updating guide: https://docs.openclaw.ai/install/updating
• Gateway runbook: https://docs.openclaw.ai/gateway

1) Snapshot state (do not skip this)

Default state directory:

• ~/.openclaw/

On 2026.3.8+, prefer the built-in backup command:

openclaw backup create --verify

Useful variants:

openclaw backup create --only-config --verify
openclaw backup create --no-include-workspace --verify
openclaw backup create --dry-run --json

If you are on an older build or want a second belt-and-suspenders copy, a manual archive still helps:

tar -czf openclaw-state-backup.tgz ~/.openclaw

This contains secrets. Store it securely.

Deep dive:

• /guides/openclaw-backup-and-rollback

2) Update (global installs)

npm i -g openclaw@latest

Then run checks and restart:

openclaw doctor
openclaw gateway restart
openclaw health

If you are on macOS and the update path leaves the service disabled or half-recovered, use the boring recovery path:

openclaw gateway install --force
openclaw gateway restart

2.5) Roll back / pin (when something breaks)

If an update breaks a critical workflow, rolling back to a known-good version is often faster than trying to “repair forward” under pressure.

Pin the last working version (replace <version>):

npm i -g openclaw@<version>

Then run the same verification loop:

openclaw doctor
openclaw gateway restart
openclaw health

If rollback causes “config was written by a newer OpenClaw” warning spam

After a downgrade, you may see warnings like:

Config was last written by a newer OpenClaw (...); current version is ...

Some builds have emitted that warning on every CLI invocation.

Practical fixes:

1. Preferred: pick one version and align everything (re-upgrade when possible).
2. If you must stay downgraded, make the downgraded version rewrite the config metadata once:

openclaw config unset meta.lastTouchedVersion
openclaw gateway restart

If config unset can’t reach the field in your version, open your config file and delete the meta.lastTouchedVersion entry manually, then restart the gateway.

3) Update (from source)

If you installed from a git checkout, prefer:

openclaw update

That flow is designed to build, run checks, and restart safely.

4) If the gateway service is “running” but the port is dead

This often means the service is installed but pointing at the wrong runtime or a stale path.

Try:

openclaw gateway status
openclaw gateway install --force
openclaw gateway restart

Then re-open the dashboard:

openclaw dashboard

If your setup depends on a remote gateway plus a browser on another machine, also verify the browser-node topology after the upgrade:

• /guides/openclaw-remote-browser-node-host

5) Migration: copy the entire state directory

Migration should be boring:

1. Stop the gateway on the old machine.
2. Copy the full state directory to the new machine.
3. Install OpenClaw on the new machine.
4. Install/restart the service and verify health.

Example (SSH):

# On the new machine, pull from old:
rsync -a --progress user@old-host:~/.openclaw/ ~/.openclaw/

# Install OpenClaw (global):
npm install -g openclaw@latest

# Ensure the service is installed and running:
openclaw gateway install --force
openclaw gateway restart
openclaw health

5.5) Verification after the change

Do not stop at “the service restarted.” Verify:

• openclaw health passes
• one real chat or workflow still works
• one credentialed surface still authenticates cleanly
• the gateway service is using the runtime and path you think it is using
• your rollback path still exists if something fails later

6) What not to do

• Do not copy only openclaw.json and call it a migration.
• Do not delete ~/.openclaw/ as a first-line fix; you will lose creds and sessions.
• Do not expose the Control UI publicly while debugging auth; use SSH tunnel or Tailscale instead.

7) A practical 2026.3.8+ operator checklist

When upgrading modern OpenClaw builds, the safest order is:

1. openclaw backup create --verify
2. openclaw doctor
3. upgrade (npm i -g openclaw@latest or openclaw update)
4. openclaw doctor
5. openclaw gateway restart
6. openclaw health

If something feels wrong after the upgrade, prefer these before deeper surgery:

• openclaw gateway status
• openclaw gateway install --force
• openclaw gateway restart
• and a single real workflow test (one chat, one tool, one channel) instead of broad guesswork.

Then branch by symptom instead of guessing:

• provider / 403 / proxy weirdness → /guides/openclaw-relay-and-api-proxy-troubleshooting
• browser lives on another machine → /guides/openclaw-remote-browser-node-host
• host exec policy suddenly feels stricter than expected → /guides/openclaw-exec-approvals-and-safe-bins