Skip to main content

​
Migrating OpenClaw to a new machine

This guide migrates a OpenClaw Gateway from one machine to another without redoing onboarding. The migration is simple conceptually:
  • Copy the state directory ($OPENCLAW_STATE_DIR, default: ~/.openclaw/) — this includes config, auth, sessions, and channel state.
  • Copy your workspace (~/.openclaw/workspace/ by default) — this includes your agent files (memory, prompts, etc.).
But there are common footguns around profiles, permissions, and partial copies.

​
Before you start (what you are migrating)

​
1) Identify your state directory

Most installs use the default:
  • State dir: ~/.openclaw/
But it may be different if you use:
  • --profile <name> (often becomes ~/.openclaw-<profile>/)
  • OPENCLAW_STATE_DIR=/some/path
If you’re not sure, run on the old machine: 
openclaw status
Look for mentions of OPENCLAW_STATE_DIR / profile in the output. If you run multiple gateways, repeat for each profile.

​
2) Identify your workspace

Common defaults:
  • ~/.openclaw/workspace/ (recommended workspace)
  • a custom folder you created
Your workspace is where files like MEMORY.md, USER.md, and memory/*.md live.

​
3) Understand what you will preserve

If you copy both the state dir and workspace, you keep:
  • Gateway configuration (openclaw.json)
  • Auth profiles / API keys / OAuth tokens
  • Session history + agent state
  • Channel state (e.g. WhatsApp login/session)
  • Your workspace files (memory, skills notes, etc.)
If you copy only the workspace (e.g., via Git), you do not preserve:
  • sessions
  • credentials
  • channel logins
Those live under $OPENCLAW_STATE_DIR.

​
Step 0 — Make a backup (old machine)

On the old machine, stop the gateway first so files aren’t changing mid-copy: 
openclaw gateway stop
(Optional but recommended) archive the state dir and workspace: 
# Adjust paths if you use a profile or custom locations
cd ~
tar -czf openclaw-state.tgz .openclaw

tar -czf openclaw-workspace.tgz .openclaw/workspace
If you have multiple profiles/state dirs (e.g. ~/.openclaw-main, ~/.openclaw-work), archive each.

​
Step 1 — Install OpenClaw on the new machine

On the new machine, install the CLI (and Node if needed): At this stage, it’s OK if onboarding creates a fresh ~/.openclaw/ — you will overwrite it in the next step.

​
Step 2 — Copy the state dir + workspace to the new machine

Copy both:
  • $OPENCLAW_STATE_DIR (default ~/.openclaw/)
  • your workspace (default ~/.openclaw/workspace/)
Common approaches:
  • scp the tarballs and extract
  • rsync -a over SSH
  • external drive
After copying, ensure:
  • Hidden directories were included (e.g. .openclaw/)
  • File ownership is correct for the user running the gateway

​
Step 3 — Run Doctor (migrations + service repair)

On the new machine: 
openclaw doctor
Doctor is the “safe boring” command. It repairs services, applies config migrations, and warns about mismatches. Then: 
openclaw gateway restart
openclaw status

​
Common footguns (and how to avoid them)

​
Footgun: profile / state-dir mismatch

If you ran the old gateway with a profile (or OPENCLAW_STATE_DIR), and the new gateway uses a different one, you’ll see symptoms like:
  • config changes not taking effect
  • channels missing / logged out
  • empty session history
Fix: run the gateway/service using the same profile/state dir you migrated, then rerun: 
openclaw doctor

​
Footgun: copying only openclaw.json

openclaw.json is not enough. Many providers store state under:
  • $OPENCLAW_STATE_DIR/credentials/
  • $OPENCLAW_STATE_DIR/agents/<agentId>/...
Always migrate the entire $OPENCLAW_STATE_DIR folder.

​
Footgun: permissions / ownership

If you copied as root or changed users, the gateway may fail to read credentials/sessions. Fix: ensure the state dir + workspace are owned by the user running the gateway.

​
Footgun: migrating between remote/local modes

  • If your UI (WebUI/TUI) points at a remote gateway, the remote host owns the session store + workspace.
  • Migrating your laptop won’t move the remote gateway’s state.
If you’re in remote mode, migrate the gateway host.

​
Footgun: secrets in backups

$OPENCLAW_STATE_DIR contains secrets (API keys, OAuth tokens, WhatsApp creds). Treat backups like production secrets:
  • store encrypted
  • avoid sharing over insecure channels
  • rotate keys if you suspect exposure

​
Verification checklist

On the new machine, confirm:
  • openclaw status shows the gateway running
  • Your channels are still connected (e.g. WhatsApp doesn’t require re-pair)
  • The dashboard opens and shows existing sessions
  • Your workspace files (memory, configs) are present