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).

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/

Backup:

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

This contains secrets. Store it securely.

2) Update (global installs)

npm i -g openclaw@latest

Then run checks and restart:

openclaw doctor
openclaw gateway restart
openclaw health

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

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.