How to migrate from OpenClaw to Hermes Agent

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.

# 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:

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:

// 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