Migrate

text

Copy

openclaw migrate

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

Commands

bash
Copy
openclaw migrate list
openclaw migrate claude --dry-run
openclaw migrate codex --dry-run
openclaw migrate codex --skill gog-vault77-google-workspace
openclaw migrate hermes --dry-run
openclaw migrate hermes
openclaw migrate apply codex --yes --skill gog-vault77-google-workspace
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

Name of a registered migration provider, for example `hermes`. Run `openclaw migrate list` to see installed providers. Build the plan and exit without changing state. Override the source state directory. Hermes defaults to `~/.hermes`. Import supported credentials. Off by default. Allow apply to replace existing targets when the plan reports conflicts. Skip the confirmation prompt. Required in non-interactive mode. Select one skill copy item by skill name or item id. Repeat the flag to migrate multiple skills. When omitted, interactive Codex migrations show a checkbox selector and non-interactive migrations keep all planned skills. Skip the pre-apply backup. Requires `--force` when local OpenClaw state exists. Required alongside `--no-backup` when apply would otherwise refuse to skip backup. Print the plan or apply result as JSON. With `--json` and no `--yes`, apply prints the plan and does not mutate state.

Safety model

is preview-first.

Preview before apply

Backups

Conflicts

Secrets

Claude provider

The bundled Claude provider detects Claude Code state at

by default. Use to import a specific Claude Code home or project root.

What Claude imports

• Project
  text

  Copy

  CLAUDE.md
  and
  text

  Copy

  .claude/CLAUDE.md
  into the OpenClaw agent workspace.
• User
  text

  Copy

  ~/.claude/CLAUDE.md
  appended to workspace
  text

  Copy

  USER.md
  .
• MCP server definitions from project
  text

  Copy

  .mcp.json
  , Claude Code
  text

  Copy

  ~/.claude.json
  , and Claude Desktop
  text

  Copy

  claude_desktop_config.json
  .
• Claude skill directories that include
  text

  Copy

  SKILL.md
  .
• Claude command Markdown files converted into OpenClaw skills with manual invocation only.

Archive and manual-review state

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.

Codex provider

The bundled Codex provider detects Codex CLI state at

by default, or at when that environment variable is set. Use 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 per-agent

and directories, so they do not read your personal Codex CLI state by default.

Running

in an interactive terminal previews the full plan, then opens a checkbox selector for skill copy items before the final apply confirmation. All skills start selected; uncheck any skill you do not want copied into this agent. For scripted or exact runs, pass once per skill, for example:

bash
Copy
openclaw migrate codex --dry-run --skill gog-vault77-google-workspace
openclaw migrate apply codex --yes --skill gog-vault77-google-workspace

What Codex imports

• Codex CLI skill directories under
  text

  Copy

  $CODEX_HOME/skills
  , excluding Codex's
  text

  Copy

  .system
  cache.
• Personal AgentSkills under
  text

  Copy

  $HOME/.agents/skills
  , copied into the current OpenClaw agent workspace when you want per-agent ownership.

Manual-review Codex state

Codex native plugins,

, and native are not activated automatically. Plugins may expose MCP servers, apps, hooks, or other executable behavior, so the provider reports them for review instead of loading them into OpenClaw. Config and hook files are copied into the migration report for manual review.

Hermes provider

The bundled Hermes provider detects state at

by default. Use when Hermes lives elsewhere.

What Hermes imports

• Default model configuration from
  text

  Copy

  config.yaml
  .
• Configured model providers and custom OpenAI-compatible endpoints from
  text

  Copy

  providers
  and
  text

  Copy

  custom_providers
  .
• MCP server definitions from
  text

  Copy

  mcp_servers
  or
  text

  Copy

  mcp.servers
  .
• text

  Copy

  SOUL.md
  and
  text

  Copy

  AGENTS.md
  into the OpenClaw agent workspace.
• text

  Copy

  memories/MEMORY.md
  and
  text

  Copy

  memories/USER.md
  appended to workspace memory files.
• Memory config defaults for OpenClaw file memory, plus archive or manual-review items for external memory providers such as Honcho.
• Skills that include a
  text

  Copy

  SKILL.md
  file under
  text

  Copy

  skills/<name>/
  .
• Per-skill config values from
  text

  Copy

  skills.config
  .
• Supported API keys from
  text

  Copy

  .env
  , only with
  text

  Copy

  --include-secrets
  .

Supported

text

Copy

.env

keys

, , , , , , , , .

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 preserves opaque or unsafe state without pretending OpenClaw can execute or trust it automatically:

• text

  Copy

  plugins/
• text

  Copy

  sessions/
• text

  Copy

  logs/
• text

  Copy

  cron/
• text

  Copy

  mcp-tokens/
• text

  Copy

  auth.json
• text

  Copy

  state.db

After applying

bash
Copy
openclaw doctor

Plugin contract

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

:

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

At runtime the plugin calls

. The provider implements , , and . Core owns CLI orchestration, backup policy, prompts, JSON output, and conflict preflight. Core passes the reviewed plan into , and providers may rebuild the plan only when that argument is absent for compatibility.

Provider plugins can use

for item construction and summary counts, plus for conflict-aware file copies, archive-only report copies, cached config-runtime wrappers, and migration reports.

Onboarding integration

Onboarding can offer migration when a provider detects a known source. Both

and use the same plugin migration provider and still show a preview before applying.

Related

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