.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
The first time you run hermes claw migrate, the command will probably finish in under a minute and you'll wonder if it did anything.
It did. The migration tool is one of those rare bits of software that thinks it's polite to be quick. But quick doesn't mean effortless on your end. The choices you make before you run it (full migration vs user-data only, secrets in or out, what to do when skill names collide) determine if your new Hermes install feels like home on day one or like a suspiciously tidy hotel room (wink wink)
This guide walks through the migration end to end, including the bits the docs gloss over: how to do a sanity-check dry run, how to handle skills you've heavily customised, how to keep your OpenClaw install around as a safety net while you settle in and what to verify after the migration before you trust the new agent with a real task.
Before you do anything, take a snapshot
Hermes writes a backup automatically before claw migrate touches your data. That backup lives at ~/.hermes/migration/openclaw/<timestamp>/ and includes the pre-migration state of any Hermes files it's about to overwrite. Good. But it does not back up your OpenClaw install. If anything goes sideways, your OpenClaw data is still where it always was, but if you've already started running both side by side, that picture gets messy fast.
I do two things before any migration. First, I tar the entire ~/.openclaw/ directory into a dated archive and copy it somewhere off-server. tar -czf openclaw-snapshot-2026-05-05.tar.gz ~/.openclaw is enough; if you're worried about secrets in transit, encrypt it with gpg first. Second, I stop any running OpenClaw processes (the gateway, any cron-driven agents, anything else with a long-lived OpenClaw lock on the data dir). Migrating while OpenClaw is actively writing is the single most common cause of skill-conflict warnings later.
If you've installed Hermes by following the Ubuntu install guide already, you've also got a freshly created ~/.hermes with mostly empty defaults. The migration is going to drop content into it, so you don't need to wipe it first.
If you deployed a fresh LumaDock VPS with the Hermes template, our Hermes Agent VPS setup guide covers the first-login menu and the dashboard pairing flow you'll see before this migration step.
Run a dry run before the real one
The first migration command worth your time isn't the migration itself, it's the preview:
hermes claw migrate --dry-runDry-run reads your OpenClaw install, computes what would change in ~/.hermes and prints the plan. You'll see something like:
Would copy persona : ~/.openclaw/SOUL.md -> ~/.hermes/SOUL.md
Would merge memory : ~/.openclaw/MEMORY.md (12 entries)
Would merge memory : ~/.openclaw/USER.md (3 entries)
Would import skills : ~/.openclaw/skills/* (24 skills)
Would import keys : telegram, openrouter, anthropic
Would skip skills : ~/.openclaw/skills/heavy-cron (custom edits, conflict)
Would archive : ~/.openclaw/legacy/* (no Hermes equivalent)The exact wording shifts a little between versions but the structure is stable. Read it carefully. Two things to look for. First, the count of memory entries should match what you expect; if it says "0 entries" you almost certainly have a permissions problem on the OpenClaw side that's hiding the file from Hermes. Second, the "Would skip" lines tell you about skill conflicts the tool can't auto-resolve. If your dry-run flags a dozen skills as conflicts, the migration itself is going to leave them where they are and you'll need to re-import by hand later.
If the dry-run output looks wrong, fix the underlying data first. Don't just run the real migration and hope it sorts itself out.
Pick a preset
Hermes ships with two presets and they map to different intents.
Full preset (the default). Migrates everything: persona, memories, skills, command allowlist, messaging configs and API keys. The right choice when you're decommissioning OpenClaw and Hermes is going to take its place wholesale.
User-data preset. Migrates only persona, memories and skills. Skips API keys, allowlist and messaging configs. The right choice when you want to start with a clean Hermes setup but don't want to lose your accumulated context. Especially useful if your OpenClaw config has cruft you've been meaning to clean up; this is your chance to leave it behind.
Pick the preset on the command line:
hermes claw migrate # Default: full preset
hermes claw migrate --preset user-data # Memories and skills onlyIf you want full migration but want to leave secrets out of it (say, you're moving to a server where you'll regenerate API keys anyway), use the full preset and explicitly omit secrets:
hermes claw migrate --preset full --no-migrate-secretsThat gives you everything except the keys, which is sometimes the cleanest path because new servers shouldn't really inherit old credentials.
What moves and where it lands
The mapping is straightforward once you've seen it once.
Persona. ~/.openclaw/SOUL.md becomes ~/.hermes/SOUL.md. The format is identical so this is a copy with a small header rewrite to point at Hermes-style fields rather than OpenClaw ones.
Memories. ~/.openclaw/MEMORY.md and ~/.openclaw/USER.md get merged into ~/.hermes/memories/MEMORY.md and ~/.hermes/memories/USER.md. Hermes's memory file format is also markdown with one entry per heading, so the merge is mostly concatenation with deduplication on entry timestamps.
Skills. Every skill under ~/.openclaw/skills/ gets copied to ~/.hermes/skills/openclaw-imports/. Note the namespace: imported skills don't go into the top-level skills dir, they live in a subfolder so you can tell them apart from skills Hermes generates itself or that you write fresh. The skill format is compatible enough that most run unmodified, but the SKILL.md frontmatter sometimes references OpenClaw-specific tools that Hermes calls something different. The migration tool patches the obvious renames; the rest you fix when you notice them.
Workspace instructions. If you used AGENTS.md in OpenClaw to give project-specific behaviour, point Hermes at the same workspace with --workspace-target:
hermes claw migrate --workspace-target ~/projects/myappHermes will copy the AGENTS.md from your OpenClaw workspace into the same path under your Hermes-aware project. If you don't pass --workspace-target, AGENTS.md gets archived and you can copy it across by hand later.
Command allowlist. The list of shell commands you previously approved gets carried across so you don't have to re-approve everything from scratch. This one matters more than people realise; without it, the first half-hour of using Hermes is dominated by approval prompts.
Messaging configs. Telegram, Discord, Slack, WhatsApp and Signal configs all migrate, including allowed-users lists and platform-specific settings. The bot tokens themselves only carry over if you opted into secrets migration.
API keys. Telegram bot token, OpenRouter, OpenAI, Anthropic, ElevenLabs and any other allowlisted credentials. Carried by default in the full preset, skipped under user-data.
TTS assets. Audio files in your workspace that OpenClaw used for voice-mode get copied across.
Skill conflicts and how to handle them
The most fiddly part of any migration is what happens when you've heavily edited a skill on the OpenClaw side and Hermes already has a built-in skill of the same name. The tool gives you three modes:
hermes claw migrate --skill-conflict skip # Keep Hermes's version, ignore OpenClaw's
hermes claw migrate --skill-conflict overwrite # Replace Hermes's version with OpenClaw's
hermes claw migrate --skill-conflict rename # Import OpenClaw's under a renamed slugThe default is rename, which is the safest because nothing gets clobbered, but it leaves you with two skills doing similar things until you reconcile them. If your OpenClaw skill is genuinely better than Hermes's stock one (you've added retries, tightened the system prompt, added input validation), overwrite is right. If you barely changed it from the stock OpenClaw version, skip is right because Hermes's built-in equivalent is probably more current.
I usually do a first pass with --skill-conflict skip to get a clean baseline, then walk through each conflicting OpenClaw skill manually and decide one by one if it's worth bringing forward.
Run the migration
Once your dry-run looks right and you've picked your flags, run the real thing:
hermes claw migrate --preset full --skill-conflict renameYou'll see live progress per stage: persona, memories, skills, configs, secrets. The output is more verbose than the dry-run because it includes line counts and conflict resolutions as they happen. Watch for two things: any line beginning with WARN or ERROR plus the final summary, which tells you how many items moved and how many were skipped or archived.
If anything fails partway through, the auto-backup at ~/.hermes/migration/openclaw/<timestamp>/ is what you roll back to. cp -r ~/.hermes/migration/openclaw/2026-05-05_14-22-31/* ~/.hermes/ restores the pre-migration state. Then go fix whatever the migration tripped over and try again.
Verify the migration worked
After the migration finishes, three sanity checks tell you if it did the right thing.
First, run hermes and start a conversation. Ask it something only your old SOUL.md or MEMORY.md would know: a project name, a colleague's nickname, an in-joke, your home city. If the agent answers correctly without you having to retype context, the persona and memory layers are wired up. If it acts like a stranger, check that ~/.hermes/SOUL.md exists and has content. Then check that ~/.hermes/memories/USER.md isn't empty.
Second, run hermes and trigger one of your migrated skills by name (for example, /skills custom-cron if that was a skill you used). If it fires and produces sensible output, the skills directory loaded correctly. If you get "skill not found", check that ~/.hermes/skills/openclaw-imports/<skill-name>/SKILL.md exists; if it does, the issue is usually the SKILL.md frontmatter referencing tool names Hermes doesn't recognise and you'll need to edit the offending fields.
Third, run hermes gateway setup if you migrated messaging configs, then hermes gateway start. Send your bot a test message from Telegram or whatever channel you migrated. If the agent responds, the gateway tokens migrated cleanly. If you get silence, the bot token might not have copied across (especially under --no-migrate-secrets); paste the relevant token into ~/.hermes/.env manually.
Keep OpenClaw running for a few days as a safety net
Keep in mind that your OpenClaw install is still there and still works. There's no rush to delete it. For the first three to seven days I run both side by side: Hermes on the same VPS, OpenClaw on a separate port or even just paused but not removed. If Hermes does something I don't expect (forgets a memory it should have, fails on a skill that worked fine before), I can compare against the OpenClaw setup directly and figure out what diverged.
The dedicated tutorial on running OpenClaw and Hermes side by side covers the port-collision and shared-resource details. Worth reading if you plan to hold both for more than a week.
When you're confident, archive your OpenClaw data dir, stop the systemd service if you had one then remove the OpenClaw binaries. The OpenClaw backup guide covers the snapshot-and-encrypt pattern; useful even when you're shutting it down for good, because you'll want a recoverable archive in case you ever need to forensically dig something out of an old skill.
What to do if the migration silently breaks the gateway
The single most common post-migration complaint is "Telegram works for the first message then goes dead." This is usually one of two things. Either two gateways are connected to the same bot token (your old OpenClaw gateway is still running on a cron and is stealing webhooks from Hermes). Or the bot token migrated but a dependent setting (allowed-users, command prefix, working dir) didn't.
To diagnose, run hermes gateway status and look at the per-platform output. If Telegram says "connected, last poll ok", but no messages come through, run ps aux | grep -i openclaw on the same server. If you see an OpenClaw gateway process still alive, kill it. If you find no other gateway running, check ~/.hermes/.env for the Telegram allowed-users line. The migration carries that across, but if your username changed at some point, your incoming messages might be silently dropped.
A separate tutorial on silent migration failures walks through every variant of this I've seen, including the WSL path issue that bites Windows-host users.
The 1-click migration shortcut
If you're migrating to a fresh server rather than upgrading in place, the path of least resistance is to spin up a fresh VPS with Hermes already installed and run the migration there from a tarball of your old OpenClaw data. The LumaDock Hermes Agent template gives you a clean Ubuntu 24.04 box with the agent pre-installed. You scp your ~/.openclaw tarball across, untar it, then run hermes claw migrate --source ~/.openclaw and the migration runs against the imported tarball as if OpenClaw had always lived on the new box. Pick the zone closest to wherever your LLM provider terminates and you get predictable round-trip latency without the fight.
