OpenClaw to Claude Code

Migration notes

Claude Code uses a different skill architecture, so complex skills require manual conversion. Simple memory and personality transfers are fully automated.

Feature comparison

Prerequisites

Before you start, make sure you have these ready:

• An active OpenClaw workspace with the data you want to migrate. ClawSail reads directly from your workspace directory, so it needs to be accessible on the machine you are running from.
• Claude Code installed and authenticated. Run `claude --version` in your terminal to confirm. If you do not have it yet, install via `npm install -g @anthropic-ai/claude-code` and authenticate with your API key.
• ClawSail CLI (optional but recommended). Install with `npm install -g clawsail`. You can do everything manually, but the CLI automates the file conversions and catches common mistakes.
• A backup of your OpenClaw workspace. Migrations are non-destructive, but having a backup means you can always roll back.

Step 1: Export Your OpenClaw Workspace

Start by exporting your workspace into a portable format that ClawSail can process.

• - Run `clawsail export --source ./my-openclaw-workspace` from your terminal. This creates a `.clawsail-export` directory containing your memory files, personality configs, skills manifests, and conversation logs.
• - If you prefer to do it manually, copy your entire OpenClaw workspace directory to a working location. The key files are `SOUL.md`, the `memory/` directory, `AGENTS.md`, and any `.skill` manifest files.
• - Verify the export looks right: you should see your SOUL.md, memory directory, and any custom skill files in the output.

Step 2: Map Configuration Files

This is where the real translation happens. OpenClaw and Claude Code use different names and formats for the same concepts.

• SOUL.md becomes CLAUDE.md. Your personality config, behavior rules, and system instructions move into Claude Code's `CLAUDE.md` file. ClawSail handles the syntax differences automatically — OpenClaw's directive blocks get converted to Claude Code's instruction format. Place the output at `.claude/CLAUDE.md` in your project root.
• AGENTS.md maps to tool definitions. OpenClaw's agent declarations describe capabilities in a manifest format. Claude Code uses a different tool registration system. Simple agents (file search, code analysis) map cleanly. Complex multi-step agents need manual rewriting — see Step 4.
• Environment variables transfer directly. Copy your `.env` values as-is. Claude Code reads the same environment variable format.

Step 3: Transfer Memory and Conversation History

Memory is where most of your agent's accumulated knowledge lives. Losing it means your agent starts from scratch.

• - ClawSail converts OpenClaw's memory directory structure into Claude Code's context file format. Run `clawsail migrate --target claude-code` to perform the conversion.
• - Conversation history from the last 90 days gets exported as context files. Older conversations are archived but not transferred — Claude Code's context window makes them less useful anyway.
• Check the output size. Claude Code loads context files on every session start. If your memory directory is over 50KB total, consider pruning old or redundant entries. Large context files slow down every interaction.

Step 4: Rebuild Custom Skills as Claude Code Tools

This is the only step that requires real engineering work. OpenClaw skills and Claude Code tools have fundamentally different architectures.

• Simple skills (file reading, search, text processing) usually have direct Claude Code equivalents. Check the Claude Code tool registry before rebuilding from scratch — what you need might already exist.
• API-calling skills need their HTTP logic rewritten as Claude Code tool functions. The input/output schemas are similar, but the execution model is different. Budget 30-60 minutes per complex skill.
• Multi-agent orchestration does not have a direct equivalent in Claude Code. If you rely on OpenClaw's agent chaining, you will need to restructure as sequential tool calls or use Claude Code's built-in agent patterns.
• Skill permissions work differently. OpenClaw uses explicit allow/deny lists. Claude Code uses a trust-based model where tools request permission at runtime. Review your security requirements and adjust.

Step 5: Verify and Test

Do not skip this step. A migration that looks complete can still have subtle issues.

• - Run `claude` in your project directory and ask it to summarize its own configuration. It should reflect your migrated CLAUDE.md personality and have access to your context files.
• - Test each migrated tool individually. Run a simple task that exercises the tool and confirm the output matches what you got from OpenClaw.
• - Check for missing context by asking about something that was in your memory files. If the agent does not know about it, a memory file likely failed to convert.
• - Run your most common workflow end-to-end. This catches integration issues that per-tool testing misses.

Common Pitfalls

• Forgetting to convert SOUL.md directives. Raw OpenClaw directive syntax in CLAUDE.md will be treated as plain text, not instructions. Always run through ClawSail's converter or manually reformat.
• Oversized context files. Dumping your entire memory directory without pruning leads to slow startup and wasted tokens. Keep total context under 50KB.
• Assuming skills transfer 1:1. They do not. Even "simple" skills may behave differently because of Claude Code's different execution model. Always test.
• Skipping the backup. If something goes wrong mid-migration, you want the ability to restart cleanly.

Timeline Expectations

Not everything takes the same amount of effort. Here is a realistic breakdown:

• 5 minutes: Exporting your workspace, transferring environment variables, copying conversation history.
• 15-30 minutes: Converting SOUL.md to CLAUDE.md, mapping memory files, verifying context loads correctly.
• 1-3 hours: Rebuilding custom skills as Claude Code tools, depending on complexity and count. Simple API wrappers take 15 minutes each. Complex multi-step skills with error handling take closer to an hour.
• Half a day (4+ hours): Full migration of a large workspace with 10+ custom skills, multi-agent setups, and extensive memory. Most of this time goes into skill rebuilding and end-to-end testing.

The automated parts (Steps 1-3) take under 30 minutes for any workspace size. The manual parts (Step 4) scale linearly with skill complexity. Plan accordingly.