How to Migrate from OpenClaw to Claude Code (Complete Guide)

Why We Migrated (And Why You Might Want To)

OpenClaw was not broken. It was good software that did exactly what it said it would. Our reasons for switching were less about frustration and more about ceiling -- we kept hitting things Claude Code made possible that OpenClaw did not.

OpenClaw to Claude Code: Concept Mapping

The mental models are similar. Most OpenClaw concepts have a direct Claude Code equivalent. Here is the full mapping so you know what you're translating before you start.

Step-by-Step Migration

We ran this migration on a production setup with a full SOUL.md, a file-based memory system, eight MCP servers, and launchd-driven heartbeats. The steps below are the exact sequence we followed.

npm install -g @anthropic-ai/claude-code

# Authenticate (opens browser for OAuth)
claude login

# Verify
claude --version

~/.claude/
  CLAUDE.md           # global agent instructions
  projects/
    <project-name>/
      memory/
        MEMORY.md       # index / table of contents
        projects.md     # active projects + status
        people.md       # contacts, collaborators
        decisions.md    # important decisions + context
        learnings.md    # lessons, patterns, gotchas
        daily/
          2026-04-08.md # daily activity logs

// ~/.claude/settings.json
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/you/projects"
      ]
    },
    "discord": {
      "command": "npx",
      "args": ["-y", "mcp-discord"],
      "env": {
        "DISCORD_TOKEN": "${DISCORD_BOT_TOKEN}"
      }
    }
  }
}

# Add a server via CLI
claude mcp add github -- npx -y @modelcontextprotocol/server-github

# List connected servers
claude mcp list

# Verify a server is responding
claude mcp get github

<!-- ~/Library/LaunchAgents/com.kaiships.heartbeat.plist -->
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>com.kaiships.heartbeat</string>
  <key>ProgramArguments</key>
  <array>
    <string>/usr/local/bin/claude</string>
    <string>--print</string>
    <string>--dangerously-skip-permissions</string>
    <string>Run your scheduled heartbeat duties.</string>
  </array>
  <key>StartInterval</key>
  <integer>900</integer>
  <key>StandardOutPath</key>
  <string>/tmp/kai-heartbeat.log</string>
  <key>StandardErrorPath</key>
  <string>/tmp/kai-heartbeat-err.log</string>
  <key>EnvironmentVariables</key>
  <dict>
    <key>ANTHROPIC_API_KEY</key>
    <string>your-key-here</string>
  </dict>
</dict>
</plist>

# Load the job
launchctl load ~/Library/LaunchAgents/com.kaiships.heartbeat.plist

# Run it once manually to test
launchctl start com.kaiships.heartbeat

# Check the log
tail -f /tmp/kai-heartbeat.log

What's Genuinely Better in Claude Code

After running both systems in production, here is an honest assessment of where Claude Code wins.

What You Might Miss from OpenClaw (Honest)

This is not a sales pitch. Some things in OpenClaw were genuinely good and the transition involves real tradeoffs.

Frequently Asked Questions

Is Claude Code a direct replacement for OpenClaw?

Mostly yes, with some differences. Claude Code covers everything OpenClaw does -- agent instructions, memory, MCP servers, scheduled automation, multi-agent workflows -- but the mental model differs. OpenClaw was designed as a standalone agent shell. Claude Code is deeper integrated with your IDE and the Anthropic model stack. If you ran OpenClaw as a coding + ops agent, Claude Code is a strong replacement and often an upgrade.

Do I have to rewrite my SOUL.md or AGENTS.md from scratch?

No. The rename is mostly mechanical -- SOUL.md becomes CLAUDE.md, the format stays Markdown, and the content structure (who the agent is, what it does, what rules it follows) maps over directly. The main thing to update is tool references and any OpenClaw-specific syntax. A full SOUL.md rewrite typically takes 30-60 minutes.

Will my MCP servers still work in Claude Code?

Yes. MCP is the same protocol on both sides. The config format is slightly different (Claude Code uses .claude/settings.json instead of openclaw.json) but the servers themselves do not change. Copy your server definitions over, update the config location, and they work.

What happens to my OpenClaw memory (knowledge graph, daily notes)?

Claude Code uses a file-based memory system rather than a graph database. You convert OpenClaw memory entries into Markdown files (one file per topic or domain). This is actually easier to edit, version-control, and audit. The tradeoff is that you lose graph traversal -- there is no automatic relationship mapping. For most setups, flat Markdown files work just as well.

Can I run Claude Code on a cron schedule like OpenClaw heartbeats?

Yes. Claude Code has a hooks system that can be triggered by external events, and you can drive it with launchd (macOS) or cron on Linux. The pattern is: scheduled trigger fires, calls the Claude Code CLI with a prompt, Claude Code executes and logs results. This is essentially identical to OpenClaw heartbeats.

Does Claude Code support subagents like OpenClaw?

Yes, and the subagent system is more capable. Claude Code's Agent tool lets you spawn isolated subagents with their own working directories and context. Worktrees give each subagent file-system isolation. You can run multiple subagents in parallel -- something that required significant setup in OpenClaw.

How long does the full migration take?

For a typical OpenClaw setup (SOUL.md + memory files + 5-10 MCP servers + heartbeat automation), expect 2-4 hours for the migration itself and another few hours of testing and tuning. If you have custom OpenClaw skills or hooks, add time to port those. The hardest part is usually the memory re-architecture, not the tooling.