Updating and Migrating OpenClaw Safely (No Surprises)

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

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