openclaw migrate Command Reference

`openclaw migrate`

Bring in state from a different agent system using a migration provider supplied by a plugin. The providers that ship with the tool handle Claude, Codex CLI, and Hermes; extra providers can be registered through plugins.

Tip

Step-by-step guides aimed at users live at Migrating from Claude and Migrating from Hermes. Every available path is collected on the migration hub.

Commands

openclaw migrate list
openclaw migrate claude --dry-run
openclaw migrate codex --dry-run
openclaw migrate codex --skill gog-vault77-google-workspace
openclaw migrate codex --plugin google-calendar --dry-run
openclaw migrate codex --plugin google-calendar --verify-plugin-apps --dry-run
openclaw migrate hermes --dry-run
openclaw migrate hermes
openclaw migrate apply codex --yes --skill gog-vault77-google-workspace
openclaw migrate apply codex --yes --plugin google-calendar
openclaw migrate apply codex --yes
openclaw migrate apply claude --yes
openclaw migrate apply hermes --yes
openclaw migrate apply hermes --include-secrets --yes
openclaw onboard --flow import
openclaw onboard --import-from claude --import-source ~/.claude
openclaw onboard --import-from hermes --import-source ~/.hermes

Calling openclaw migrate <provider> without any other flags will plan, preview, and, when running in a TTY, ask for confirmation before it applies anything. The preview and apply phases can be split into separate subcommands using openclaw migrate plan <provider> and openclaw migrate apply <provider>, both of which accept the same set of flags.

true, " type="string"> The name of a registered migration provider, for instance hermes. Run openclaw migrate list to list which providers are installed.
--dry-run (boolean), Construct the plan and stop without touching any state.
true, " type="string"> Point the source state directory somewhere else. Hermes consults $HERMES_HOME plus the active profile, then falls back to the platform default (~/.hermes or %LOCALAPPDATA%\hermes). Codex uses ~/.codex (or $CODEX_HOME) by default, while Claude defaults to ~/.claude.
true, " type="string"> Bring the state into a specific configured agent. Leave this out only when the configured default agent should receive it. IDs that are invalid or unknown get rejected.
--include-secrets (boolean), Pull in supported credentials with no prompting. During interactive apply, you are asked before any detected auth credentials are imported, and yes is preselected; in non-interactive mode, --yes will not import them unless --include-secrets is given.
--no-auth-credentials (boolean), Leave auth credential import out entirely, including the interactive prompt.
--overwrite (boolean), Let apply overwrite existing targets when the plan flags conflicts.
--yes (boolean), Bypass the confirmation prompt. Mandatory when running non-interactively.
true, " type="string"> Pick a single skill copy item by its skill name or item id. Repeat this flag to move several skills at once. When it is absent, interactive Codex migrations present a checkbox selector, and non-interactive ones keep every planned skill.
true, " type="string"> Pick a single Codex plugin install item by its plugin name or item id. Repeat this flag to move multiple Codex plugins. When it is absent, interactive Codex migrations show a native Codex plugin checkbox selector, and non-interactive ones keep every planned plugin. It only applies to openai-curated Codex plugins installed from the source and discovered through the Codex app-server inventory.
true, " type="string"> Pick one exact migration item by its plan ID. Repeat this flag to move several items. As an example, --item auth:openai narrows a Codex migration down to the detected OpenAI credential item.
--verify-plugin-apps (boolean), Codex only. Before planning native plugin activation, a fresh source Codex app-server app/installed snapshot read is forced. Off by default so that planning stays quick.
true, " type="string"> A path or directory for the pre-migration backup archive. This is handed straight to openclaw backup create.
--no-backup (boolean), Do not create the pre-apply backup. When local OpenClaw state exists, --force becomes necessary.
--force (boolean), Needed together with --no-backup when apply would otherwise decline to skip the backup.
--json (boolean), Emit the plan or the apply result as JSON. When --json is present but --yes is not, apply prints the plan and leaves state untouched.

Safety model

openclaw migrate puts preview first.

Preview before apply

Before anything is altered, the provider hands back an itemized plan that includes conflicts, skipped items, and sensitive items. JSON plans, apply output, and migration reports redact nested keys that look secret, such as API keys, tokens, authorization headers, cookies, and passwords.

openclaw migrate apply <provider> previews the plan and asks before modifying state, unless --yes is set. When running non-interactively, apply needs --yes.

Backups

Apply builds and verifies an OpenClaw backup before it applies the migration. If no local OpenClaw state exists at that point, the backup step is omitted and the migration proceeds. To skip a backup when state does exist, supply both --no-backup and --force.

Conflicts

Apply stops when the plan contains conflicts. Look over the plan, then run it again with --overwrite if replacing existing targets is what you intend. Providers may still write item-level backups for overwritten files inside the migration report directory.

Secrets

Interactive apply asks whether detected auth credentials should be imported, with yes preselected. Use --no-auth-credentials to leave them out, or --include-secrets for unattended credential import together with --yes.

Claude provider

The bundled Claude provider looks for Claude Code state at ~/.claude by default. To bring in a particular Claude Code home or project root, pass --from <path>.

Tip

A step-by-step guide for users is available at Migrating from Claude.

What Claude imports

Claude Code auto-memory Markdown sourced from ~/.claude/projects/*/memory and a user-defined autoMemoryDirectory, placed under memory/imports/claude-code/ so it can be searched later.
Project CLAUDE.md and .claude/CLAUDE.md are moved into the OpenClaw agent workspace (AGENTS.md).
User ~/.claude/CLAUDE.md gets appended to workspace USER.md.
MCP server definitions taken from project .mcp.json, Claude Code ~/.claude.json (which includes its per-project entries), and Claude Desktop claude_desktop_config.json.
Claude skill directories containing SKILL.md (user ~/.claude/skills and project .claude/skills).
Claude command Markdown files (user ~/.claude/commands and project .claude/commands) become OpenClaw skills that can only be triggered manually.

Archive and manual-review state

The migration report keeps or flags for manual review these items: Claude hooks, permissions, environment defaults, project CLAUDE.local.md, .claude/rules, user and project agents/ directories, and project history (projects, cache, plans under ~/.claude). OpenClaw will not run hooks, copy broad allowlists, or automatically pull in OAuth or Desktop credential state.

Codex provider

Codex CLI state is detected at ~/.codex by the bundled Codex provider by default, or at CODEX_HOME when that environment variable is present. To inventory a particular Codex home, use --from <path>.

Pick this provider when you are switching to the OpenClaw Codex harness and want to intentionally carry over useful personal Codex CLI assets. Local Codex app-server launches rely on a per-agent CODEX_HOME, so your personal ~/.codex is not read by default. The standard process HOME is still passed down, which lets Codex access shared $HOME/.agents/* skills and plugin marketplace entries, and lets subprocesses locate user-home config and tokens.

Codex auth.json credentials count as sensitive inputs for migration. The default agent-scoped runtime does not directly use a copied or mounted auth.json; instead, explicitly import those credentials into the owning agent's OpenClaw auth store. Swap <agent-id> for the ID of that configured agent:

openclaw migrate plan codex --from <codex-home> --agent <agent-id> --include-secrets --item auth:openai
openclaw migrate apply codex --from <codex-home> --agent <agent-id> --include-secrets --item auth:openai --yes

When you run openclaw migrate codex in an interactive terminal, the full plan is previewed, then checkbox selectors appear before the final apply confirmation. Skill copy items are presented first. For bulk selection, use Toggle all on or Toggle all off. Press Space to toggle rows, or Enter to activate the highlighted row and move on. Planned skills begin checked, conflict skills begin unchecked, and Skip for now skips skill copies for this run while still advancing to plugin selection. If source-installed curated Codex plugins can be migrated and --plugin was not provided, the migration then asks for native Codex plugin activation by plugin name. Plugin items start checked unless the target OpenClaw Codex plugin config already contains that plugin. Existing target plugins start unchecked and display a conflict hint such as conflict: plugin exists; choose Toggle all off to migrate no native Codex plugins in that run, or Skip for now to halt before applying.

For scripted or exact runs, explicitly select one or more skills or plugins:

openclaw migrate codex --dry-run --skill gog-vault77-google-workspace
openclaw migrate apply codex --yes --skill gog-vault77-google-workspace
openclaw migrate codex --dry-run --plugin google-calendar
openclaw migrate apply codex --yes --plugin google-calendar

What Codex imports

Credentials for ChatGPT OAuth or the OpenAI API key, sourced from $CODEX_HOME/auth.json, enter the agent's OpenClaw auth store only when --include-secrets is enabled.
Codex MEMORY.md and memory_summary.md are consolidated from $CODEX_HOME/memories, placed under memory/imports/codex/ for indexed lookup. Raw rollout memory stays out of the import.
Codex CLI skill folders located in $CODEX_HOME/skills, with Codex's .system cache left out.
Personal AgentSkills from $HOME/.agents/skills get copied into the active OpenClaw agent workspace, giving each agent its own copy.
Source-installed openai-curated Codex plugins found via the Codex app-server plugin/installed. Planning consults plugin/read for every enabled installed plugin.

Extra checks apply when migrating app-backed plugins:

For app-backed plugins, the source Codex app-server account must belong to a ChatGPT subscription. Accounts without ChatGPT or missing responses are skipped with codex_subscription_required.
Migration skips reading the source app inventory by default, so app-backed plugins passing the account check are planned without verifying source app accessibility, and account-lookup transport errors are skipped with codex_account_unavailable.
Set --verify-plugin-apps to force a fresh source app/installed snapshot (including authorized metadata from batched app/read) and to demand that every owned app be present, enabled, and reachable before native activation is planned. In this mode, account-lookup transport failures fall back to source app-inventory verification. The snapshot lives only in memory for the current process; it never reaches migration output or target config.

Disabled plugins, plugin details that cannot be read, subscription-gated source accounts, and (when --verify-plugin-apps is set) missing, disabled, or unreachable apps become manually skipped items with typed reasons, not target config entries. Apply calls app-server plugin/install for each selected eligible plugin, even when the target app-server already lists that plugin as installed and enabled. Migrated Codex plugins work only in sessions that pick the native Codex harness; OpenClaw provider runs, ACP conversation bindings, and other harnesses do not see them.

Manual-review Codex state

Codex config.toml, native hooks/hooks.json, non-curated marketplaces, cached plugin bundles that are not source-installed curated plugins, and source-installed plugins failing the source subscription gate are never activated automatically. With --verify-plugin-apps set, plugins failing the source app-inventory gate are also omitted. All of these appear in the migration report, copied or noted, for manual handling.

For migrated source-installed curated plugins, apply writes:

plugins.entries.codex.enabled: true
plugins.entries.codex.config.codexPlugins.enabled: true
plugins.entries.codex.config.codexPlugins.allow_destructive_actions: true
one explicit plugin entry carrying marketplaceName: "openai-curated" and pluginName for each selected plugin

Migration never writes plugins["*"] and never records local marketplace cache paths.

Skipped plugins do not land in target config. Source-side subscription failures show up on manual items with typed reasons: codex_subscription_required, codex_account_unavailable, plugin_disabled, or plugin_read_unavailable. With --verify-plugin-apps, source app-inventory failures can also surface as app_inaccessible, app_disabled, app_missing, or app_inventory_unavailable. Target-side installs that need auth are flagged on the affected plugin item with status: "skipped", reason: "auth_required", and sanitized app identifiers; their explicit config entries are written disabled until you reauthorize and enable them. Other install failures come back as item-scoped error results.

When Codex app-server plugin inventory is unavailable during planning, migration falls back to cached bundle advisory items rather than failing the whole run.

Hermes provider

The bundled Hermes provider follows $HERMES_HOME and the active profile, then picks the platform default (~/.hermes or %LOCALAPPDATA%\hermes). Override discovery with --from <path>.

What Hermes imports

The default model setup, sourced from config.yaml.
Provider configurations and custom OpenAI-compatible endpoints defined in model, providers, and custom_providers.
MCP server definitions taken from mcp_servers or mcp.servers. Precise OpenClaw mappings handle default Streamable HTTP routing, OAuth scope, boolean TLS verification, separate client certificate and key paths, plus Hermes native, resource, and prompt tool policies. Any Hermes-only runtime or credential fields that are unsupported get flagged for manual handling.
SOUL.md and AGENTS.md are placed into the OpenClaw agent workspace.
memories/MEMORY.md and memories/USER.md get added to the workspace memory files. For memory-only surfaces, namely the onboarding memory page and the Control UI Memory import page, these files are instead copied under memory/imports/hermes/ for indexed recall, leaving existing workspace memory untouched.
Memory config defaults for OpenClaw file memory, along with archive or manual-review entries for external memory providers like Honcho.
Skills carrying a SKILL.md file anywhere beneath skills/; nested skills get flattened into the workspace skill directory.
Per-skill configuration values from skills.config.
Current Hermes OpenAI Codex OAuth credentials and OpenCode OpenAI OAuth credentials, provided interactive credential migration is accepted or --include-secrets is set. Avoid letting Hermes and OpenClaw share the same imported refresh grant.
Supported API keys and tokens from Hermes .env and OpenCode auth.json when interactive credential migration is accepted, or when --include-secrets is set.

Supported `.env` keys

AI_GATEWAY_API_KEY, ALIBABA_API_KEY, ANTHROPIC_API_KEY, ARCEEAI_API_KEY, CEREBRAS_API_KEY, CHUTES_API_KEY, CLOUDFLARE_AI_GATEWAY_API_KEY, COPILOT_GITHUB_TOKEN, DASHSCOPE_API_KEY, DEEPINFRA_API_KEY, DEEPSEEK_API_KEY, FIREWORKS_API_KEY, GEMINI_API_KEY, GH_TOKEN, GITHUB_TOKEN, GLM_API_KEY, GOOGLE_API_KEY, GROQ_API_KEY, HF_TOKEN, HUGGINGFACE_HUB_TOKEN, KILOCODE_API_KEY, KIMICODE_API_KEY, KIMI_API_KEY, KIMI_CODING_API_KEY, MINIMAX_API_KEY, MINIMAX_CODING_API_KEY, MISTRAL_API_KEY, MODELSTUDIO_API_KEY, MOONSHOT_API_KEY, NVIDIA_API_KEY, OPENAI_API_KEY, OPENCODE_API_KEY, OPENCODE_GO_API_KEY, OPENCODE_ZEN_API_KEY, OPENROUTER_API_KEY, QIANFAN_API_KEY, QWEN_API_KEY, TOGETHER_API_KEY, VENICE_API_KEY, XAI_API_KEY, XIAOMI_API_KEY, ZAI_API_KEY, Z_AI_API_KEY.

Archive-only state

Hermes state that OpenClaw cannot safely interpret is copied into the migration report for manual review, but it is not loaded into live OpenClaw config or credentials. This includes plugins/, sessions/, logs/, cron/, mcp-tokens/, plans/, workspace/, skins/, kanban/, pairing/platform state, gateway routing/process state, and the detected Hermes SQLite databases.

After applying

openclaw doctor

Plugin contract

Migration sources are plugins. A plugin declares its provider ids in openclaw.plugin.json:

{
  "contracts": {
    "migrationProviders": ["hermes"]
  }
}

During execution, the plugin invokes api.registerMigrationProvider(...). The provider supplies detect, plan, and apply. Core handles CLI orchestration, backup policy, prompts, JSON output, and conflict preflight. The reviewed plan is passed by Core into apply(ctx, plan), and providers can rebuild the plan only when that argument is missing for compatibility reasons. Migration items may set applyPhase: "after-promotion" for external activation effects that onboarding must postpone until staged local data is durably published. Those providers need to declare deferredApply: { retrySafe: true } and ensure each deferred effect can be safely replayed after an interrupted process; onboarding rejects undeclared deferred effects. An idempotent no-op should return a non-mutating item with deferredCompletion: true so recovery can mark it as complete. Standalone openclaw migrate still applies the complete plan through its normal backup-backed flow.

For item construction and summary counts, provider plugins can use openclaw/plugin-sdk/migration, plus openclaw/plugin-sdk/migration-runtime for conflict-aware file copies, archive-only report copies, cached config-runtime wrappers, and migration reports.

Onboarding integration

Migration can be offered by onboarding when a provider detects a known source. Both openclaw onboard --flow import and openclaw setup --wizard --import-from hermes rely on the same plugin migration provider and still display a preview before applying. In contrast to standalone migration, the fresh-target onboarding path stages local artifacts and imported credentials, verifies or repairs imported inference within staging, then promotes workspace and agent state before committing configuration. A mode-0600 promotion journal allows the next run to finish or roll back an interrupted publish, including any deferred external activation, without replaying imported local data.

Note

A fresh OpenClaw setup is required for onboarding imports. Reset config, credentials, sessions, and the workspace first if you already have local state. Backup-plus-overwrite or merge imports are feature-gated for existing setups.

Migrating from Hermes: user-facing walkthrough.
Migrating from Claude: user-facing walkthrough.
Migrating: move OpenClaw to a new machine.
Doctor: health check after applying a migration.
Plugins: plugin install and registration.