Leaving OpenClaw: A Smooth Migration

Who this guide is for

Users currently on OpenClaw who want to switch to Hermes and keep their existing persona, skills, memories, and bot tokens without starting from scratch.

If you’ve never used OpenClaw, skip this guide. If you want to get Hermes running first and come back later, start with the 7-Day Tutorial.

Back up first, then migrate

Before doing anything, do two things:

1. cp -r ~/.openclaw ~/.openclaw.bak-$(date +%F) — manual backup
2. Run hermes claw migrate --dry-run first to preview what will be migrated and catch conflicts

The official tool copies files rather than moving them, but it’s still worth keeping your own copy.

---

Five-minute overview

OpenClaw and Hermes concepts map 1:1, and there’s an official migration tool that handles most of it in one pass:

hermes claw migrate --dry-run    # preview — no files changed
hermes claw migrate              # execute
hermes claw cleanup              # after verification, clean up OpenClaw remnants (optional)

By default, the tool migrates: SOUL.md, memories, skills, provider config, platform tokens, MCP servers, and session policies. This covers the most common case — just three commands.

The rest of this guide explains what’s happening, where things can go wrong, and what requires manual handling.

---

Concept mapping table

Get both sets of terminology aligned before you start:

OpenClaw	→	Hermes Agent	Notes
SOUL.md (persona)	→	~/.hermes/SOUL.md	Direct copy, formats are compatible
IDENTITY.md	→	Merge into SOUL.md	Archived — requires manual merge
AGENTS.md (project-level instructions)	→	AGENTS.md in your project directory	Requires --workspace-target
MEMORY.md + USER.md + diary files	→	~/.hermes/memories/	Merged into the new memory system
Skills (4 locations: workspace / managed / personal / project)	→	~/.hermes/skills/openclaw-imports/	All consolidated into one directory
Integrations (plugins)	→	Toolsets + MCP servers	Partly automatic, partly manual
Heartbeats (recurring tasks)	→	Cron jobs	Requires manual rebuild (see below)
HEARTBEAT.md	→	Cron job description text	Archived — requires manual rewrite
BOOTSTRAP.md	→	Context file or skill	Archived — requires manual rewrite
TOOLS.md	→	Not migrated	Hermes has built-in tool documentation
Bot platform config (TG/DC/Slack/…)	→	*_BOT_TOKEN / *_ALLOWED_USERS in ~/.hermes/.env	Automatic
Session reset policy	→	session_reset in config.yaml	Automatic
MCP servers	→	mcp_servers in config.yaml	Automatic, stdio + HTTP/SSE
Persistent Memory	→	Memory System	See Day 6

---

Migration steps

1. Run a dry-run first

   hermes claw migrate --dry-run

   The output is a change plan: what will be migrated, how conflicts are handled, what will be archived. Read it before executing — a few minutes now can save an hour of rollback later.

   If OpenClaw is installed in a non-default path:

   hermes claw migrate --dry-run --source /path/to/your/.openclaw

2. Decide whether to migrate API keys

   The default preset is full, which migrates API keys from OpenClaw (OpenRouter / OpenAI / Anthropic / DeepSeek / Gemini, etc.) alongside everything else.

   For a more cautious approach (migrating on a different machine, or taking the opportunity to rotate keys), use user-data:

   hermes claw migrate --preset user-data

   This skips API keys and migrates everything else. Re-add keys manually afterward: hermes config set ANTHROPIC_API_KEY ...

3. Handle skill name conflicts

   If you already have a skill in Hermes with the same name as one in OpenClaw (e.g. code-review on both sides), the default strategy is skip (keep your current version). Other options:

   hermes claw migrate --skill-conflict rename     # rename the OpenClaw version before migrating
   hermes claw migrate --skill-conflict overwrite  # overwrite Hermes version with OpenClaw's (use with caution)

4. Execute

   hermes claw migrate

   For non-interactive use (in scripts), add --yes to skip prompts — but don’t do this on the first run.

   At completion, a migration report is printed:

   ✓ SOUL.md migrated
   ✓ memories: 3 files merged (MEMORY.md, USER.md, 2026-04-*.md)
   ✓ skills: 12 migrated, 2 skipped (conflict: skip), 1 archived
   ✓ providers: anthropic, openrouter, deepseek
   ✓ bots: telegram, discord
   ✓ mcp_servers: 4
   ⚠ 6 items archived to ~/.hermes/migration/openclaw/2026-04-23-221532/archive/

5. Check the archive directory

   ls ~/.hermes/migration/openclaw/*/archive/

   This contains items the tool wasn’t confident enough to handle automatically — you’ll need to rebuild them selectively (see next section). Leaving them untouched is fine for now — they’re just not yet in Hermes.

6. Restart the gateway (if platform tokens were migrated)

   # Linux / macOS user service
   systemctl --user restart hermes-gateway
   
   # Or the straightforward way
   hermes gateway stop && hermes gateway start

   WhatsApp requires a fresh QR code scan:

   hermes whatsapp

7. Verify

   hermes status --deep       # check provider auth and platform connections
   hermes skills list         # confirm all skills are present
   hermes gateway status      # gateway and all bots connected

   Start Hermes and test:

   • Does SOUL.md take effect? (Does the personality feel right?)
   • Did memories carry over? (Ask about something it should know from the OpenClaw era)
   • Trigger a migrated skill (using Day 5’s trigger methods)

8. Clean up after verification

   hermes claw cleanup

   This removes the OpenClaw config directory. Don’t rush — run Hermes for a day or two first to confirm nothing is missing.

---

Items requiring manual rebuild

The following are archived by the tool and won’t be auto-migrated:

IDENTITY.md → merge into SOUL.md

The two files serve overlapping purposes; Hermes only recognizes SOUL.md. Open IDENTITY.md from the archive directory, manually copy over any still-relevant sections to ~/.hermes/SOUL.md, and check for contradictions.

Heartbeats / HEARTBEAT.md → rewrite as cron jobs

OpenClaw’s heartbeat mechanism corresponds to cron jobs in Hermes (see Day 7).

Extract the intent + frequency from each heartbeat in HEARTBEAT.md and rewrite as a cron job:

# Original OpenClaw heartbeat: check RSS summary every day at 9 AM
hermes cron create "0 9 * * *" "Summarize my RSS subscriptions and send to Telegram"

BOOTSTRAP.md → rewrite as a context file or skill

OpenClaw’s bootstrap typically means “do X at the start of every session.” Hermes has two options:

• Simple startup instructions → put them in AGENTS.md (project-level) or SOUL.md (global)
• Complex multi-step workflows → write a skill (see Day 5 advanced section)

Old cron jobs / plugins / webhooks

OpenClaw’s scheduled tasks, custom plugins, and external webhooks don’t go through hermes claw migrate’s automatic path. Rebuild using the corresponding mechanism in Hermes:

OpenClaw	Hermes equivalent
Scheduled tasks	hermes cron create ... (Day 7)
Custom tools	Toolsets or MCP servers
Webhook receivers	Gateway webhook mode or a custom MCP server

Complex channel config (multiple accounts, routing rules)

The tool only migrates the primary account’s platform tokens and allowlist. If you had multiple Telegram bots, or per-channel/per-user routing rules in OpenClaw, rebuild manually in ~/.hermes/.env and ~/.hermes/config.yaml.

---

Quick reference: common flags

# Dry-run (strongly recommended first)
hermes claw migrate --dry-run

# Presets
hermes claw migrate                         # = --preset full (default, includes API keys)
hermes claw migrate --preset user-data      # excludes API keys

# Paths
hermes claw migrate --source /custom/.openclaw
hermes claw migrate --workspace-target /path/to/project   # where to put AGENTS.md

# Conflict handling
hermes claw migrate --skill-conflict skip        # default
hermes claw migrate --skill-conflict rename
hermes claw migrate --skill-conflict overwrite
hermes claw migrate --overwrite                  # overwrite all conflicts (use with caution)

# Automation
hermes claw migrate --yes                        # skip confirmations (for scripts)

---

Troubleshooting

'OpenClaw directory not found'

The tool defaults to ~/.openclaw. If yours is in a different location, add --source:

hermes claw migrate --source /path/to/.openclaw

Not sure where it is? Search: find / -name "SOUL.md" -path "*openclaw*" 2>/dev/null

'No provider API keys found'

OpenClaw may store keys in four locations — the tool checks in priority order:

1. openclaw.json config fields
2. ~/.openclaw/.env
3. The env sub-object in config
4. auth-profiles.json

If you used source: "file" or source: "exec" dynamic SecretRef, the tool won’t resolve those automatically. Add them manually after migration:

hermes config set ANTHROPIC_API_KEY sk-ant-xxx

Skills don't appear after migration

Migrated skills land in ~/.hermes/skills/openclaw-imports/. The skills list loads at session startup, so:

1. Exit and re-enter Hermes
2. /skills to see the list
3. Still not there? ls ~/.hermes/skills/openclaw-imports/ to confirm the files exist
4. Files exist but not listed → hermes skills audit to rescan

TTS voice changed or silent after migration

OpenClaw TTS settings may be in three locations — the tool checks in priority order:

1. messages.tts.providers.* (new format)
2. talk.providers.* (old format fallback)
3. Older flat keys

Voice IDs selected through the OpenClaw UI sometimes don’t auto-migrate. Add manually:

hermes config set tts.elevenlabs.voice_id YOUR_VOICE_ID

Gateway won't connect to Telegram after migration

90% of the time: the token was migrated but the gateway wasn’t restarted.

hermes gateway stop && hermes gateway start
# or
systemctl --user restart hermes-gateway

Still not working: hermes logs gateway --since 5m -f — you’ll typically see a specific 401 / DNS / network error.

Can I migrate only part of my config?

Yes. --preset user-data skips API keys; --skill-conflict skip protects your existing skills; running the migration scripts individually for specific files also works (e.g. just copy SOUL.md and reconfigure everything else manually).

You don’t have to do it all in one pass. Run the tool multiple times if needed — it’s idempotent, and re-running at most outputs “nothing to do.”

Can I still use OpenClaw after migration?

Yes. Migration copies, not moves — OpenClaw’s original config is untouched. Running both simultaneously will cause state divergence (e.g. the same Telegram bot gets grabbed by both), which isn’t recommended long-term.

Suggested transition: stop OpenClaw’s gateway, run Hermes’s. After a stable week with no issues, run hermes claw cleanup.

---

What to do after migration

1. Walk through the 7-Day Tutorial — not to re-learn, but to verify “these features actually work under Hermes”
2. Read Day 7 to rewrite all your heartbeats as cron jobs
3. Use Day 6’s hermes backup to take an initial snapshot of the new setup — that way you have a quick rollback point if anything surfaces later