Migrate from OpenClaw

# Migrate from OpenClaw | Hermes Agent Source: [https://hermes-agent.nousresearch.com/docs/guides/migrate-from-openclaw](https://hermes-agent.nousresearch.com/docs/guides/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\. 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](https://hermes-agent.nousresearch.com/docs/integrations/nous-portal)\. ## Quick start[​](https://hermes-agent.nousresearch.com/docs/guides/migrate-from-openclaw#quick-start) ``` # Preview then migrate (always shows a preview first, then asks to confirm)hermes claw migrate# Preview only, no changeshermes claw migrate --dry-run# Full migration including API keys, skip confirmationhermes 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[​](https://hermes-agent.nousresearch.com/docs/guides/migrate-from-openclaw#options) OptionDescription`\-\-dry\-run`Preview only — stop after showing what would be migrated\.`\-\-preset <name\>``full`\(all compatible settings\) or`user\-data`\(excludes infrastructure config\)\. Neither preset imports secrets by default — pass`\-\-migrate\-secrets`explicitly\.`\-\-overwrite`Overwrite existing Hermes files on conflicts \(default: refuse to apply when the plan has conflicts\)\.`\-\-migrate\-secrets`Include API keys\. Required even under`\-\-preset full`— no preset imports secrets silently\.`\-\-no\-backup`Skip 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 <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[​](https://hermes-agent.nousresearch.com/docs/guides/migrate-from-openclaw#what-gets-migrated) ### Persona, memory, and instructions[​](https://hermes-agent.nousresearch.com/docs/guides/migrate-from-openclaw#persona-memory-and-instructions) WhatOpenClaw sourceHermes destinationNotesPersona`workspace/SOUL\.md``~/\.hermes/SOUL\.md`Direct copyWorkspace instructions`workspace/AGENTS\.md``AGENTS\.md`in`\-\-workspace\-target`Requires`\-\-workspace\-target`flagLong\-term memory`workspace/MEMORY\.md``~/\.hermes/memories/MEMORY\.md`Parsed into entries, merged with existing, deduped\. Uses`§`delimiter\.User profile`workspace/USER\.md``~/\.hermes/memories/USER\.md`Same entry\-merge logic as memory\.Daily memory files`workspace/memory/\*\.md``~/\.hermes/memories/MEMORY\.md`All 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\)[​](https://hermes-agent.nousresearch.com/docs/guides/migrate-from-openclaw#skills-4-sources) SourceOpenClaw locationHermes destinationWorkspace skills`workspace/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 shared`workspace/\.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[​](https://hermes-agent.nousresearch.com/docs/guides/migrate-from-openclaw#model-and-provider-configuration) WhatOpenClaw config pathHermes destinationNotesDefault model`agents\.defaults\.model``config\.yaml`→`model`Can be a string or`\{primary, fallbacks\}`objectCustom providers`models\.providers\.\*``config\.yaml`→`custom\_providers`Maps`baseUrl`,`apiType`/`api`— handles both short \("openai", "anthropic"\) and hyphenated \("openai\-completions", "anthropic\-messages", "google\-generative\-ai"\) valuesProvider API keys`models\.providers\.\*\.apiKey``~/\.hermes/\.env`Requires`\-\-migrate\-secrets`\. See[API key resolution](https://hermes-agent.nousresearch.com/docs/guides/migrate-from-openclaw#api-key-resolution)below\.### Agent behavior[​](https://hermes-agent.nousresearch.com/docs/guides/migrate-from-openclaw#agent-behavior) WhatOpenClaw config pathHermes config pathMappingMax turns`agents\.defaults\.timeoutSeconds``agent\.max\_turns``timeoutSeconds / 10`, capped at 200Verbose mode`agents\.defaults\.verboseDefault``agent\.verbose`"off" / "on" / "full"Reasoning effort`agents\.defaults\.thinkingDefault``agent\.reasoning\_effort`"always"/"high"/"xhigh" → "high", "auto"/"medium"/"adaptive" → "medium", "off"/"low"/"none"/"minimal" → "low"Compression`agents\.defaults\.compaction\.mode``compression\.enabled`"off" → false, anything else → trueCompression model`agents\.defaults\.compaction\.model``compression\.summary\_model`Direct string copyHuman delay`agents\.defaults\.humanDelay\.mode``human\_delay\.mode`"natural" / "custom" / "off"Human delay timing`agents\.defaults\.humanDelay\.minMs`/`\.maxMs``human\_delay\.min\_ms`/`\.max\_ms`Direct copyTimezone`agents\.defaults\.userTimezone``timezone`Direct string copyExec timeout`tools\.exec\.timeoutSec``terminal\.timeout`Direct copy \(field is`timeoutSec`, not`timeout`\)Docker sandbox`agents\.defaults\.sandbox\.backend``terminal\.backend`"docker" → "docker"Docker image`agents\.defaults\.sandbox\.docker\.image``terminal\.docker\_image`Direct copy### Session reset policies[​](https://hermes-agent.nousresearch.com/docs/guides/migrate-from-openclaw#session-reset-policies) OpenClaw config pathHermes config pathNotes`session\.reset\.mode``session\_reset\.mode`"daily", "idle", or both`session\.reset\.atHour``session\_reset\.at\_hour`Hour \(0–23\) for daily reset`session\.reset\.idleMinutes``session\_reset\.idle\_minutes`Minutes of inactivityNote: 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[​](https://hermes-agent.nousresearch.com/docs/guides/migrate-from-openclaw#mcp-servers) OpenClaw fieldHermes fieldNotes`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 \(text\-to\-speech\)[​](https://hermes-agent.nousresearch.com/docs/guides/migrate-from-openclaw#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\) WhatHermes destinationProvider name`config\.yaml`→`tts\.provider`ElevenLabs voice ID`config\.yaml`→`tts\.elevenlabs\.voice\_id`ElevenLabs model ID`config\.yaml`→`tts\.elevenlabs\.model\_id`OpenAI model`config\.yaml`→`tts\.openai\.model`OpenAI voice`config\.yaml`→`tts\.openai\.voice`Edge TTS voice`config\.yaml`→`tts\.edge\.voice`\(OpenClaw renamed "edge" to "microsoft" — both are recognized\)TTS assets`~/\.hermes/tts/`\(file copy\)### Messaging platforms[​](https://hermes-agent.nousresearch.com/docs/guides/migrate-from-openclaw#messaging-platforms) PlatformOpenClaw config pathHermes`\.env`variableNotesTelegram`channels\.telegram\.botToken`or`\.accounts\.default\.botToken``TELEGRAM\_BOT\_TOKEN`Token can be string or[SecretRef](https://hermes-agent.nousresearch.com/docs/guides/migrate-from-openclaw#secretref-handling)\. Both flat and accounts layout supported\.Telegram`credentials/telegram\-default\-allowFrom\.json``TELEGRAM\_ALLOWED\_USERS`Comma\-joined from`allowFrom\[\]`arrayDiscord`channels\.discord\.token`or`\.accounts\.default\.token``DISCORD\_BOT\_TOKEN`Discord`channels\.discord\.allowFrom`or`\.accounts\.default\.allowFrom``DISCORD\_ALLOWED\_USERS`Slack`channels\.slack\.botToken`or`\.accounts\.default\.botToken``SLACK\_BOT\_TOKEN`Slack`channels\.slack\.appToken`or`\.accounts\.default\.appToken``SLACK\_APP\_TOKEN`Slack`channels\.slack\.allowFrom`or`\.accounts\.default\.allowFrom``SLACK\_ALLOWED\_USERS`WhatsApp`channels\.whatsapp\.allowFrom`or`\.accounts\.default\.allowFrom``WHATSAPP\_ALLOWED\_USERS`Auth via Baileys QR pairing — requires re\-pairing after migrationSignal`channels\.signal\.account`or`\.accounts\.default\.account``SIGNAL\_ACCOUNT`Signal`channels\.signal\.httpUrl`or`\.accounts\.default\.httpUrl``SIGNAL\_HTTP\_URL`Signal`channels\.signal\.allowFrom`or`\.accounts\.default\.allowFrom``SIGNAL\_ALLOWED\_USERS`Matrix`channels\.matrix\.accessToken`or`\.accounts\.default\.accessToken``MATRIX\_ACCESS\_TOKEN`Uses`accessToken`\(not`botToken`\)Mattermost`channels\.mattermost\.botToken`or`\.accounts\.default\.botToken``MATTERMOST\_BOT\_TOKEN`### Other config[​](https://hermes-agent.nousresearch.com/docs/guides/migrate-from-openclaw#other-config) WhatOpenClaw pathHermes pathNotesApproval mode`approvals\.exec\.mode``config\.yaml`→`approvals\.mode`"auto"→"off", "always"→"manual", "smart"→"smart"Command allowlist`exec\-approvals\.json``config\.yaml`→`command\_allowlist`Patterns merged and dedupedBrowser CDP URL`browser\.cdpUrl``config\.yaml`→`browser\.cdp\_url`Browser headless`browser\.headless``config\.yaml`→`browser\.headless`Brave search key`tools\.web\.search\.brave\.apiKey``\.env`→`BRAVE\_API\_KEY`Requires`\-\-migrate\-secrets`Gateway auth token`gateway\.auth\.token``\.env`→`HERMES\_GATEWAY\_TOKEN`Requires`\-\-migrate\-secrets`Working directory`agents\.defaults\.workspace``config\.yaml`→`terminal\.cwd`Legacy migrations may still emit`MESSAGING\_CWD`as a compatibility fallback### Archived \(no direct Hermes equivalent\)[​](https://hermes-agent.nousresearch.com/docs/guides/migrate-from-openclaw#archived-no-direct-hermes-equivalent) These are saved to`~/\.hermes/migration/openclaw/<timestamp\>/archive/`for manual review: WhatArchive fileHow to recreate in Hermes`IDENTITY\.md``archive/workspace/IDENTITY\.md`Merge into`SOUL\.md``TOOLS\.md``archive/workspace/TOOLS\.md`Hermes has built\-in tool instructions`HEARTBEAT\.md``archive/workspace/HEARTBEAT\.md`Use cron jobs for periodic tasks`BOOTSTRAP\.md``archive/workspace/BOOTSTRAP\.md`Use context files or skillsCron jobs`archive/cron\-config\.json`Recreate with`hermes cron create`Plugins`archive/plugins\-config\.json`See[plugins guide](https://hermes-agent.nousresearch.com/docs/user-guide/features/hooks)Hooks/webhooks`archive/hooks\-config\.json`Use`hermes webhook`or gateway hooksMemory backend`archive/memory\-backend\-config\.json`Configure via`hermes honcho`Skills registry`archive/skills\-registry\-config\.json`Use`hermes skills config`UI/identity`archive/ui\-identity\-config\.json`Use`/skin`commandLogging`archive/logging\-diagnostics\-config\.json`Set in`config\.yaml`logging sectionMulti\-agent list`archive/agents\-list\.json`Use Hermes profilesChannel bindings`archive/bindings\.json`Manual setup per platformComplex channels`archive/channels\-deep\-config\.json`Manual platform config## API key resolution[​](https://hermes-agent.nousresearch.com/docs/guides/migrate-from-openclaw#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[​](https://hermes-agent.nousresearch.com/docs/guides/migrate-from-openclaw#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[​](https://hermes-agent.nousresearch.com/docs/guides/migrate-from-openclaw#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[​](https://hermes-agent.nousresearch.com/docs/guides/migrate-from-openclaw#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**— run`hermes config show`and verify the`session\_reset`value 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[​](https://hermes-agent.nousresearch.com/docs/guides/migrate-from-openclaw#troubleshooting) ### "OpenClaw directory not found"[​](https://hermes-agent.nousresearch.com/docs/guides/migrate-from-openclaw#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"[​](https://hermes-agent.nousresearch.com/docs/guides/migrate-from-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[​](https://hermes-agent.nousresearch.com/docs/guides/migrate-from-openclaw#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[​](https://hermes-agent.nousresearch.com/docs/guides/migrate-from-openclaw#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`\.