How do you migrate from OpenClaw to Hermes Agent?

Hermes Agent ships a migration command for exactly this, hermes claw migrate, and it moves your persona, memory, skills, model and provider settings, MCP servers, messaging tokens and text-to-speech config out of ~/.openclaw/ in one run. What it does not move is the automation layer: cron jobs, plugins, hooks and webhooks are archived for you to rebuild, not converted. Run it with --dry-run first, add --migrate-secrets only when you have read which keys it copies, and leave hermes claw cleanup until you have tested the result.

#What does hermes claw migrate actually move?

The command splits your OpenClaw setup into three piles: things it imports, things it converts into a Hermes equivalent, and things it files away for you to deal with. The third pile is the one that decides how long the migration really takes.

Some settings are converted rather than copied, which is worth knowing because the resulting value will not match what you had. The docs give max turns as the clearest example: it is derived from timeoutSeconds / 10 and capped at 200. Reasoning effort is remapped onto high, medium and low, and the compression toggle becomes a boolean, where off turns into false and anything else into true. The settings the docs mark as a direct copy are the compression model, the human-delay timing in minMs and maxMs, the timezone and the Docker image, plus the exec timeout, which keeps its value but moves field, from tools.exec.timeoutSec to terminal.timeout. Verbose mode, the human-delay mode and the Docker sandbox backend are listed as value mappings whose accepted names are the same on both sides.

If you have not decided between the two agents yet, our Hermes Agent versus OpenClaw comparison is the better page to read first, because this one assumes you have already chosen.

#What do you need before you start?

You need Hermes installed and an OpenClaw directory it can find.

The install script covers Linux, macOS and WSL2:

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

On native Windows, in PowerShell:

iex (irm https://hermes-agent.nousresearch.com/install.ps1)

Then reload your shell and start it once, so the data directory exists:

source ~/.bashrc   # or: source ~/.zshrc
hermes

Two platform details catch people out. The macOS installer is Apple Silicon only, and Intel Macs are unsupported. Android is supported on aarch64 through Termux, using the signed Termux APT repository and pkg install hermes-agent rather than the desktop or server script. The installer brings its own pinned Python, Node.js, npm, ripgrep and FFmpeg through its package manager instead of using whatever is on your system, so there is no Node version for you to satisfy.

On the OpenClaw side, the migration looks in ~/.openclaw/ by default and also detects the legacy ~/.clawdbot/ and ~/.moltbot/ directories and the clawdbot.json and moltbot.json filenames. If your install lives anywhere else, you will need --source.

One thing this command is not for: migrating from Claude Code or OpenAI Codex CLI. The docs point those at hermes import-agent instead.

#How do you run the migration safely?

Four steps, in this order.

1. Preview it. This shows what would be migrated and then stops without touching anything:

hermes claw migrate --dry-run

2. Read the plan for conflicts. Without --overwrite, a plan that has conflicts will not apply at all. That is the safe default, and it means a refusal here is information rather than a failure: something in Hermes already occupies a file the migration wants.

3. Run it. Bare is the cautious form, because the migration shows the full preview and asks for confirmation before changing anything:

hermes claw migrate

The documented one-shot form, which imports everything compatible including API keys and skips the prompt, is:

hermes claw migrate --preset full --migrate-secrets --yes

4. Verify before cleaning up. Start a new session, because imported skills and memory only take effect in one. Then:

hermes status
hermes claw cleanup

hermes status checks provider authentication, and /skills inside chat confirms your skills loaded. hermes claw cleanup renames leftover OpenClaw directories to .pre-migration/, so it is reversible, but run it only once you are satisfied.

#Which flags matter, and when?

Two of these are worth a second look. --skill-conflict defaults to skip, which leaves the existing Hermes skill in place, so a bundled Hermes skill with the same name as yours silently wins unless you pass rename. And --no-backup removes the one safety net the migration gives you for free, since the default is a zip snapshot of ~/.hermes/ at ~/.hermes/backups/pre-migration-*.zip, restorable with hermes import.

#Where does everything land on disk?

The skills path is the one to note. Hermes treats ~/.hermes/skills/ as what its documentation calls the "single source of truth" for skills, with bundled, hub-installed and agent-created skills all living there, so your imports arrive as a sibling folder of the rest rather than in a separate world. If you want the wider picture of where different agents keep skills, we cover it in where skills go.

#What has to be rebuilt by hand?

Everything in the archive folder, and the docs name the Hermes replacement for each one. This is the real work of the migration:

• Cron jobs. Recreate them with hermes cron create.
• HEARTBEAT.md. There is no equivalent file; use cron jobs.
• Plugins. Follow the plugins guide rather than expecting a conversion.
• Hooks and webhooks. Use hermes webhook or gateway hooks.
• Memory backend. Configure it through hermes honcho.
• Skills registry. Use hermes skills config.
• IDENTITY.md. Merge it into SOUL.md yourself.
• TOOLS.md. Drop it; Hermes has built-in tool instructions.
• BOOTSTRAP.md. Replace it with context files or skills.
• UI and identity. Use the /skin command.
• Logging. Set it in the logging section of config.yaml.
• Multi-agent list. Rebuild it as Hermes profiles.
• Channel bindings and complex channel config. Set these up manually per platform.

Session behaviour changes in a way no file captures, so budget for it rather than debugging it later: idle and daily reset timers are not imported, and a Hermes conversation persists until you run /new or /reset. Advanced session settings are archived for reference only.

#What about API keys and secrets?

Secrets are opt-in twice over: you need --migrate-secrets, and the key has to be on the allowlist. The documented allowlist covers OpenRouter, OpenAI, Anthropic, DeepSeek, Gemini, Z.AI, MiniMax, ElevenLabs, the Telegram bot token and the voice tools OpenAI key. Anything else is left behind, and the docs are explicit that "keys not in this allowlist are never copied."

Where it looks for them matters if a key seems to go missing. Four locations are searched in priority order: config values, ~/.openclaw/.env, the env sub-object in openclaw.json, and ~/.openclaw/agents/main/agent/auth-profiles.json. Config values win, and later sources fill only the remaining gaps.

One class of secret cannot be moved automatically at all. SecretRef objects whose source is "file" or "exec" cannot be resolved, so the migration warns about them and you add them yourself with hermes config set.

#What could go wrong?

The docs list four failures with specific causes, and each has a one-line answer.

• "OpenClaw directory not found". The default search covers ~/.openclaw/, ~/.clawdbot/ and ~/.moltbot/. Anywhere else needs --source.
• "No provider API keys found". The key is in one of the four locations above, or it is a SecretRef that cannot be resolved. Add those with hermes config set.
• Skills missing. You are still in the old session. Start a new one, or run /skills to confirm they loaded.
• TTS voice not migrated. A voice set through the OpenClaw UI may be stored somewhere the migration does not read. Set it with hermes config set tts.elevenlabs.voice_id YOUR_VOICE_ID.

A fifth is not an error at all but reads like one: the gateway. If you migrated platform tokens, restart it with systemctl --user restart hermes-gateway, or your channels will keep using the old credentials until you do.

#Where to go next

Run the dry run today and read its plan before you commit to anything; it is the cheapest part of this process and it tells you how much of your setup is in the archive pile. Keep OpenClaw installed until Hermes has run your real workload for a few days, because hermes claw cleanup is the only step here that is awkward to undo.

The Hermes Agent platform hub tracks its pricing and skill format, the OpenClaw hub covers the setup you are leaving, and our general migration guide covers the version-to-version moves within a single agent rather than a move between two.