Migrate from Claude to OpenClaw

OpenClaw loads local Claude state using the included Claude migration provider. Before making any changes, this provider shows a preview of each item and hides secrets in both plans and reports. A standalone openclaw migrate generates a verified backup; the fresh onboarding path stages the import and only publishes it once verification passes.

Note

A clean OpenClaw installation is required for onboarding imports. If local OpenClaw state already exists, reset configuration, credentials, sessions, and the workspace first, or run openclaw migrate directly with --overwrite after reviewing the plan.

Two ways to import

Onboarding wizard

When local Claude state is detected, the wizard offers Claude as an option.

openclaw onboard --flow import

Alternatively, target a specific source:

openclaw onboard --import-from claude --import-source ~/.claude

CLI

For scripted or repeatable operations, use openclaw migrate. See openclaw migrate for the complete reference.

openclaw migrate claude --dry-run
openclaw migrate apply claude --yes

To import a particular Claude Code home or project root, add --from <path>.

What gets imported

Instructions and memory

Content from project CLAUDE.md and .claude/CLAUDE.md is copied or appended into the OpenClaw agent workspace at AGENTS.md.
Content from user ~/.claude/CLAUDE.md is appended into workspace USER.md.

MCP servers

Where they exist, MCP server definitions are imported from project .mcp.json, Claude Code ~/.claude.json, and Claude Desktop claude_desktop_config.json.

Skills and commands

Claude skills that include a SKILL.md file are copied into the OpenClaw workspace skills directory.
Claude command Markdown files located under .claude/commands/ or ~/.claude/commands/ are turned into OpenClaw skills using disable-model-invocation: true.

What stays archive-only

The provider copies the following into the migration report for manual inspection but does not load them into the active OpenClaw configuration:

Claude hooks
Claude permissions and broad tool allowlists
Claude environment defaults
CLAUDE.local.md
.claude/rules/
Claude subagents under .claude/agents/ or ~/.claude/agents/
Claude Code caches, plans, and project history directories
Claude Desktop extensions and OS-stored credentials

OpenClaw will not execute hooks, trust permission allowlists, or automatically decode opaque OAuth and Desktop credential state. After reviewing the archive, manually move whatever you need.

Source selection

Without --from, OpenClaw checks the default Claude Code home at ~/.claude, the sampled Claude Code ~/.claude.json state file, and the Claude Desktop MCP config on macOS.

When --from targets a project root, OpenClaw imports only that project's Claude files, including CLAUDE.md, .claude/settings.json, .claude/commands/, .claude/skills/, and .mcp.json. During a project-root import, your global Claude home is not read.

Recommended flow

Preview the plan

openclaw migrate claude --dry-run

The plan shows everything that will be modified, including conflicts, skipped items, and sensitive values hidden from nested MCP env or headers fields.

Apply with backup

openclaw migrate apply claude --yes

Before applying, OpenClaw creates and verifies a backup.

Run doctor

openclaw doctor

After the import, Doctor checks for configuration or state problems.

Restart and verify

openclaw gateway restart
openclaw status

Make sure the gateway is healthy and that your imported instructions, MCP servers, and skills are all loaded.

Conflict handling

When the plan reports conflicts (a file or config value already exists at the destination), Apply will not proceed.

Warning

Only rerun with --overwrite if you intend to replace the existing target. Providers may still create item-level backups for overwritten files inside the migration report directory.

Conflicts are uncommon with a fresh OpenClaw install. They usually happen when you run the import again on a setup that already contains user edits.

JSON output for automation

openclaw migrate claude --dry-run --json
openclaw migrate apply claude --json --yes

--yes is mandatory when running migrate apply from a non-interactive terminal. Without it, OpenClaw will fail with an error rather than applying changes, so scripts and CI pipelines must explicitly include --yes. Start by previewing with --dry-run --json, then execute with --json --yes once the plan is satisfactory.

Troubleshooting

Claude state lives outside ~/.claude

Use --from /actual/path on the command line or --import-source /actual/path during the onboarding process.

Onboarding refuses to import on an existing setup

Onboarding imports require a clean environment. Either reset the state and begin onboarding again, or work directly with openclaw migrate apply claude, which provides --overwrite and explicit backup management.

MCP servers from Claude Desktop did not import

Claude Desktop reads claude_desktop_config.json from a location that depends on the operating system. If OpenClaw could not locate it automatically, point --from to the directory containing that file.

Claude commands became skills with model invocation disabled

This is intentional. Claude commands are initiated by the user, so OpenClaw imports them as skills with disable-model-invocation: true. To have the agent call them automatically, modify each skill's frontmatter.

openclaw migrate: complete CLI reference, plugin contract, and JSON schemas.
Migration guide: every migration path.
Migrating from Hermes: the alternative cross-system import option.
Onboarding: the wizard flow and flags for non-interactive use.
Doctor: health verification after migration.
Agent workspace: where AGENTS.md, USER.md, and skills are stored.