Migration guide

OpenClaw supports three migration paths: importing from another agent system, moving an existing install to a new machine, and upgrading a plugin in place.

Import from another agent system

Use the bundled migration providers to bring instructions, MCP servers, skills, model config, and (opt-in) API keys into OpenClaw. Plans are previewed before any change, secrets are redacted in reports, and apply is backed by a verified backup.

The CLI entry point is

Move OpenClaw to a new machine

Copy the state directory (

• Config —
  text

  Copy

  openclaw.json
  and all gateway settings.
• Auth — per-agent
  text

  Copy

  auth-profiles.json
  (API keys plus OAuth), plus any channel or provider state under
  text

  Copy

  credentials/
  .
• Sessions — conversation history and agent state.
• Channel state — WhatsApp login, Telegram session, and similar.
• Workspace files —
  text

  Copy

  MEMORY.md
  ,
  text

  Copy

  USER.md
  , skills, and prompts.

Migration steps

text
Copy
```bash}
openclaw gateway stop
cd ~
tar -czf openclaw-state.tgz .openclaw
```

If you use multiple profiles (for example `~/.openclaw-work`), archive each separately.

text
Copy
```bash}
cd ~
tar -xzf openclaw-state.tgz
```

Ensure hidden directories were included and file ownership matches the user that will run the gateway.

text
Copy
```bash}
openclaw doctor
openclaw gateway restart
openclaw status
```

Common pitfalls

Verification checklist

On the new machine, confirm:

• text

  Copy

  openclaw status
  shows the gateway running.
• Channels are still connected (no re-pairing needed).
• The dashboard opens and shows existing sessions.
• Workspace files (memory, configs) are present.

Upgrade a plugin in place

In-place plugin upgrades preserve the same plugin id and config keys but may move on-disk state into the current layout. Plugin-specific upgrade guides live alongside their channels:

• Matrix migration: encrypted-state recovery limits, automatic snapshot behavior, and manual recovery commands.

Related

• text

  Copy

  openclaw migrate
  : CLI reference for cross-system imports.
• Install overview: all installation methods.
• Doctor: post-migration health check.
• Uninstall: removing OpenClaw cleanly.