✦
Hermes Agent
Open navigation menu

How-To Guide

How to Migrate from OpenClaw to Hermes Agent

Use hermes claw migrate to preview and import OpenClaw memory, skills, providers, MCP servers, channels, and settings, then verify archived items and secrets safely.

Quick answer

Run hermes claw migrate --dry-run first. Hermes auto-detects ~/.openclaw, legacy ~/.clawdbot and ~/.moltbot directories, previews every change, and creates a restore-point backup before the real migration. Use --preset full for compatible settings or --preset user-data for persona, memory, and skills. Secrets are never imported unless you explicitly add --migrate-secrets. Cron jobs, plugins, hooks, multi-agent bindings, and other settings without direct Hermes equivalents are archived for manual review rather than silently discarded.

The current migration command is safer and broader than copying files by hand. It merges and deduplicates memory, imports skills from four possible locations, maps model and provider settings, translates MCP and messaging configuration, and produces a report of migrated, skipped, conflicting, and archived items. This guide follows the official OpenClaw migration command and shows the verification work that still belongs to you after the import.

Deploy Hermes faster with FlyHermes

Managed cloud · API costs included · Skill library · Cancel anytime

Before you start:

  • ☑A working Hermes Agent install; run hermes doctor before importing anything
  • ☑The source OpenClaw directory, normally ~/.openclaw, or its legacy Clawdbot/Moltbot location
  • ☑A separate backup of the source directory and enough disk space for the default Hermes restore-point archive
  • ☑A decision about secrets: leave them out by default, or review the preview before adding --migrate-secrets

Steps

  1. 1

    Verify the clean Hermes destination

    Run hermes doctor, hermes config path, and hermes config env-path. If the destination already contains important profiles, skills, memory, or MCP servers, back it up before continuing and do not start with --overwrite.

  2. 2

    Preview the OpenClaw migration

    Run hermes claw migrate --dry-run. The command checks ~/.openclaw, then legacy ~/.clawdbot and ~/.moltbot locations, and prints the plan without writing. Use --source /path/to/openclaw for a custom directory.

  3. 3

    Choose full or user-data scope

    Use hermes claw migrate --preset full to import all compatible configuration without secrets. Use --preset user-data when you only want persona, memory, skills, and other user data while leaving infrastructure configuration behind.

  4. 4

    Handle secrets deliberately

    Neither preset imports secrets automatically. Add --migrate-secrets only after reviewing the preview. Hermes can resolve approved keys from OpenClaw config, .env, config env values, and auth profiles; file- or exec-based SecretRefs require manual setup. Never paste the migration report or .env contents into chat.

  5. 5

    Resolve conflicts before applying

    Existing Hermes files and MCP entries are protected by default. For skills, choose --skill-conflict skip, overwrite, or rename; skip is safest. Use global --overwrite only after inspecting every conflict and confirming the Hermes destination can be replaced.

  6. 6

    Apply the migration and preserve the backup

    Run the selected command without --dry-run and confirm the preview. By default Hermes writes ~/.hermes/backups/pre-migration-*.zip before applying changes. Keep that archive until the new setup has passed provider, memory, skill, MCP, and channel tests.

  7. 7

    Review imported and archived items

    Read the final counts and inspect ~/.hermes/migration/openclaw/<timestamp>/archive/. Cron jobs, plugins, hooks/webhooks, memory backends, multi-agent lists, channel bindings, and files such as HEARTBEAT.md are archived for manual recreation. Convert agents to Hermes profiles and periodic work to Hermes cron jobs instead of assuming they were activated.

  8. 8

    Start a new session and verify every runtime layer

    Start a new Hermes session so imported skills and memory load. Run hermes status, hermes skills list, hermes mcp list, and one hermes chat -q "Reply with exactly: migration ok" provider test. Restart the gateway, then test each real Telegram, Discord, Slack, or other channel. WhatsApp must be paired again by QR.

  9. 9

    Clean up only after a stable observation window

    Keep the old source and restore-point archive while you verify recurring jobs and day-to-day recall. When Hermes is stable, run hermes claw cleanup to rename leftover OpenClaw directories to .pre-migration/ and prevent the two state trees from being confused.

Pro Tips

  • 💡Use --workspace-target /path/to/project when you want OpenClaw AGENTS.md instructions copied into a specific project; it is not placed automatically without that flag.
  • 💡Imported skills land under ~/.hermes/skills/openclaw-imports/. Start a new session before judging whether they load or trigger.
  • 💡Memory and user-profile files are parsed, merged, and deduplicated rather than blindly replacing the existing Hermes memory files.
  • 💡Do not use --no-backup just to make the command faster. The default pre-migration zip is the simplest rollback path.
  • 💡If you want a clean project-specific bot rather than old-agent clutter, create a blank Hermes profile and cherry-pick only the approved secrets and skills.
  • 💡Compare the Hermes Agent vs OpenClaw decision page before migrating a production bot, and use FlyHermes pricing when the real goal is managed uptime rather than another self-hosted runtime.

Troubleshooting

❌ OpenClaw directory not found

✅ The command checks ~/.openclaw, ~/.clawdbot, and ~/.moltbot. If your data lives elsewhere, run hermes claw migrate --source /absolute/path/to/openclaw --dry-run and confirm that the preview finds the expected workspace and config.

❌ Migration refuses to apply because of conflicts

✅ Keep the safe default, inspect the conflicting Hermes files or MCP servers, and choose a per-skill skip or rename policy where possible. Use --overwrite only when replacing the existing Hermes destination is intentional.

❌ Provider API keys were not imported

✅ Secrets are excluded unless --migrate-secrets is present. The importer checks supported config values, OpenClaw .env, config env values, and auth profiles. File- and exec-based SecretRefs cannot be resolved automatically; add those credentials to the active Hermes profile manually and verify with hermes status.

❌ Skills or memory do not appear in the current chat

✅ Imported skills and memory are loaded for new sessions. Start a new session, run hermes skills list, and inspect ~/.hermes/skills/openclaw-imports/. Do not run a nonexistent memory reindex command as a generic fix; first verify the imported files and active profile.

❌ Cron jobs, hooks, or multi-agent routing did not start

✅ These items are archived for manual review because they do not map one-to-one. Inspect the timestamped migration archive, recreate periodic work with hermes cron create, map separate agents to Hermes profiles, and rebuild channel bindings explicitly.

❌ Messaging token exists but the bot is silent

✅ Run the provider smoke test first, restart the Hermes gateway, confirm the active profile and allowlists, and send one real message in the exact chat or thread. WhatsApp credentials are pairing state rather than a portable token, so pair it again by QR.

FAQ

What does hermes claw migrate import?

It imports compatible persona, memory, user profile, skills, model/provider settings, MCP servers, messaging tokens and allowlists, agent behavior, session reset policies, approval rules, TTS, browser settings, and selected API keys when explicitly authorized. Unsupported items are archived for manual review.

Does the OpenClaw migration copy API keys automatically?

No. Both full and user-data presets exclude secrets by default. Add --migrate-secrets explicitly after reviewing the dry-run plan.

Can I undo an OpenClaw to Hermes migration?

Hermes creates a pre-migration zip under ~/.hermes/backups/ by default. Keep that restore point and the original source directory until the migrated setup has passed all provider, memory, skill, MCP, cron, and channel checks.

Are OpenClaw cron jobs and plugins migrated automatically?

No. Cron, plugins, hooks, multi-agent bindings, and other settings without direct equivalents are archived under the timestamped migration directory so you can recreate them with Hermes cron, plugins, webhooks, and profiles.

Does the migration support Clawdbot or Moltbot data?

Yes. The command auto-detects legacy ~/.clawdbot and ~/.moltbot directories and legacy config filenames, or you can pass a custom source path.

Should I migrate everything into my main Hermes profile?

Not always. If the old setup is cluttered or contains secrets with different trust levels, use a clean Hermes profile and cherry-pick only the memory, skills, providers, and channel credentials you actually want.

Related setup and cost guides

Hermes Agent vs OpenClaw

Compare architecture, memory, skills, providers, channels, and the operational migration trade-off.

Install Hermes Agent

Get a clean destination working before importing any old agent state.

Hermes profiles guide

Keep projects, bots, secrets, sessions, skills, and memory in isolated profile boundaries.

Hermes Agent skills

Inspect, trigger, and maintain imported SKILL.md procedures after the migration.

FlyHermes pricing

Choose managed cloud when uptime and channel operations matter more than owning the migration.

Related Guides

openclawinstall hermes agenthermes agent profiles guideset up hermes memorycreate hermes skills