OpenClaw migration from Hermes: import an agent without copying its baggage

An OpenClaw migration from Hermes should start with a plan, not a copy command. OpenClaw can import compatible model configuration, MCP servers, workspace files, memory, skills, and selected credentials. It intentionally leaves sessions, cron state, plugin state, logs, and Hermes databases out of live configuration. That boundary is the point: a useful migration preserves the parts you understand and forces a review of the parts you do not.

The current OpenClaw migration provider for Hermes is built around that approach. It previews changes, redacts secret-looking values in plans and reports, creates a verified backup for standalone imports, and treats unsupported state as archive material rather than something to execute automatically.

Contents

• What OpenClaw imports from Hermes
• Preview an OpenClaw migration from Hermes first
• Choose a migration path
• Keep credentials and runtime state separate
• Verify the new agent before moving work
• FAQ

What OpenClaw imports from Hermes

OpenClaw’s bundled Hermes provider maps the parts of an agent that can be reviewed as configuration or workspace content. It does not claim that two runtimes share a compatible internal state model.

Hermes surface	OpenClaw handling	Operator decision
Default model and supported providers	Imports compatible configuration and endpoints	Test the imported model route with a real completion
MCP servers	Imports compatible definitions, disabled state, timeouts, OAuth scope, and supported policy fields	Review anything requiring literal headers or environment variables
SOUL.md and AGENTS.md	Copies them into the OpenClaw agent workspace	Check that instructions still match the new tool and channel surface
MEMORY.md and USER.md	Appends them to matching OpenClaw memory files	Remove stale personal or operational assumptions before relying on them
Skills with SKILL.md	Discovers them recursively and copies support files	Review each skill’s permissions and external dependencies
Plugins, sessions, cron, logs, SQLite databases	Keeps them archive-only for manual review	Rebuild or migrate them with their own documented path

That last row is the most important. A session store, gateway process state, or plugin database may look portable because it lives under a familiar directory. It can still carry format, credential, or trust assumptions that OpenClaw should not inherit blindly. For a broader view of those layers, start with how OpenClaw works: Gateway, workspace, model routes, tools, and channels are connected, but they are not one blob of state.

Preview an OpenClaw migration from Hermes first

Use the preview as an inventory. It should answer three questions before anything changes: what OpenClaw found, what it can import safely, and what requires a human decision.

openclaw migrate hermes --dry-run

The command follows HERMES_HOME and the active Hermes profile before falling back to the normal platform location. If the source lives elsewhere, supply it explicitly:

openclaw migrate hermes --from /path/to/hermes-home --dry-run

A good review separates items into four buckets:

1. Carry over now: a known model endpoint, a small set of MCP servers, workspace instructions, and skills you have already audited.
2. Carry over after checking: memory files and credentials that you still need for a specific provider or channel.
3. Archive for later: sessions, logs, plugin state, cron jobs, and databases.
4. Do not move: expired credentials, experimental skills, abandoned integrations, and broad permissions that were convenient on the old machine.

The migration documentation says conflicts stop the plan from proceeding automatically. That is useful friction. A conflict means the target already has a file or value worth protecting, not that the migration command needs a larger hammer.

Choose a migration path

There are two supported ways to import Hermes state. The right one depends on whether OpenClaw is new or already configured.

Use onboarding for a fresh agent

For a fresh setup, OpenClaw can detect Hermes and stage imports while onboarding:

openclaw onboard --flow import

You can also name the source directly:

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

This path stages local artifacts and imported credentials, verifies or repairs imported inference in staging, then promotes workspace and agent state. It is the safer choice when you are setting up a new host because a working model route is proved before you treat the imported setup as complete. The onboarding overview explains the same principle for ordinary first-run setup: OpenClaw saves a model and credential only after a live completion succeeds.

Use the migration CLI for an existing install

For a scripted or repeatable migration into an existing OpenClaw setup, use the migration provider directly:

openclaw migrate apply hermes --yes

Standalone apply creates and verifies an OpenClaw backup before it changes existing local state. It also supports an interactive credential decision. For unattended automation, keep the default non-secret import unless you have a deliberate credential-transfer procedure. --include-secrets is an explicit opt-in, not a convenient default.

OpenClaw’s CLI migration reference also supports JSON plans. With --json and no --yes, apply prints the reviewed plan without mutating state. That is a useful mode for a change ticket or a shared operations script because the command can show the impact without quietly importing credentials.

Keep credentials and runtime state separate

Credentials are not ordinary configuration. OpenClaw can import selected Hermes OpenAI Codex OAuth entries, OpenCode OpenAI OAuth, GitHub Copilot entries, and supported .env keys if you approve that step. The docs also call out one awkward case: after importing Hermes OAuth, do not leave both runtimes using the same refresh grant. Reauthenticate one side before running both.

That is a good example of why migration needs an operating decision, not just file copying. Two agent runtimes sharing a refresh token can create confusing revocation, billing, or audit behavior. AI agent auth profiles covers the same underlying rule: provider identity should be explicit enough that an operator can tell which account and quota pool actually served a run.

Likewise, do not treat archive-only state as harmless. Hermes plugin directories, sessions, logs, cron definitions, pairing state, and SQLite databases may contain secrets or assumptions that only make sense inside Hermes. Preserve them for review if they matter. Do not load them into a live OpenClaw Gateway just because they survived the copy.

Verify the new agent before moving work

A completed import is not proof of a working agent. Verify the new runtime before you transfer production messages, schedules, or long-running work.

1. Run openclaw doctor and read the findings before applying a repair.
2. Confirm that the Gateway starts and that openclaw status reports the expected health.
3. Run one real model completion through the imported route.
4. Inspect the imported workspace files, memory, skills, and MCP server list.
5. Reconnect one non-critical channel or run one low-risk tool task before moving everything else.
6. Keep the Hermes archive until the new agent has handled representative work successfully.

This sequence prevents the usual migration mistake: discovering a missing provider route, unsupported MCP field, or stale credential only after all of the old automation has already been switched off. If your original system relied on background jobs, pair this with the agent data recovery guide so you can decide which schedules and durable records need a purpose-built recovery plan rather than a directory copy.

FAQ

What does an OpenClaw migration from Hermes import?

It can import compatible model and provider configuration, MCP server definitions, workspace instructions, Hermes memory files, skills, and supported credentials when you approve them. Plugins, sessions, cron state, logs, pairing state, and Hermes SQLite databases are archive-only because OpenClaw does not automatically trust or execute their runtime state.

Can I migrate Hermes credentials automatically?

OpenClaw asks before importing credentials interactively. In non-interactive use, credentials require an explicit --include-secrets option with --yes. Import only credentials you intend to use, then verify the new model route without printing secret values into logs or tickets.

Should I use onboarding or openclaw migrate?

Use openclaw onboard --flow import for a fresh installation that should verify inference before promotion. Use openclaw migrate when you need a repeatable, preview-first import into an existing OpenClaw setup. Both paths show the planned import before the final change.

Can I run Hermes and OpenClaw at the same time after migration?

Yes, but do not let both runtimes use the same imported OAuth refresh grant. Reauthenticate one side first, then move workflows gradually while you verify the correct model route, credentials, channel behavior, and skill ownership.

OpenClaw migration from Hermes: move intent, not opaque state

A safe OpenClaw migration from Hermes preserves useful intent: your model setup, reviewed tools, workspace instructions, and durable knowledge. It does not pretend that every session file, plugin database, or credential can cross a runtime boundary unchanged. Preview first, import in small pieces, verify a real agent task, and keep the old state archived until the new system earns trust.

Sources: OpenClaw: Migrating from Hermes, OpenClaw: openclaw migrate reference, OpenClaw migration guide, OpenClaw onboarding overview, OpenClaw Doctor