docs/cli/migrate.md
openclaw migrateImport state from another agent system through a plugin-owned migration provider. Bundled providers cover Codex CLI state, Claude, and Hermes; third-party plugins can register additional providers.
<Tip> For user-facing walkthroughs, see [Migrating from Claude](/install/migrating-claude) and [Migrating from Hermes](/install/migrating-hermes). The [migration hub](/install/migrating) lists all paths. </Tip>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
openclaw migrate is preview-first.
`openclaw migrate apply <provider>` previews the plan and prompts before changing state unless `--yes` is set. In non-interactive mode, apply requires `--yes`.
The bundled Claude provider detects Claude Code state at ~/.claude by default. Use --from <path> to import a specific Claude Code home or project root.
CLAUDE.md and .claude/CLAUDE.md into the OpenClaw agent workspace.~/.claude/CLAUDE.md appended to workspace USER.md..mcp.json, Claude Code ~/.claude.json, and Claude Desktop claude_desktop_config.json.SKILL.md.Claude hooks, permissions, environment defaults, local memory, path-scoped rules, subagents, caches, plans, and project history are preserved in the migration report or reported as manual-review items. OpenClaw does not execute hooks, copy broad allowlists, or import OAuth/Desktop credential state automatically.
The bundled Codex provider detects Codex CLI state at ~/.codex by default, or
at CODEX_HOME when that environment variable is set. Use --from <path> to
inventory a specific Codex home.
Use this provider when moving to the OpenClaw Codex harness and you want to
promote useful personal Codex CLI assets deliberately. Local Codex app-server
launches use a per-agent CODEX_HOME, so they do not read your personal Codex
CLI state by default, while subprocesses still inherit the normal process
HOME unless the app-server launch explicitly overrides it.
Running openclaw migrate codex in an interactive terminal previews the full
plan, then opens checkbox selectors before the final apply confirmation. Skill
copy items are prompted first. Use Toggle all on or Toggle all off for bulk
selection. Press Space to toggle rows, or press Enter to activate the highlighted
row and continue. Planned skills start checked, conflict skills start unchecked, and
Skip for now skips skill copies for this run while still continuing to plugin
selection. When source-installed curated Codex plugins are migratable and
--plugin was not supplied, migration then prompts for native Codex plugin
activation by plugin name. Plugin items
start checked unless the target OpenClaw Codex plugin config already has that
plugin. Existing target plugins start unchecked and show 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 stop before applying. For scripted or
exact runs, pass --skill <name> once per skill, for example:
openclaw migrate codex --dry-run --skill gog-vault77-google-workspace
openclaw migrate apply codex --yes --skill gog-vault77-google-workspace
Use --plugin <name> to limit native Codex plugin migration non-interactively
to one or more source-installed curated plugins:
openclaw migrate codex --dry-run --plugin google-calendar
openclaw migrate apply codex --yes --plugin google-calendar
$CODEX_HOME/skills, excluding Codex's
.system cache.$HOME/.agents/skills, copied into the current
OpenClaw agent workspace when you want per-agent ownership.openai-curated Codex plugins discovered through Codex
app-server plugin/list. Planning reads plugin/read for each enabled
installed plugin. App-backed plugins require the source Codex app-server
account response to be a ChatGPT subscription account; non-ChatGPT or missing
account responses are skipped with codex_subscription_required. By default,
migration does not call source app/list, so app-backed plugins that pass the
account gate are planned without source app accessibility verification, and
account lookup transport failures skip with codex_account_unavailable. Pass
--verify-plugin-apps when you want migration to force a fresh source
app/list snapshot and require every owned app to be present, enabled, and
accessible before planning native activation. In that mode, account lookup
transport failures fall through to source app inventory verification. The
source app inventory snapshot is kept in memory for the current process; it
is not written to migration output or target config. Disabled plugins,
unreadable plugin details, subscription-gated source accounts, and, when
verification is requested, missing apps, disabled apps, inaccessible apps, or
source app inventory failures become manual skipped items with typed reasons
instead of target config entries.
Apply calls app-server plugin/install for each selected eligible plugin,
even if the target app-server already reports that plugin as installed and
enabled. Migrated Codex plugins are usable only in sessions that select the
native Codex harness; they are not exposed to Pi, normal OpenAI provider runs,
ACP conversation bindings, or other harnesses.Codex config.toml, native hooks/hooks.json, non-curated marketplaces, cached
plugin bundles that are not source-installed curated plugins, and source-installed
plugins that fail the source subscription gate are not activated automatically.
When --verify-plugin-apps is set, plugins that fail the source app-inventory
gate are also skipped. They are copied or reported in the migration report for
manual review.
For migrated source-installed curated plugins, apply writes:
plugins.entries.codex.enabled: trueplugins.entries.codex.config.codexPlugins.enabled: trueplugins.entries.codex.config.codexPlugins.allow_destructive_actions: truemarketplaceName: "openai-curated" and
pluginName for each selected pluginMigration never writes plugins["*"] and never stores local marketplace cache
paths. Source-side subscription failures are reported on manual items with typed
reasons such as codex_subscription_required, codex_account_unavailable,
plugin_disabled, or plugin_read_unavailable. With --verify-plugin-apps,
source app-inventory failures can also appear as app_inaccessible,
app_disabled, app_missing, or app_inventory_unavailable. Skipped plugins
are not written to target config.
Target-side auth-required installs are reported 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 are item-scoped error results.
If Codex app-server plugin inventory is unavailable during planning, migration falls back to cached bundle advisory items instead of failing the whole migration.
The bundled Hermes provider detects state at ~/.hermes by default. Use --from <path> when Hermes lives elsewhere.
config.yaml.providers and custom_providers.mcp_servers or mcp.servers.SOUL.md and AGENTS.md into the OpenClaw agent workspace.memories/MEMORY.md and memories/USER.md appended to workspace memory files.SKILL.md file under skills/<name>/.skills.config..env, only with --include-secrets..env keysOPENAI_API_KEY, ANTHROPIC_API_KEY, OPENROUTER_API_KEY, GOOGLE_API_KEY, GEMINI_API_KEY, GROQ_API_KEY, XAI_API_KEY, MISTRAL_API_KEY, DEEPSEEK_API_KEY.
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 preserves opaque or unsafe state without pretending OpenClaw can execute or trust it automatically:
plugins/sessions/logs/cron/mcp-tokens/auth.jsonstate.dbopenclaw doctor
Migration sources are plugins. A plugin declares its provider ids in openclaw.plugin.json:
{
"contracts": {
"migrationProviders": ["hermes"]
}
}
At runtime the plugin calls api.registerMigrationProvider(...). The provider implements detect, plan, and apply. Core owns CLI orchestration, backup policy, prompts, JSON output, and conflict preflight. Core passes the reviewed plan into apply(ctx, plan), and providers may rebuild the plan only when that argument is absent for compatibility.
Provider plugins can use openclaw/plugin-sdk/migration for item construction and summary counts, plus openclaw/plugin-sdk/migration-runtime for conflict-aware file copies, archive-only report copies, cached config-runtime wrappers, and migration reports.
Onboarding can offer migration when a provider detects a known source. Both openclaw onboard --flow import and openclaw setup --wizard --import-from hermes use the same plugin migration provider and still show a preview before applying.