OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Maintenance

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

Bundled migration providers bring instructions, MCP servers, skills, model config, and (opt-in) API keys into OpenClaw. Plans are previewed before any change and secrets are redacted in reports. Standalone openclaw migrate is backed by a verified backup; fresh onboarding imports instead stage and verify local artifacts before publishing them with configuration committed before any irreversible external activation.

Migrating from Claude

Import Claude Code and Claude Desktop state, including CLAUDE.md, MCP servers, skills, and project commands.
Migrating from Hermes

Import Hermes config, providers, MCP servers, memory, skills, and supported .env keys.

The CLI entry point is openclaw migrate. Onboarding can also offer migration when it detects a known source (openclaw onboard --flow import).

Move OpenClaw to a new machine

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

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

Migration steps

  • Stop the gateway and back up

    On the old machine, stop the Gateway, then create and verify a portable archive:

    bash
    openclaw gateway stopmkdir -p ~/Backups/openclawopenclaw backup create --output ~/Backups/openclaw --verify

    Stop the Gateway before taking a machine-move snapshot. A raw copy of a changing SQLite database can capture mismatched database and WAL files; quiescing the Gateway also keeps the rest of the state tree stable. If you use multiple profiles, run the command once with each profile selected.

  • Install OpenClaw on the new machine

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

  • Transfer and restore to staging

    Transfer the generated .tar.gz archive via scp, an external drive, or another protected channel. On the new machine, restore it to a fresh staging directory:

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

    Restore never activates in place. With the Gateway stopped, use the restored manifest.json mapping to move the state and workspace assets to their recorded destinations, or point OPENCLAW_STATE_DIR at the restored state asset. Confirm ownership matches the user that will run the Gateway.

  • Run doctor and verify

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

    bash
    openclaw doctoropenclaw gateway restartopenclaw status

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

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

    openclaw doctor also warns 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 appear logged out and sessions will be empty. Launch the gateway with the same profile or state-dir you migrated, then rerun openclaw doctor.

    Copying only openclaw.json

    The config file alone is not enough. 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, confirm:

    • [ ] 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.
    Was this useful?
    On this page

    On this page