sidebar_position: 10 title: “Migrate from OpenClaw” description: “Complete guide to migrating your OpenClaw / Clawdbot setup to Hermes Agent — what gets migrated, how config maps, and what to check after.”

Migrate from OpenClaw

hermes claw migrate imports your OpenClaw (or legacy Clawdbot/Moldbot) setup into Hermes. This guide covers exactly what gets migrated, the config key mappings, and what to verify after migration.

Quick start

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

The migration always shows a full preview of what will be imported before making any changes. Review the list, then confirm to proceed.

Reads from ~/.openclaw/ by default. Legacy ~/.clawdbot/ or ~/.moltbot/ directories are detected automatically. Same for legacy config filenames (clawdbot.json, moltbot.json).

Options

What gets migrated

Persona, memory, and instructions

Workspace files are also checked at workspace.default/ and workspace-main/ as fallback paths (OpenClaw renamed workspace/ to workspace-main/ in recent versions, and uses workspace-{agentId} for multi-agent setups).

Skills (4 sources)

Skill conflicts are handled by --skill-conflict: skip leaves the existing Hermes skill, overwrite replaces it, rename creates a -imported copy.

Model and provider configuration

Agent behavior

Session reset policies

Note: OpenClaw also has session.resetTriggers (a simple string array like ["daily", "idle"]). If the structured session.reset isn’t present, the migration falls back to inferring from resetTriggers.

MCP servers

TTS (text-to-speech)

TTS settings are read from two OpenClaw config locations with this priority:

1. messages.tts.providers.{provider}.* (canonical location)
2. Top-level talk.providers.{provider}.* (fallback)
3. Legacy flat keys messages.tts.{provider}.* (oldest format)

Messaging platforms

Other config

Archived (no direct Hermes equivalent)

These are saved to ~/.hermes/migration/openclaw/<timestamp>/archive/ for manual review:

API key resolution

When --migrate-secrets is enabled, API 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 (keys like OPENROUTER_API_KEY, ANTHROPIC_API_KEY, etc.)
3. Config env sub-object — openclaw.json → "env" or "env"."vars" (some setups store keys here instead of a separate .env file)
4. Auth profiles — ~/.openclaw/agents/main/agent/auth-profiles.json (per-agent credentials)

Config values take priority. Each subsequent source fills any remaining gaps.

Supported key targets

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.

SecretRef handling

OpenClaw config values for tokens and API keys can be in three formats:

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

The migration resolves all three formats. 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" can’t be resolved automatically — the migration warns about these, and those values must be added to Hermes manually via hermes config set.

After migration

1. Check the migration report — printed on completion with counts of migrated, skipped, and conflicting items.

2. Review archived files — anything in ~/.hermes/migration/openclaw/<timestamp>/archive/ needs manual attention.

3. Start a new session — imported skills and memory entries take effect in new sessions, not the current one.

4. Verify API keys — run hermes status to check provider authentication.

5. Test messaging — if you migrated platform tokens, restart the gateway: systemctl --user restart hermes-gateway

6. Check session policies — verify hermes config get session_reset matches your expectations.

7. Re-pair WhatsApp — WhatsApp uses QR code pairing (Baileys), not token migration. Run hermes whatsapp to pair.

8. Archive cleanup — after confirming everything works, run hermes claw cleanup to rename leftover OpenClaw directories to .pre-migration/ (prevents state confusion).

Troubleshooting

“OpenClaw directory not found”

The migration checks ~/.openclaw/, then ~/.clawdbot/, then ~/.moltbot/. If your installation is elsewhere, use --source /path/to/your/openclaw.

“No provider API keys found”

Keys might be stored in several places depending on your OpenClaw version: inline in openclaw.json under models.providers.*.apiKey, in ~/.openclaw/.env, in the openclaw.json "env" sub-object, or in agents/main/agent/auth-profiles.json. The migration checks all four. If keys use source: "file" or source: "exec" SecretRefs, they can’t be resolved automatically — add them via hermes config set.

Skills not appearing after migration

Imported skills land in ~/.hermes/skills/openclaw-imports/. Start a new session for them to take effect, or run /skills to verify they’re loaded.

TTS voice not migrated

OpenClaw stores TTS settings in two places: messages.tts.providers.* and the top-level talk config. The migration checks both. If your voice ID was set via the OpenClaw UI (stored in a different path), you may need to set it manually: hermes config set tts.elevenlabs.voice_id YOUR_VOICE_ID.