# How do you migrate from OpenClaw to Hermes Agent?

Canonical: https://clawdocx.com/docs/hermes-agent-migrate-from-openclaw
Author: Sam Okafor
Difficulty: INTERMEDIATE
Published: 2026-02-24
Updated: 2026-11-07

> Move an OpenClaw setup to Hermes Agent with hermes claw migrate: what it imports, what it only archives, the flags that matter and the parts you rebuild.

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.

| OpenClaw thing | What happens to it |
|---|---|
| `SOUL.md` | Copied directly to `~/.hermes/SOUL.md` |
| `MEMORY.md`, `USER.md` | Parsed into entries, merged with existing entries and deduplicated; daily memory files are merged into main memory |
| `AGENTS.md` | Migrated only when you pass `--workspace-target` |
| Skills | Collected from workspace, managed and shared, personal cross-project, and project-level shared skills |
| Default model, custom providers | Migrated, including custom base URLs and API types |
| Provider API keys | Only with `--migrate-secrets`, and only those on the allowlist |
| MCP servers | Command, args, env, cwd, URL and tool include/exclude filters, for both stdio and HTTP/SSE |
| Messaging tokens and allowlists | Telegram, Discord, Slack, WhatsApp, Signal, Matrix and Mattermost |
| Text to speech | Provider, voice and model for ElevenLabs, OpenAI and Edge, plus the TTS assets |
| Approval mode, command allowlist, browser CDP URL, Brave key, gateway auth token, working directory | Migrated |
| Cron jobs, plugins, hooks and webhooks, memory backend, skills registry, logging, UI identity, multi-agent list, channel bindings | **Archived only.** Rebuilt by hand |

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](/blog/hermes-agent-vs-openclaw) 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:

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

On native Windows, in PowerShell:

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

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

```bash
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:

```bash
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:

```bash
hermes claw migrate
```

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

```bash
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:

```bash
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?

| Flag | What it does |
|---|---|
| `--dry-run` | Shows what would be migrated, then stops |
| `--preset <name>` | `full` imports all compatible settings; `user-data` excludes infrastructure config. Neither imports secrets |
| `--migrate-secrets` | Includes API keys. Required even with `--preset full` |
| `--overwrite` | Overwrites existing Hermes files on conflict. Without it, a plan with conflicts will not apply |
| `--no-backup` | Skips the pre-migration zip snapshot of `~/.hermes/` |
| `--source <path>` | Uses a custom OpenClaw directory |
| `--workspace-target <path>` | Sets where `AGENTS.md` is placed |
| `--skill-conflict <mode>` | `skip` is the default; `overwrite` replaces; `rename` creates an `-imported` copy |
| `--yes` | Skips the confirmation prompt after the preview |

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?

| Item | Location |
|---|---|
| Persona | `~/.hermes/SOUL.md` |
| Workspace instructions | `AGENTS.md` at your `--workspace-target` path |
| Memory and user profile | `~/.hermes/memories/MEMORY.md`, `~/.hermes/memories/USER.md` |
| Skills | `~/.hermes/skills/openclaw-imports/` |
| Settings | `~/.hermes/config.yaml` |
| API keys and tokens | `~/.hermes/.env` |
| TTS assets | `~/.hermes/tts/` |
| Archived items | `~/.hermes/migration/openclaw/<timestamp>/archive/` |
| Pre-migration backup | `~/.hermes/backups/pre-migration-*.zip` |

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](/docs/agent-skills-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](/ai-agents/hermes-agent) tracks its pricing and skill format, the [OpenClaw hub](/ai-agents/openclaw) covers the setup you are leaving, and our general [migration guide](/docs/migration-guide) covers the version-to-version moves within a single agent rather than a move between two.

## Frequently asked questions

**What command migrates OpenClaw to Hermes Agent?**

hermes claw migrate. The documentation says the migration "always shows a full preview of what will be imported before making any changes" and then asks you to confirm, so running it bare is already a preview followed by a prompt. Add --dry-run if you want the preview and nothing else.

**Does the migration move my API keys?**

Not unless you ask. Neither the full nor the user-data preset imports secrets, so you have to pass --migrate-secrets, and it is required even alongside --preset full. Only keys on the documented allowlist are copied, and the docs say plainly that "keys not in this allowlist are never copied."

**What does hermes claw migrate not bring across?**

Cron jobs, plugins, hooks and webhooks, the memory backend, the skills registry, logging, UI identity, the multi-agent list, and channel bindings are archived rather than migrated. They land in ~/.hermes/migration/openclaw/<timestamp>/archive/ for you to rebuild by hand, and the docs name the Hermes command to use for each one.

**Where do my OpenClaw skills end up in Hermes?**

In ~/.hermes/skills/openclaw-imports/. Hermes treats ~/.hermes/skills/ as what its documentation calls the "single source of truth" for skills, and the imported ones arrive in that subfolder. They only take effect in a new session, so start one or run /skills to confirm they loaded.

**Is it safe to delete my OpenClaw directory afterwards?**

Use the built-in cleanup rather than deleting anything, and only once you have tested the result. hermes claw cleanup renames leftover OpenClaw directories to .pre-migration/ instead of removing them. The migration also takes a zip snapshot of ~/.hermes/ to ~/.hermes/backups/pre-migration-*.zip first, unless you pass --no-backup.

**Do I need to re-pair my messaging channels?**

WhatsApp yes, the others usually no. Tokens and allowlists migrate for Telegram, Discord, Slack, WhatsApp, Signal, Matrix and Mattermost, but the docs note that "WhatsApp uses QR code pairing (Baileys), not token migration", so you run hermes whatsapp again. If you migrated platform tokens, restart the gateway with systemctl --user restart hermes-gateway.

## Sources

- [Hermes Agent docs: Migrating from OpenClaw to Hermes](https://hermes-agent.nousresearch.com/docs/guides/migrate-from-openclaw)
- [Hermes Agent docs: Installation](https://hermes-agent.nousresearch.com/docs/getting-started/installation)
- [Hermes Agent docs: Skills](https://hermes-agent.nousresearch.com/docs/user-guide/features/skills)
- [Hermes Agent releases on GitHub](https://github.com/NousResearch/hermes-agent/releases)