Neura Market Logo

OpenClaw Migration Guide: Import, Move, and Upgrade

Learn how to migrate to OpenClaw from other agent systems, move an existing setup to new hardware, or upgrade plugins. This guide is for users planning any of these transitions.

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 offers three ways to migrate: bringing data over from a different agent system, relocating an existing setup to different hardware, and updating a plugin without removing it.

Import from another agent system

The migration providers bundled with OpenClaw carry over instructions, MCP servers, skills, model configuration, and API keys when you opt in. Plans are shown for review before anything changes, and reports hide secret values. Standalone openclaw migrate relies on a verified backup; fresh onboarding instead stages and checks local artifacts, then commits configuration before any irreversible external activation occurs.

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

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

The command-line entry point is openclaw migrate. Onboarding may also present migration when it recognizes a known source (openclaw onboard --flow import).

Move OpenClaw to a new machine

Copy the state directory (~/.openclaw/ by default) and your workspace to keep these items:

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

Tip

Run openclaw status on the old machine to verify where your state directory lives. Custom profiles use ~/.openclaw-<profile>/ or a path defined with OPENCLAW_STATE_DIR.

Migration steps

Stop the gateway and back up

On the old machine, halt the Gateway, then generate and validate a portable archive:

openclaw gateway stop
mkdir -p ~/Backups/openclaw
openclaw backup create --output ~/Backups/openclaw --verify

Halt the Gateway before you take a machine-move snapshot. Copying a live SQLite database directly can leave mismatched database and WAL files; stopping the Gateway also keeps the rest of the state tree consistent. With multiple profiles, execute the command once per selected profile.

Install OpenClaw on the new machine

Install the CLI (and Node if required) on the new machine. It is acceptable if onboarding creates a fresh ~/.openclaw/, you replace it in the next step.

Transfer and restore to staging

Move the generated .tar.gz archive using scp, an external drive, or another secure channel. On the new machine, unpack it into a clean staging directory:

openclaw backup restore <archive.tar.gz> --target ~/openclaw-restored

Restore does not activate anything in place. With the Gateway stopped, apply the restored manifest.json mapping to relocate state and workspace assets to their intended paths, or set OPENCLAW_STATE_DIR to the restored state asset. Verify ownership matches the user who will run the Gateway.

Warning

Restoring older channel state can break ratcheting credentials like WhatsApp. Approvals and delivery/dedupe state also revert, and plugin node_modules trees must be reinstalled. See Restore a full archive.

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 relies on the default env fallback (TELEGRAM_BOT_TOKEN or DISCORD_BOT_TOKEN), check that the migrated state-dir .env holds those keys without displaying the secret values:

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

openclaw doctor also alerts when an enabled default Telegram or Discord account has no configured token and the matching env variable is unavailable 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 show as 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 will not suffice. Model auth profiles reside 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 changed users, the gateway may not read credentials. Make sure 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 holds sessions and workspace. Migrate the gateway host itself, not your local laptop. See FAQ.

Secrets in backups

The state directory holds auth profiles, channel credentials, and other provider state. Keep 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 shift on-disk state into the current layout. Plugin-specific upgrade guides sit alongside their channels:

  • Matrix migration: encrypted-state recovery limits, automatic snapshot behavior, and manual recovery commands.
872 words · updated Aug 14, 2026