How to Migrate from Hermes to OpenClaw

OpenClaw's Hermes migration provider is built for a careful transition, not a blind copy. The docs describe a previewed, reversible import that redacts secrets in plans and reports and creates a verified backup before applying changes.

30-second answer

Use openclaw onboard --flow import for the fastest path when Hermes lives at ~/.hermes, or use openclaw migrate hermes --dry-run for scripted migration. Review the plan, then apply only after you understand which model config, MCP servers, workspace files, memory, and skills are moving.

Onboarding path

openclaw onboard --flow import
openclaw onboard --import-from hermes --import-source ~/.hermes

The onboarding wizard detects Hermes at the default home and shows a preview before applying. Imports require a fresh OpenClaw setup. If OpenClaw already has local state, reset intentionally or use direct migrate commands with overwrite only after reviewing the plan.

CLI path

openclaw migrate hermes --dry-run
openclaw migrate apply hermes --yes

Add --from <path> when Hermes lives outside ~/.hermes. The dry run is where you catch surprises: stale providers, old prompts, memory that should not be imported, or MCP servers that no longer exist.

What gets imported

The provider imports default model selection from Hermes config, configured model providers, and custom OpenAI-compatible endpoints from provider settings. It can also import MCP server definitions from Hermes MCP config keys.

Workspace files such as SOUL.md and AGENTS.md are copied into the OpenClaw agent workspace. Hermes memory files such as MEMORY.md and USER.md are appended to matching OpenClaw memory files instead of overwriting them. That append behavior protects existing destination structure but still needs human review.

Post-migration cleanup

After apply, inspect model routing, memory, user instructions, skills, and MCP definitions. Hermes prompts may assume different tool names or runtime behavior. Keep the imported material that still describes your operating preferences, then remove stale provider hacks before they confuse future agents.

Operator checklist

Dry-run, read the plan, confirm backup, apply, validate config, start a private session, test a harmless MCP server, and search memory for one known imported fact. Only then connect external channels or scheduled tasks.

The OpenClaw Playbook treats migration as a controlled handoff: keep the useful identity and memory, but make the new OpenClaw workspace explicit enough that the next agent session does not inherit mystery behavior from the old system.

Rollout plan

Treat How to Migrate from Hermes to OpenClaw as a workflow you roll out in stages, not a switch you flip once. Start with the smallest harmless proof: a status check, dry run, local-only call, private session, or read-only inspection. Confirm the documented behavior matches your installed OpenClaw version, then write the exact commands and expected output into the workspace so the next agent does not rely on memory or vibes.

For a production runbook, document installation state, service ownership, update cadence, rollback command, and the exact machine that owns the Gateway. Also write down what the agent may do alone, what requires approval, and what must stop immediately. That boundary is the difference between useful autonomy and a workflow that surprises the operator at the worst possible time.

Keep one rollback note beside the guide. It can be as simple as the command to disable a plugin, the channel to pause, the config key to revert, or the owner who must approve the next run. Include the proof that tells you rollback worked, and keep it visible near the production checklist for future maintainers. Agents are most useful when recovery is obvious.

After the first live run, review the transcript or logs while the details are fresh. Look for missing prerequisites, stale assumptions, broad prompts, confusing errors, and any external side effect that should have been gated. Tighten the guide, then repeat with one wider scope. The OpenClaw Playbook is built around this operating rhythm: cautious first proof, written runbook, verified automation, then gradual autonomy once the evidence is boring.