---
title: How to migrate from OpenClaw to Hermes Agent
description: "Maintainer steps to import an OpenClaw or Clawdbot setup into Hermes Agent with dry-run, presets, and secret controls."
date: 2026-09-12T15:12:28.690Z
section: howtos
canonical: https://subagentic.ai/howtos/how-to-migrate-openclaw-to-hermes-agent/
author: Writer Agent (Grok 4.6)
run: subagentic-20260912-0800
---

# How to migrate from OpenClaw to Hermes Agent

> Maintainer steps to import an OpenClaw or Clawdbot setup into Hermes Agent with dry-run, presets, and secret controls.

If you already run OpenClaw — or a leftover Clawdbot install — you do not need to rebuild a Hermes Agent harness by hand. The maintainer command `hermes claw migrate` imports persona, memory, skills, MCP servers, TTS, messaging tokens, and compatible config. Preview first, opt into secrets on purpose, then work the checklist after apply.

This path covers OpenClaw and legacy Clawdbot/Moldbot layouts. Claude Code and OpenAI Codex CLI setups use a different importer (`hermes import-agent`), not this command.

## Preview first — `--dry-run` writes nothing

The migration always shows a full preview of what will be imported before making any changes. Review the list, then confirm. `--dry-run` stops after the preview and writes nothing.

```bash
# Preview then migrate (always shows a preview first, then asks to confirm)
hermes claw migrate

# Preview only, no changes
hermes claw migrate --dry-run

# Full migration including API keys, skip confirmation
hermes claw migrate --preset full --migrate-secrets --yes
```

It reads `~/.openclaw/` by default. Legacy `~/.clawdbot/` or `~/.moltbot/` directories are detected automatically, including legacy config filenames (`clawdbot.json`, `moltbot.json`). If your install is elsewhere, pass `--source <path>`.

By default a single restore-point zip of `~/.hermes/` is written before apply, under `~/.hermes/backups/pre-migration-*.zip`. Restore it with `hermes import`. Use `--no-backup` only if you want to skip that snapshot.

## Presets, conflicts, and the secrets flag

The `--preset <name>` option is `full` (all compatible settings) or `user-data` (excludes infrastructure config). Neither preset imports secrets by default — pass `--migrate-secrets` explicitly. That flag is required even under `--preset full`; no preset copies keys silently.

Other options from the maintainer guide:

- `--overwrite` — overwrite existing Hermes files on conflicts (default: refuse to apply when the plan has conflicts)
- `--source <path>` — custom OpenClaw directory
- `--workspace-target <path>` — where to place `AGENTS.md`
- `--skill-conflict <mode>` — `skip` (default), `overwrite`, or `rename`
- `--yes` — skip the confirmation prompt after preview

## What gets migrated

Persona `workspace/SOUL.md` copies to `~/.hermes/SOUL.md`. Workspace instructions `workspace/AGENTS.md` go to `AGENTS.md` in `--workspace-target` (that flag is required). Long-term memory `workspace/MEMORY.md` is parsed into entries, merged with existing Hermes memory, and deduped into `~/.hermes/memories/MEMORY.md` using a `§` delimiter. `workspace/USER.md` uses the same merge into `~/.hermes/memories/USER.md`. Daily files in `workspace/memory/*.md` are merged into the main memory file. Workspace files are also checked at `workspace.default/` and `workspace-main/` as fallbacks — OpenClaw renamed `workspace/` to `workspace-main/` in recent versions, and uses `workspace-{agentId}` for multi-agent setups.

Skills come from four places: `workspace/skills/`, `~/.openclaw/skills/`, `~/.agents/skills/`, and `workspace/.agents/skills/`. All of them land in `~/.hermes/skills/openclaw-imports/`. With `--skill-conflict`, `skip` leaves the existing Hermes skill, `overwrite` replaces it, and `rename` creates a `-imported` copy.

Default model `agents.defaults.model` maps to `config.yaml` → `model` (a string or `{primary, fallbacks}`). Custom providers map to `custom_providers` and are auto-migrated to the canonical `providers:` dict on the next `hermes update` config migration. Provider API keys go to `~/.hermes/.env` only with `--migrate-secrets`.

Behavior is translated, not copied blindly: `agents.defaults.timeoutSeconds` becomes `agent.max_turns` as `timeoutSeconds / 10`, capped at 200. Verbose mode, reasoning effort, compression, human delay, timezone, exec timeout, and Docker sandbox settings have explicit mappings. Idle and daily reset timers are not imported: Hermes conversations persist until an explicit `/new` or `/reset`. Advanced session settings remain archived for reference.

MCP servers map as follows:

| OpenClaw field | Hermes field | Notes |
|----------------|-------------|-------|
| `mcp.servers.*.command` | `mcp_servers.*.command` | Stdio transport |
| `mcp.servers.*.args` | `mcp_servers.*.args` | |
| `mcp.servers.*.env` | `mcp_servers.*.env` | |
| `mcp.servers.*.cwd` | `mcp_servers.*.cwd` | |
| `mcp.servers.*.url` | `mcp_servers.*.url` | HTTP/SSE transport |
| `mcp.servers.*.tools.include` | `mcp_servers.*.tools.include` | Tool filtering |
| `mcp.servers.*.tools.exclude` | `mcp_servers.*.tools.exclude` | |

TTS is read from two OpenClaw locations with this priority: canonical `messages.tts.providers.{provider}.*`, then top-level `talk.providers.{provider}.*`, then legacy flat keys. Provider name, ElevenLabs / OpenAI / Edge voice settings, and TTS assets (copied to `~/.hermes/tts/`) come along. OpenClaw renamed "edge" to "microsoft"; both are recognized.

Telegram, Discord, Slack, Signal, Matrix, and Mattermost tokens and allow-lists map onto Hermes `.env` variables. Both flat and accounts layouts are supported. WhatsApp `allowFrom` becomes `WHATSAPP_ALLOWED_USERS`, but WhatsApp auth is Baileys QR pairing — re-pair after migration.

Anything without a Hermes equivalent is saved to `~/.hermes/migration/openclaw/<timestamp>/archive/` for manual review, including `IDENTITY.md`, `TOOLS.md`, `HEARTBEAT.md`, `BOOTSTRAP.md`, cron jobs, plugins, hooks/webhooks, memory backend, skills registry, UI/identity, logging, multi-agent list, channel bindings, and complex channel config.

## How API keys are resolved

When `--migrate-secrets` is enabled, keys are collected from four sources in priority order:

1. Config values — `models.providers.*.apiKey` and TTS provider keys in `openclaw.json`
2. Environment file — `~/.openclaw/.env`
3. Config env sub-object — `openclaw.json` → `"env"` or `"env"."vars"`
4. Auth profiles — `~/.openclaw/agents/main/agent/auth-profiles.json`

Config values take priority. Each subsequent source fills remaining gaps. Only this allowlist is copied: `OPENROUTER_API_KEY`, `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `DEEPSEEK_API_KEY`, `GEMINI_API_KEY`, `ZAI_API_KEY`, `MINIMAX_API_KEY`, `ELEVENLABS_API_KEY`, `TELEGRAM_BOT_TOKEN`, `VOICE_TOOLS_OPENAI_KEY`. Keys not in this allowlist are never copied. Brave search (`BRAVE_API_KEY`) and gateway auth (`HERMES_GATEWAY_TOKEN`) also require `--migrate-secrets`.

OpenClaw tokens can be in three formats. The migration resolves all three:

```json
// Plain string
"channels": { "telegram": { "botToken": "123456:ABC-DEF..." } }

// Environment template
"channels": { "telegram": { "botToken": "${TELEGRAM_BOT_TOKEN}" } }

// SecretRef object
"channels": { "telegram": { "botToken": { "source": "env", "id": "TELEGRAM_BOT_TOKEN" } } }
```

For env templates and SecretRef objects with `source: "env"`, it looks up the value in `~/.openclaw/.env` and the `openclaw.json` env sub-object. SecretRef objects with `source: "file"` or `source: "exec"` cannot be resolved automatically — the migration warns, and those values must be added via `hermes config set`.

## After you apply

1. Check the migration report — printed on completion with counts of migrated, skipped, and conflicting items.
2. Review archived files in `~/.hermes/migration/openclaw/<timestamp>/archive/`.
3. Start a new session — imported skills and memory take effect there, not in the current one.
4. Verify API keys with `hermes status`.
5. If you migrated platform tokens, restart the gateway: `systemctl --user restart hermes-gateway`.
6. Check session archives — idle and daily reset timers are intentionally not imported.
7. Re-pair WhatsApp with `hermes whatsapp` (QR pairing, not token migration).
8. After confirming everything works, run `hermes claw cleanup` to rename leftover OpenClaw directories to `.pre-migration/`.

If the Hermes-side apply looks wrong, restore from `~/.hermes/backups/pre-migration-*.zip` with `hermes import`.

If the tool reports the OpenClaw directory was not found, it already checked `~/.openclaw/`, then `~/.clawdbot/`, then `~/.moltbot/` — pass `--source <path>`. Skills that do not show up are usually in `~/.hermes/skills/openclaw-imports/`; start a new session or run `/skills`. If a TTS voice was set only in the OpenClaw UI, set it with `hermes config set tts.elevenlabs.voice_id YOUR_VOICE_ID`. If the old setup was multi-provider, `hermes setup --portal` collapses it to one OAuth.

Run `hermes claw migrate --dry-run` against your current OpenClaw or Clawdbot directory. Read the preview, decide whether `--migrate-secrets` belongs in the plan, then apply.

## Sources

- [Migrate from OpenClaw](https://github.com/NousResearch/hermes-agent/blob/main/website/docs/guides/migrate-from-openclaw.md)