Claude Code / Hermes → OpenClaw 2026: Complete Migration Guide Using openclaw migrate on Mac mini M4

OpenClaw v2026.4.26, released April 28, 2026, shipped a feature that many developers have been requesting for months: openclaw migrate, a one-command tool that imports your existing AI coding agent configuration from Claude Code or Hermes directly into OpenClaw. If you've built up MCP server connections, custom skills, and workflow tuning in Claude Code or Hermes and want to bring it all to OpenClaw without manually recreating each piece, this guide walks you through the complete process on a VpsGona Mac mini M4 node — including what migrates automatically, what requires manual work, and how to fix the six most common post-migration errors.

Why Developers Are Moving from Claude Code and Hermes to OpenClaw in 2026

The migration trend accelerated in early 2026 for three concrete reasons, not because of marketing. Understanding them helps you decide whether migration is right for your specific workflow.

Reason 1: Multi-agent orchestration without plugin hacks. Claude Code's multi-agent support requires workarounds and is limited to Anthropic-hosted model routing. OpenClaw's native multi-agent framework (ClawHub) lets you orchestrate independent agent processes that share a Memory-Wiki state layer, with any model provider. Teams running parallel research, code review, and test-generation agents find this architecture significantly simpler to manage.

Reason 2: OpenClaw's OTEL observability is production-grade. Since v2026.4.25, OpenClaw emits structured telemetry for every model call, tool invocation, and memory access. Claude Code and Hermes both lack equivalent structured observability. Teams that need token cost attribution, tool loop detection, and memory pressure alerts — especially for autonomous overnight agents — have no equivalent in the other tools.

Reason 3: Provider neutrality and bundled Cerebras support. OpenClaw v2026.4.26 added Cerebras as a bundled provider, joining OpenAI, Anthropic, Gemini, DeepSeek, and local Ollama models. Claude Code is structurally tied to Anthropic's API. Hermes has provider flexibility but lacks the plugin SDK maturity that OpenClaw's v2026 releases brought. If you run a mixed-provider workflow, OpenClaw's plugin manifest architecture handles model-id normalization across providers without custom configuration.

What openclaw migrate Actually Does in v2026.4.26

The openclaw migrate command performs a structured scan of the source tool's configuration directory, extracts compatible settings, and writes them into OpenClaw's configuration format. It does not copy conversation history or session logs — only configuration, capability definitions, and connection metadata.

The migration process has three phases:

1. Discovery phase: OpenClaw scans the source configuration directory (~/.claude/ for Claude Code, ~/.hermes/ for Hermes) to detect installed MCP servers, custom skills/tools, API key references, and provider configurations.
2. Translation phase: Each detected item is mapped to its OpenClaw equivalent. MCP server definitions are re-expressed in OpenClaw's plugin manifest format. API key environment variable names are aliased. Custom tool definitions are wrapped in OpenClaw's skill schema.
3. Report phase: A JSON migration report is written to ~/.openclaw/migrate-report.json listing every item that was migrated successfully, every item that was partially migrated (requires manual completion), and every item that could not be migrated (incompatible format or no OpenClaw equivalent).

Configuration Item	Migrates from Claude Code	Migrates from Hermes	Notes
MCP server endpoint definitions	✓ Automatic	✓ Automatic	Connection URIs and auth headers preserved
Custom skill / tool definitions	✓ Automatic	✓ Automatic	Wrapped in OpenClaw skill schema; test after migration
API key environment variable references	✓ Aliased automatically	✓ Aliased automatically	Actual key values are never read; aliases created in .env
System prompt customizations	⚠ Partial (review required)	⚠ Partial (review required)	Operator identity format differs between tools
Model provider configurations	⚠ Partial (Anthropic only)	✓ Automatic (multi-provider)	Non-Anthropic providers in Claude Code are not migratable
Memory / knowledge base content	✗ Not migrated	✗ Not migrated	Must be manually re-ingested into OpenClaw Memory-Wiki
Conversation / session history	✗ Not migrated	✗ Not migrated	By design — OpenClaw session format is incompatible
TaskFlow / webhook definitions	✗ N/A (Claude Code lacks this)	⚠ Partial	Hermes workflow definitions require manual mapping to TaskFlows

Pre-Migration Checklist: 7 Things to Verify Before Running the Command

Running openclaw migrate without preparation causes the majority of post-migration issues. Complete all seven items before executing the migration command.

1. Confirm OpenClaw version ≥ 2026.4.26. The migrate subcommand does not exist in earlier versions. Check with openclaw --version. Update with npx openclaw@latest update or /update inside the agent.
2. Back up the source tool's configuration directory. Run cp -r ~/.claude/ ~/claude-backup-$(date +%Y%m%d)/ (for Claude Code) or the equivalent for Hermes. The migration command is read-only, but having a dated backup prevents panic if something goes wrong.
3. List your active MCP servers. Inside Claude Code, run /mcp to see all connected MCP servers and note their names and connection types. You'll use this list to verify the migration report's coverage.
4. Document your custom system prompt customizations. If you've modified operator identity, persona instructions, or safety overrides, copy them to a plain text file. These are the items most likely to require manual review after migration.
5. Confirm Node.js ≥ 20 on the Mac mini M4 node. migrate uses Node's native fetch API, which requires Node 20+. Verify with node --version.
6. Note which API providers you currently use. If you have multiple providers configured in Hermes (OpenAI + Gemini + Cerebras, for example), verify they're all supported in OpenClaw's bundled provider list before migrating. Missing providers will show up as "manual-required" in the report.
7. Ensure sufficient disk space on the Mac mini M4 node. The migration process writes the report and translated configuration files to ~/.openclaw/. For most setups, 500 MB free space is more than sufficient.

Step-by-Step: Migrating from Claude Code on Mac mini M4

This sequence assumes you have an active VpsGona Mac mini M4 session with both Claude Code and OpenClaw v2026.4.26+ installed. SSH into your node and run the following:

1. Verify both tools are present and at the correct versions:

   openclaw --version # Must be ≥ 2026.4.26 claude --version # Confirm Claude Code installation exists

2. Run the migration command pointing to Claude Code:

   openclaw migrate --from claude-code

   OpenClaw will auto-detect ~/.claude/. If your Claude Code config is in a non-standard location, specify it explicitly:

   openclaw migrate --from claude-code --source /custom/path/to/.claude/

3. Watch the migration output. The CLI prints each discovered item in real-time. Items prefixed with ✓ migrated successfully. Items with ⚠ need review. Items with ✗ could not be migrated. A typical Claude Code migration output looks like:

   Discovered: 8 MCP servers, 12 custom tools, 3 system prompt blocks, 1 provider config ✓ MCP server: filesystem-mcp → migrated ✓ MCP server: github-mcp → migrated ✓ MCP server: brave-search-mcp → migrated ⚠ System prompt block 'persona' → manual-required (format differs) ⚠ Provider: anthropic → partial (only Anthropic models available in source) ✗ Memory content → not migrated (re-ingest manually) Migration complete. Report: ~/.openclaw/migrate-report.json

4. Read the full migration report:

   cat ~/.openclaw/migrate-report.json | python3 -m json.tool | head -80

5. Start OpenClaw and verify MCP connections:

   openclaw start /mcp status

   Each migrated MCP server should show a green connected state. If any show disconnected, see the troubleshooting section below.

Step-by-Step: Migrating from Hermes to OpenClaw

Hermes migration follows the same pattern but with a different --from flag and a few Hermes-specific considerations. Hermes stores its configuration in ~/.hermes/ by default and uses a YAML-based configuration format that OpenClaw's migration tool reads directly.

1. Run the Hermes migration:

   openclaw migrate --from hermes

   For Hermes workspaces (project-scoped configs), specify the workspace directory:

   openclaw migrate --from hermes --source /path/to/hermes-workspace/

2. Handle Hermes workflow definitions manually. Hermes uses a "workflow" construct that partially maps to OpenClaw's TaskFlows. The migration tool translates the trigger and step structure but cannot automatically replicate conditional branching logic. After migration, open each flagged workflow in OpenClaw's TaskFlow editor and verify the branching conditions are correctly expressed.
3. Re-configure multi-provider setups. If you used Hermes with multiple model providers, verify each provider is active in OpenClaw's settings:

   openclaw config list-providers

   Add any missing providers:

   openclaw config add-provider cerebras --api-key $CEREBRAS_API_KEY

4. Re-ingest Memory-Wiki content. Hermes memory content must be re-ingested into OpenClaw's Memory-Wiki. For small knowledge bases (< 50 documents), use the /learn command interactively. For larger bases, use the batch ingest API:

   openclaw memory ingest --dir /path/to/hermes/knowledge/ --format markdown

What Gets Migrated vs What You Must Reconfigure Manually

After running the migration command and reviewing the report, use this checklist to ensure nothing critical was missed:

Item Category	Auto-Migrated?	Manual Action Required
MCP server endpoints and auth	✓ Yes	None if connection succeeds; re-auth if token expired
Custom tool / skill definitions	✓ Yes	Run each tool manually to verify behavior after schema translation
API key environment variable aliases	✓ Yes (aliases only)	Verify actual keys are in ~/.openclaw/.env or system env
System prompt operator identity	⚠ Partial	Review and rewrite in OpenClaw's operator format
Model provider configurations	⚠ Partial	Add non-Anthropic providers manually for Claude Code migrations
Hermes workflow conditions	⚠ Partial	Manually translate conditional branches to TaskFlow schema
Memory / knowledge base content	✗ No	Re-ingest all documents via /learn or batch ingest command
Conversation history	✗ No	No action needed — history is tool-specific and not portable
Matrix E2EE configuration (new in v2026.4.26)	✗ N/A (new OpenClaw feature)	Set up from scratch with: openclaw security matrix --setup

Post-Migration Troubleshooting: 6 Common Errors and Fixes

These are the errors most frequently reported in the OpenClaw community after running openclaw migrate for the first time.

Error 1: MCP server shows "disconnected" after migration. The most common cause is an expired authentication token. MCP servers that use OAuth or bearer tokens store a reference to the token, not the token value itself — and tokens expire. Solution: open the MCP server's authentication settings in OpenClaw's control panel and re-authenticate.

Error 2: openclaw migrate: source directory not found. Claude Code may be installed in a non-standard location if you used a different installer. Find it with find ~ -name ".claude" -type d 2>/dev/null and pass the path explicitly with --source.

Error 3: Custom tool throws schema validation error when invoked. The migration tool wraps tools in OpenClaw's skill schema, but some tools have parameter types that don't have exact equivalents. Check the tool's parameter definitions in ~/.openclaw/skills/ and align the type declarations with OpenClaw's schema (string, number, boolean, array, object).

Error 4: Boot-up hang after migration (known v2026.4.26 issue). Some users report delayed startup after updating to v2026.4.26, particularly when many MCP servers are configured. This is a known issue where connection initialization is synchronous. Workaround: temporarily disable non-essential MCP servers in openclaw.config.js until startup completes, then re-enable them progressively.

Error 5: ENOENT: no such file or directory, open '~/.openclaw/.env'. The migration tool creates API key alias entries assuming .env exists. Create it manually and populate with your actual keys:

touch ~/.openclaw/.env echo "ANTHROPIC_API_KEY=your-key-here" >> ~/.openclaw/.env echo "OPENAI_API_KEY=your-key-here" >> ~/.openclaw/.env

Error 6: Ollama connections fail after migration. OpenClaw v2026.4.26 improved Ollama reliability for Qwen and Gemma 4 models specifically. If your Ollama connection worked in Hermes but fails in OpenClaw, verify you're running Ollama 0.22.0 or later — community reports confirm this version resolves compatibility issues with the updated retrieval paths.

ollama --version # Should be ≥ 0.22.0 ollama serve # Confirm Ollama is running before OpenClaw starts

Optimizing Your Migrated OpenClaw Setup on Mac mini M4

Once migration is stable and all MCP servers are connected, these four optimizations specifically benefit Mac mini M4 deployments:

• Set maxContextTokens based on your actual model. The migrated config inherits a generic context window size. On Mac mini M4 with 16 GB unified memory, Claude 3.7 Sonnet's 200K context window is memory-intensive. For typical coding tasks, setting maxContextTokens: 32768 in openclaw.config.js significantly reduces memory pressure while covering virtually all real-world coding sessions.
• Enable the new JSON5 pending-changes diff panel. This v2026.4.26 feature shows a structured diff of pending file changes before the agent commits them. On a remote Mac mini M4 session where you can't visually inspect the working directory in real-time, this panel is particularly valuable:

  // in openclaw.config.js ui: { pendingChangesDiff: true, diffFormat: 'json5' }

• Configure the Cerebras provider for speed-critical tasks. Cerebras is now a bundled provider in v2026.4.26. For tasks where response latency matters more than output length — quick code explanations, type annotation suggestions, test case generation — Cerebras models deliver significantly lower time-to-first-token than Anthropic or OpenAI at similar quality tiers.
• Set up Matrix E2EE for secure remote sessions. This is a new feature with no equivalent in Claude Code or Hermes. When running OpenClaw on a VpsGona node, all data travels over SSH, but adding Matrix E2EE adds end-to-end encryption at the application layer — particularly useful when agents handle code containing sensitive credentials:

  openclaw security matrix --setup

Why Mac mini M4 on VpsGona Is the Ideal OpenClaw Migration Target

Migrating to OpenClaw is a configuration change; where you run OpenClaw determines whether the migration delivers its full value. For developers who relied on Claude Code or Hermes running locally on a personal laptop or desktop, migrating to OpenClaw on a VpsGona Mac mini M4 node changes the equation in several concrete ways.

First, the Mac mini M4's Apple Silicon architecture is natively compatible with every macOS-specific MCP server and tool that Claude Code users have built up. Filesystem access, Xcode integrations, macOS automation via AppleScript or Shortcuts, and CoreML-based local model inference all work on the M4 chip as expected — without the compatibility layer overhead that x86 emulation introduces. When you migrate your MCP server configurations, they drop into a Mac mini M4 environment where they're running on the exact same OS and chip architecture as they were designed for.

Second, VpsGona's no-minimum-commitment rental model aligns naturally with OpenClaw's use patterns. OpenClaw's most powerful features — multi-agent orchestration via ClawHub, OTEL observability, autonomous overnight agents — are most valuable when running continuously on a dedicated node, not intermittently on a personal machine. Renting a Mac mini M4 node exclusively for OpenClaw workloads, and stopping it between project cycles, costs a fraction of dedicated server alternatives while delivering native Apple Silicon performance. The new OTEL integration means you can also attribute every hour of compute cost to specific agent tasks, turning the VpsGona bill into an auditable record of where AI compute was actually spent. Learn more about available configurations on the VpsGona pricing page or consult the OpenClaw deployment documentation for environment setup tips.