Complete Guide: Migrate from OpenClaw to Hermes Agent

If you're an OpenClaw (or legacy Clawdbot / Moldbot) user, Hermes Agent offers a complete migration path. This guide walks you through moving your configs, memories, skills, and platform integrations to Hermes in one go.

Prerequisites

1. Install Hermes Agent

If you haven't installed Hermes yet, run the official one-line installer (Linux / macOS / WSL2 / Termux):

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

Then reload your shell:

source ~/.bashrc   # or source ~/.zshrc

Windows users must install WSL2 first before running the command above.

2. Confirm OpenClaw Directory Exists

The migration tool checks for your OpenClaw installation in this order:

1. ~/.openclaw/
2. ~/.clawdbot/ (older version)
3. ~/.moltbot/ (oldest version)

If installed elsewhere, use --source /your/path with the migration command.

---

Quick Start

Hermes provides a hermes claw migrate command to handle the entire migration. Three common patterns:

# Preview then confirm (recommended for first use)
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

We recommend running --dry-run first to see what will be migrated before committing.

---

Command Options

Option	Description
--dry-run	Preview only, no files modified
--preset <name>	full (default, includes secrets) or user-data (excludes API keys)
--overwrite	Overwrite existing Hermes files on conflicts (default: skip)
--migrate-secrets	Migrate API keys (on by default with --preset full)
--source <path>	Custom OpenClaw directory path
--workspace-target <path>	Where to place AGENTS.md
--skill-conflict <mode>	skip (default), overwrite, or rename (creates -imported copy)
--yes	Skip confirmation prompt after preview

---

What Gets Migrated

1. Persona, Memory & Instructions

Content	OpenClaw Path	Hermes Destination	Notes
Persona	workspace/SOUL.md	~/.hermes/SOUL.md	Direct copy
Workspace instructions	workspace/AGENTS.md	AGENTS.md at --workspace-target	Requires flag
Long-term memory	workspace/MEMORY.md	~/.hermes/memories/MEMORY.md	Parsed, merged, deduped with § delimiter
User profile	workspace/USER.md	~/.hermes/memories/USER.md	Entry-merge logic
Daily memory files	workspace/memory/*.md	~/.hermes/memories/MEMORY.md	All daily files merged into main

Fallback paths: If workspace/ doesn't exist, the tool checks workspace.default/ and workspace-main/.

2. Skills (4 Sources)

All skills are imported to ~/.hermes/skills/openclaw-imports/:

Source	OpenClaw Location	Hermes Destination
Workspace skills	workspace/skills/	~/.hermes/skills/openclaw-imports/
Managed/shared	~/.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/

Conflict handling via --skill-conflict:

• skip (default) — keep existing Hermes skill
• overwrite — replace with OpenClaw skill
• rename — create -imported copy

3. Model & Provider Configuration

Content	OpenClaw Config Path	Hermes Destination	Notes
Default model	agents.defaults.model	config.yaml → model	String or {primary, fallbacks} object
Custom providers	models.providers.*	config.yaml → custom_providers	Maps baseUrl, apiType/api
Provider API keys	models.providers.*.apiKey	~/.hermes/.env	Requires --migrate-secrets

4. Agent Behavior

Content	OpenClaw Path	Hermes Path	Mapping
Max turns	agents.defaults.timeoutSeconds	agent.max_turns	timeoutSeconds / 10, capped at 200
Verbose 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, else true
Compression model	agents.defaults.compaction.model	compression.summary_model	Direct copy
Human delay	agents.defaults.humanDelay.mode	human_delay.mode	natural / custom / off
Delay timing	agents.defaults.humanDelay.minMs / .maxMs	human_delay.min_ms / .max_ms	Direct copy
Timezone	agents.defaults.userTimezone	timezone	Direct copy
Exec timeout	tools.exec.timeoutSec	terminal.timeout	Direct copy
Docker sandbox	agents.defaults.sandbox.backend	terminal.backend	docker → docker
Docker image	agents.defaults.sandbox.docker.image	terminal.docker_image	Direct copy

5. Session Reset Policies

OpenClaw Path	Hermes Path	Notes
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 inactivity

Legacy fallback: If session.reset is missing, the tool infers from session.resetTriggers array.

6. Messaging Platforms

Telegram

OpenClaw Path	Hermes Env Variable	Notes
channels.telegram.botToken	TELEGRAM_BOT_TOKEN	Supports string, env template, and SecretRef formats
credentials/telegram-default-allowFrom.json	TELEGRAM_ALLOWED_USERS	Comma-joined from allowFrom[]

Discord

OpenClaw Path	Hermes Env Variable
channels.discord.token	DISCORD_BOT_TOKEN
channels.discord.allowFrom	DISCORD_ALLOWED_USERS

Slack

OpenClaw Path	Hermes Env Variable
channels.slack.botToken	SLACK_BOT_TOKEN
channels.slack.appToken	SLACK_APP_TOKEN
channels.slack.allowFrom	SLACK_ALLOWED_USERS

WhatsApp

OpenClaw Path	Hermes Env Variable	Notes
channels.whatsapp.allowFrom	WHATSAPP_ALLOWED_USERS	Uses Baileys QR pairing — must re-pair after migration

Signal

OpenClaw Path	Hermes Env Variable
channels.signal.account	SIGNAL_ACCOUNT
channels.signal.httpUrl	SIGNAL_HTTP_URL
channels.signal.allowFrom	SIGNAL_ALLOWED_USERS

Matrix

OpenClaw Path	Hermes Env Variable	Notes
channels.matrix.accessToken	MATRIX_ACCESS_TOKEN	Uses accessToken, not botToken

Mattermost

OpenClaw Path	Hermes Env Variable
channels.mattermost.botToken	MATTERMOST_BOT_TOKEN

7. MCP Servers

OpenClaw Field	Hermes Field	Notes
mcp.servers.*.command	mcp_servers.*.command	Stdio transport
mcp.servers.*.args	mcp_servers.*.args	Arguments
mcp.servers.*.env	mcp_servers.*.env	Environment variables
mcp.servers.*.cwd	mcp_servers.*.cwd	Working directory
mcp.servers.*.url	mcp_servers.*.url	HTTP/SSE transport
mcp.servers.*.tools.include	mcp_servers.*.tools.include	Tool allowlist
mcp.servers.*.tools.exclude	mcp_servers.*.tools.exclude	Tool blocklist

8. TTS Configuration

The migration tool reads TTS config from three locations in priority order:

1. messages.tts.providers.{provider}.* (canonical)
2. talk.providers.{provider}.* (fallback)
3. messages.tts.{provider}.* (oldest format)

Supports ElevenLabs (voice_id, model_id), OpenAI (model, voice), and Edge TTS (voice).

9. Other Config

Content	OpenClaw Path	Hermes Path	Notes
Approval mode	approvals.exec.mode	approvals.mode	auto → off, always → manual, smart → smart
Command allowlist	exec-approvals.json	command_allowlist	Merged and deduped
Browser CDP	browser.cdpUrl	browser.cdp_url	Direct copy
Brave search key	tools.web.search.brave.apiKey	BRAVE_API_KEY	Requires --migrate-secrets
Gateway token	gateway.auth.token	HERMES_GATEWAY_TOKEN	Requires --migrate-secrets
Working directory	agents.defaults.workspace	MESSAGING_CWD	Direct copy

---

API Key Handling

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

1. Config values — models.providers.*.apiKey and TTS 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

Supported Keys

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

Security: Keys not in this allowlist are never copied.

SecretRef Format Handling

OpenClaw tokens and API keys can appear in three formats — all are handled:

// 1. Plain string
{ "botToken": "123456:ABC-DEF..." }

// 2. Environment template
{ "botToken": "${TELEGRAM_BOT_TOKEN}" }

// 3. SecretRef object
{ "botToken": { "source": "env", "id": "TELEGRAM_BOT_TOKEN" } }

For source: "file" or source: "exec" SecretRef types, automatic resolution is not possible — the tool warns about these. Add values manually via hermes config set.

---

What Cannot Be Auto-Migrated

These items are archived to ~/.hermes/migration/openclaw/<timestamp>/archive/:

File	Archive Location	How 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
BOOTSTRAP.md	archive/workspace/BOOTSTRAP.md	Use context files or skills
Cron jobs	archive/cron-config.json	Recreate with hermes cron create
Plugins	archive/plugins-config.json	See Hermes plugins guide
Hooks/webhooks	archive/hooks-config.json	Use hermes webhook or gateway hooks
Memory 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 command
Logging	archive/logging-diagnostics-config.json	Set in config.yaml logging section
Multi-agent list	archive/agents-list.json	Use Hermes profiles
Channel bindings	archive/bindings.json	Manual platform config
Complex channels	archive/channels-deep-config.json	Manual platform config

---

Post-Migration Checklist

1. Review Migration Report

The summary printed on completion shows counts of migrated, skipped, and conflicting items.

2. Check Archived Files

Review ~/.hermes/migration/openclaw/<timestamp>/archive/ for items needing manual attention.

3. Start a New Session

Imported skills and memory entries take effect in new sessions only.

4. Verify API Keys

hermes status

5. Test Messaging Platforms

If you migrated platform tokens, restart the gateway:

systemctl --user restart hermes-gateway

6. Verify Session Policies

hermes config get session_reset

7. Re-pair WhatsApp

WhatsApp uses Baileys QR code pairing and cannot be migrated via token:

hermes whatsapp

8. Clean Up

After confirming everything works:

hermes claw cleanup

This renames leftover OpenClaw directories to .pre-migration/.

---

Troubleshooting

"OpenClaw directory not found"

The tool checks ~/.openclaw/, ~/.clawdbot/, and ~/.moltbot/. If installed elsewhere:

hermes claw migrate --source /path/to/your/openclaw

"No provider API keys found"

Keys may be stored in different locations depending on your OpenClaw version. The migration checks all four sources. For source: "file" or source: "exec" SecretRefs, add manually:

hermes config set providers.openrouter.api_key YOUR_KEY

Skills Not Appearing After Migration

Imported skills land in ~/.hermes/skills/openclaw-imports/. Start a new session, or run /skills to verify they're loaded.

TTS Voice Not Migrated

If voice ID was set via the OpenClaw UI (stored in a different path), set it manually:

hermes config set tts.elevenlabs.voice_id YOUR_VOICE_ID

---

Summary

The entire migration boils down to three steps:

1. hermes claw migrate --dry-run — preview first
2. hermes claw migrate --preset full — run the migration
3. Walk through the checklist — verify each module

The migration tool covers the vast majority of configurations automatically. Items it can't handle are archived with clear guidance on manual recreation — no data is lost.