Migrate from OpenClaw

Source: Hacker News

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.

tip

If your OpenClaw setup was multi-provider, hermes setup --portal collapses it to one OAuth — 300+ models plus the Tool Gateway in a single login. See Nous Portal.

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 --migrate-secrets --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​

OptionDescription--dry-runPreview only — stop after showing what would be migrated.--preset ``full (all compatible settings) or user-data (excludes infrastructure config). Neither preset imports secrets by default — pass --migrate-secrets explicitly.--overwriteOverwrite existing Hermes files on conflicts (default: refuse to apply when the plan has conflicts).--migrate-secretsInclude API keys. Required even under --preset full — no preset imports secrets silently.--no-backupSkip the pre-migration zip snapshot of ~/.hermes/ (by default a single restore-point archive is written before apply, under ~/.hermes/backups/pre-migration-*.zip; restorable with hermes import).--source Custom OpenClaw directory.--workspace-target Where to place AGENTS.md.--skill-conflict ``skip (default), overwrite, or rename.--yesSkip the confirmation prompt after preview.

What gets migrated​

Persona, memory, and instructions​

WhatOpenClaw sourceHermes destinationNotesPersonaworkspace/SOUL.md``~/.hermes/SOUL.mdDirect copyWorkspace instructionsworkspace/AGENTS.md``AGENTS.md in --workspace-targetRequires --workspace-target flagLong-term memoryworkspace/MEMORY.md``~/.hermes/memories/MEMORY.mdParsed into entries, merged with existing, deduped. Uses § delimiter.User profileworkspace/USER.md``~/.hermes/memories/USER.mdSame entry-merge logic as memory.Daily memory filesworkspace/memory/*.md``~/.hermes/memories/MEMORY.mdAll daily files merged into main memory.

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)​

SourceOpenClaw locationHermes destinationWorkspace skillsworkspace/skills/``~/.hermes/skills/openclaw-imports/Managed/shared skills~/.openclaw/skills/``~/.hermes/skills/openclaw-imports/Personal cross-project~/.agents/skills/``~/.hermes/skills/openclaw-imports/Project-level sharedworkspace/.agents/skills/``~/.hermes/skills/openclaw-imports/

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​

WhatOpenClaw config pathHermes destinationNotesDefault modelagents.defaults.model``config.yaml → modelCan be a string or {primary, fallbacks} objectCustom providersmodels.providers.*``config.yaml → custom_providersMaps baseUrl, apiType/api — handles both short (“openai”, “anthropic”) and hyphenated (“openai-completions”, “anthropic-messages”, “google-generative-ai”) valuesProvider API keysmodels.providers.*.apiKey``~/.hermes/.envRequires --migrate-secrets. See API key resolution below.

Agent behavior​

WhatOpenClaw config pathHermes config pathMappingMax turnsagents.defaults.timeoutSeconds``agent.max_turns``timeoutSeconds / 10, capped at 200Verbose modeagents.defaults.verboseDefault``agent.verbose”off” / “on” / “full”Reasoning effortagents.defaults.thinkingDefault``agent.reasoning_effort”always”/“high”/“xhigh” → “high”, “auto”/“medium”/“adaptive” → “medium”, “off”/“low”/“none”/“minimal” → “low”Compressionagents.defaults.compaction.mode``compression.enabled”off” → false, anything else → trueCompression modelagents.defaults.compaction.model``compression.summary_modelDirect string copyHuman delayagents.defaults.humanDelay.mode``human_delay.mode”natural” / “custom” / “off”Human delay timingagents.defaults.humanDelay.minMs / .maxMs``human_delay.min_ms / .max_msDirect copyTimezoneagents.defaults.userTimezone``timezoneDirect string copyExec timeouttools.exec.timeoutSec``terminal.timeoutDirect copy (field is timeoutSec, not timeout)Docker sandboxagents.defaults.sandbox.backend``terminal.backend”docker” → “docker”Docker imageagents.defaults.sandbox.docker.image``terminal.docker_imageDirect copy

Session reset policies​

OpenClaw config pathHermes config pathNotessession.reset.mode``session_reset.mode”daily”, “idle”, or bothsession.reset.atHour``session_reset.at_hourHour (0–23) for daily resetsession.reset.idleMinutes``session_reset.idle_minutesMinutes of inactivity

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​

OpenClaw fieldHermes fieldNotesmcp.servers.*.command``mcp_servers.*.commandStdio transportmcp.servers.*.args``mcp_servers.*.args``mcp.servers.*.env``mcp_servers.*.env``mcp.servers.*.cwd``mcp_servers.*.cwd``mcp.servers.*.url``mcp_servers.*.urlHTTP/SSE transportmcp.servers.*.tools.include``mcp_servers.*.tools.includeTool filteringmcp.servers.*.tools.exclude``mcp_servers.*.tools.exclude

TTS (text-to-speech)​

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

• messages.tts.providers.{provider}.* (canonical location)

• Top-level talk.providers.{provider}.* (fallback)

• Legacy flat keys messages.tts.{provider}.* (oldest format)

WhatHermes destinationProvider nameconfig.yaml → tts.providerElevenLabs voice IDconfig.yaml → tts.elevenlabs.voice_idElevenLabs model IDconfig.yaml → tts.elevenlabs.model_idOpenAI modelconfig.yaml → tts.openai.modelOpenAI voiceconfig.yaml → tts.openai.voiceEdge TTS voiceconfig.yaml → tts.edge.voice (OpenClaw renamed “edge” to “microsoft” — both are recognized)TTS assets~/.hermes/tts/ (file copy)

Messaging platforms​

PlatformOpenClaw config pathHermes .env variableNotesTelegramchannels.telegram.botToken or .accounts.default.botToken``TELEGRAM_BOT_TOKENToken can be string or SecretRef. Both flat and accounts layout supported.Telegramcredentials/telegram-default-allowFrom.json``TELEGRAM_ALLOWED_USERSComma-joined from allowFrom[] arrayDiscordchannels.discord.token or .accounts.default.token``DISCORD_BOT_TOKENDiscordchannels.discord.allowFrom or .accounts.default.allowFrom``DISCORD_ALLOWED_USERSSlackchannels.slack.botToken or .accounts.default.botToken``SLACK_BOT_TOKENSlackchannels.slack.appToken or .accounts.default.appToken``SLACK_APP_TOKENSlackchannels.slack.allowFrom or .accounts.default.allowFrom``SLACK_ALLOWED_USERSWhatsAppchannels.whatsapp.allowFrom or .accounts.default.allowFrom``WHATSAPP_ALLOWED_USERSAuth via Baileys QR pairing — requires re-pairing after migrationSignalchannels.signal.account or .accounts.default.account``SIGNAL_ACCOUNTSignalchannels.signal.httpUrl or .accounts.default.httpUrl``SIGNAL_HTTP_URLSignalchannels.signal.allowFrom or .accounts.default.allowFrom``SIGNAL_ALLOWED_USERSMatrixchannels.matrix.accessToken or .accounts.default.accessToken``MATRIX_ACCESS_TOKENUses accessToken (not botToken)Mattermostchannels.mattermost.botToken or .accounts.default.botToken``MATTERMOST_BOT_TOKEN

Other config​

WhatOpenClaw pathHermes pathNotesApproval modeapprovals.exec.mode``config.yaml → approvals.mode”auto”→“off”, “always”→“manual”, “smart”→“smart”Command allowlistexec-approvals.json``config.yaml → command_allowlistPatterns merged and dedupedBrowser CDP URLbrowser.cdpUrl``config.yaml → browser.cdp_urlBrowser headlessbrowser.headless``config.yaml → browser.headlessBrave search keytools.web.search.brave.apiKey``.env → BRAVE_API_KEYRequires --migrate-secretsGateway auth tokengateway.auth.token``.env → HERMES_GATEWAY_TOKENRequires --migrate-secretsWorking directoryagents.defaults.workspace``config.yaml → terminal.cwdLegacy migrations may still emit MESSAGING_CWD as a compatibility fallback

Archived (no direct Hermes equivalent)​

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

WhatArchive fileHow to recreate in HermesIDENTITY.md``archive/workspace/IDENTITY.mdMerge into SOUL.md``TOOLS.md``archive/workspace/TOOLS.mdHermes has built-in tool instructionsHEARTBEAT.md``archive/workspace/HEARTBEAT.mdUse cron jobs for periodic tasksBOOTSTRAP.md``archive/workspace/BOOTSTRAP.mdUse context files or skillsCron jobsarchive/cron-config.jsonRecreate with hermes cron createPluginsarchive/plugins-config.jsonSee plugins guideHooks/webhooksarchive/hooks-config.jsonUse hermes webhook or gateway hooksMemory backendarchive/memory-backend-config.jsonConfigure via hermes honchoSkills registryarchive/skills-registry-config.jsonUse hermes skills configUI/identityarchive/ui-identity-config.jsonUse /skin commandLoggingarchive/logging-diagnostics-config.jsonSet in config.yaml logging sectionMulti-agent listarchive/agents-list.jsonUse Hermes profilesChannel bindingsarchive/bindings.jsonManual setup per platformComplex channelsarchive/channels-deep-config.jsonManual platform config

API key resolution​

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

• Config values — models.providers.*.apiKey and TTS provider keys in openclaw.json

• Environment file — ~/.openclaw/.env (keys like OPENROUTER_API_KEY, ANTHROPIC_API_KEY, etc.)

• Config env sub-object — openclaw.json → "env" or "env"."vars" (some setups store keys here instead of a separate .env file)

• 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​

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

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

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

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

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

Check session policies — run hermes config show and verify the session_reset value matches your expectations.

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

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.