Neura Market Logo

OpenClaw Migration Guide: Import, Move, or Upgrade

Learn how to migrate data from other agent systems, move OpenClaw to new hardware, or upgrade plugins without reinstalling. Includes steps for importing from Claude and Hermes.

Read this when

  • You are moving OpenClaw to a new laptop or server
  • You are coming from another agent system and want to keep state
  • You are upgrading an in-place plugin

OpenClaw provides three ways to migrate: bringing in data from a different agent system, relocating an existing setup to different hardware, or updating a plugin without reinstalling.

Import from another agent system

Prepackaged migration providers transfer instructions, MCP servers, skills, model configuration, and (if you opt in) API keys into OpenClaw. You see a plan before anything changes, and secrets are hidden in reports. Standalone openclaw migrate relies on a verified backup; fresh onboarding instead stages and checks local artifacts before publishing them with configuration committed before any irreversible external activation takes effect.

  • Migrating from Claude, Bring over Claude Code and Claude Desktop data, such as CLAUDE.md, MCP servers, skills, and project commands.

  • Migrating from Hermes, Bring over Hermes configuration, providers, MCP servers, memory, skills, and supported .env keys.

The CLI command is openclaw migrate. Onboarding can also suggest migration when it identifies a known source (openclaw onboard --flow import).

Move OpenClaw to a new machine

Copy the state directory (defaults to ~/.openclaw/) and your workspace to keep:

  • Config, openclaw.json and all gateway settings.
  • Auth, per-agent auth-profiles.json (API keys plus OAuth), plus any channel or provider state under credentials/.
  • Sessions, conversation history and agent state.
  • Channel state, WhatsApp login, Telegram session, and similar.
  • Workspace files, MEMORY.md, USER.md, skills, and prompts.

Tip

Run openclaw status on the old machine to find your state directory path. Custom profiles use ~/.openclaw-<profile>/ or a path set via OPENCLAW_STATE_DIR.

Migration steps

Stop the gateway and back up

On the old machine, stop the gateway so files are not changing during the copy, then create an archive:

openclaw gateway stop
cd ~
tar -czf openclaw-state.tgz .openclaw

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

Install OpenClaw on the new machine

Install the CLI (and Node if needed) on the new machine. It is acceptable if onboarding creates a fresh ~/.openclaw/, you will overwrite it next.

Copy state directory and workspace

Move the archive using scp, rsync -a, or an external drive, then unpack it:

cd ~
tar -xzf openclaw-state.tgz

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

Run doctor and verify

On the new machine, run Doctor to apply config migrations and fix services:

openclaw doctor
openclaw gateway restart
openclaw status

If Telegram or Discord uses the default env fallback (TELEGRAM_BOT_TOKEN or DISCORD_BOT_TOKEN), check that the migrated state-dir .env contains those keys without printing the secret values:

awk -F= '/^(TELEGRAM_BOT_TOKEN|DISCORD_BOT_TOKEN)=/ { print $1 "=present" }' ~/.openclaw/.env

openclaw doctor also alerts you when an enabled default Telegram or Discord account has no configured token and the matching env variable is not available to the doctor process.

Common pitfalls

Profile or state-dir mismatch

If the old gateway used --profile or OPENCLAW_STATE_DIR and the new one does not, channels will appear logged out and sessions will be empty. Start the gateway with the same profile or state-dir you migrated, then run openclaw doctor again.

Copying only openclaw.json

The config file alone is insufficient. Model auth profiles live under agents/<agentId>/agent/auth-profiles.json, and channel and provider state lives under credentials/. Always migrate the entire state directory.

Permissions and ownership

If you copied as root or switched users, the gateway may fail to read credentials. Ensure the state directory and workspace are owned by the user running the gateway.

Remote mode

If your UI points at a remote gateway, the remote host owns sessions and workspace. Migrate the gateway host itself, not your local laptop. See FAQ.

Secrets in backups

The state directory contains auth profiles, channel credentials, and other provider state. Store backups encrypted, avoid insecure transfer channels, and rotate keys if you suspect exposure.

Verification checklist

On the new machine, verify:

  • 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 keep the same plugin id and config keys but may rearrange 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.