How to migrate from OpenClaw to Hermes Agent without losing memory or skills

July 29, 202610 minOpenClaw, Hermes Agent, Nous Research, AI, Tutorial

Short answer (60 seconds): the migration is preview → apply → verify → clean up. (1) Install and verify Hermes Agent on the same machine where OpenClaw already runs. (2) Preview with hermes claw migrate --dry-run to see what it will import without touching anything. (3) Apply the migration with hermes claw migrate (or the opt-in variant hermes claw migrate --preset full --migrate-secrets --yes if you want a complete run that also carries API keys with no prompts). (4) Verify with hermes doctor, hermes status, and hermes config show, plus a new session that already sees the imported skills. (5) Review channels (including WhatsApp QR re-pairing) and archived files. (6) Only after validating everything, stop OpenClaw with openclaw gateway stop, preview cleanup with hermes claw cleanup --dry-run, and only then run hermes claw cleanup. For a complete OpenClaw uninstall at the end, follow the uninstall guide.

If you've been running OpenClaw for a while and want to move to Hermes Agent without losing memory or skills, there's an official command: hermes claw migrate. It reads from ~/.openclaw/ (with fallbacks to ~/.clawdbot/ and ~/.moltbot/), imports everything compatible, and archives what has no direct equivalent. This guide is the short version of the official migration guide, focused on what gets carried automatically, what gets archived, and how to validate before touching anything important.

What migrates automatically

The table summarizes, by area, what hermes claw migrate takes from your OpenClaw install and where it puts it in Hermes. The key flags are --preset full (everything compatible) or --preset user-data (excludes infra). No preset imports secrets on its own: if you want API keys and tokens, add --migrate-secrets.

What does not migrate automatically

What follows is archived under ~/.hermes/migration/openclaw/<timestamp>/archive/ for manual review. These are pieces that in Hermes are built with other commands or have no direct equivalent.

There are also two platforms that require manual action: WhatsApp (re-pair via QR with hermes whatsapp) and any token that in OpenClaw uses source: file or source: exec as SecretRef — the migration warns about these and leaves them unresolved.

Step 1 · Install and verify Hermes

Before moving anything, make sure Hermes Agent is running on the same machine with hermes --version green. The full installation guide (Linux, macOS, WSL2, Android, native Windows, no-sudo paths) is here:

~

# After installing Hermes, confirm the binary and the Gateway
hermes --version
hermes doctor

If you already have it installed and updated, you can skip straight to the preview. If not, install Hermes Agent and come back. Having both running in parallel is exactly what you want during the transition.

Step 2 · Preview the migration

Before touching anything, see what the command will do. The preview reads all OpenClaw state, looks for skills, providers, channels, and memory, and prints the full plan without writing anything:

~

# Preview the migration without modifying anything
hermes claw migrate --dry-run

By default it reads from ~/.openclaw/. If your install lives elsewhere (e.g. a custom profile or a container), pass the explicit path:

~

# Source on a custom path (e.g. profile or container)
hermes claw migrate --dry-run --source /path/to/openclaw

The preview shows you: files to copy, skills to import, providers and channels detected, secrets that will not be copied (by default), and conflicts. Read it carefully: if anything looks off, adjust before applying.

Step 3 · Run the migration

Once the preview looks right, apply the migration:

~

# Apply the migration (shows preview again and asks for confirmation)
hermes claw migrate

If you want a complete run in one shot — including API keys and no prompts — use this opt-in variant. Caveat: it carries secrets, so read it twice before running:

~

# Full opt-in path (includes API keys, no confirmation)
#   --preset full: imports everything compatible
#   --migrate-secrets: also API keys and tokens (strict allowlist)
#   --yes: skip the confirmation prompt
hermes claw migrate --preset full --migrate-secrets --yes

Useful flags if your situation calls for them:

• --workspace-target /path: where AGENTS.md goes (required to copy workspace instructions).
• --overwrite: force overwriting Hermes files that conflict. Without this flag, the migration refuses to apply on conflicts.
• --no-backup: skip the pre-migration snapshot under ~/.hermes/backups/pre-migration-*.zip. By default a restore point is always written before applying.
• --skill-conflict skip | overwrite | rename: how to resolve duplicate skills. rename keeps the imported one with the -imported suffix on the basename (e.g. my-skill → my-skill-imported).

Step 4 · Verify Hermes

After applying, the critical part is validating that Hermes is functional. Four commands, in this order:

~

# 1) Full check of config and deps
hermes doctor

# 2) Authentication with the migrated providers
hermes status

# 3) Effective config: check session_reset, terminal.cwd, model, providers
hermes config show

After the checks, start a new session (imported skills and memory entries take effect in new sessions, not the current one):

~

# 4) New session: imported skills should appear here
hermes

If anything is missing, hermes config show tells you which keys effectively got set. If an API key is missing, add it with hermes config set OPENROUTER_API_KEY your_key (or whichever variable applies). /skills lists the loaded skills.

Step 5 · Review channels and archived files

Channel tokens land in ~/.hermes/.env, but the Gateway doesn't reload them on its own. Restart it:

~

# Restart the Gateway so it picks up the migrated tokens
systemctl --user restart hermes-gateway

If you use WhatsApp, the migration cannot carry the session (WhatsApp uses QR pairing with Baileys, not a token). WHATSAPP_ALLOWED_USERS was saved so the allowlist is preserved, but the device must be re-paired:

~

# Re-pair WhatsApp via QR after migrating
hermes whatsapp

For everything that does not migrate automatically (cron, plugins, hooks, multi-agent, channel bindings, IDENTITY.md, TOOLS.md, HEARTBEAT.md, etc.), review the directory:

~

# Archived files for manual review
ls -la ~/.hermes/migration/openclaw/$(ls -t ~/.hermes/migration/openclaw/ | head -1)/archive/

Each folder inside (workspace/, cron-config.json, plugins-config.json, hooks-config.json, bindings.json, etc.) corresponds to the "How to recreate in Hermes" column in the table above. Recreate what you need using the matching column.

Step 6 · Clean up only after validating

Cleanup runs at the end, and only when everything above is green. The flow:

1. Stop the OpenClaw Gateway so it stops processing: openclaw gateway stop.
2. Preview what the Hermes cleanup will rename.
3. Apply the cleanup: renames OpenClaw directories to .pre-migration/ to avoid state confusion between the two agents.

~

# 1) Stop OpenClaw so it doesn't compete with Hermes
openclaw gateway stop

# 2) Preview what the Hermes cleanup will rename
hermes claw cleanup --dry-run

# 3) Apply cleanup (renames OpenClaw dirs to .pre-migration/)
hermes claw cleanup

If you want to fully remove OpenClaw (CLI + Gateway + state + workspace + app), follow the OpenClaw uninstall guide after the cleanup. Do not remove OpenClaw before validating that Hermes is stable.

Troubleshooting

The four most common errors during a migration, with the exact fix.

If your case is rarer (container install, Nix, Docker, multi-agent profile), the official migration guide has edge-case sections beyond this run.

Have a particular setup (multi-agent, custom providers, multiple channels) and want to validate the plan before running the migration? There's a CTA at the end with a free 30-minute call.