Migrate from Hermes to OpenClaw

The bundled Hermes migration provider operates according to HERMES_HOME and whichever Hermes profile is currently active. On macOS or Linux it defaults to ~/.hermes, and on Windows to %LOCALAPPDATA%\hermes. Every modification is shown as a preview before being executed, and secrets are hidden from plans and reports. A standalone openclaw migrate run creates a verified backup. The fresh onboarding workflow stages configuration, credentials, and files, publishing them only after imported inference confirms the changes. An explicit --from path takes precedence over all others.

Note

A clean OpenClaw installation is required for imports. If local OpenClaw state already exists, reset the configuration, credentials, sessions, and workspace first. Alternatively, use openclaw migrate apply hermes directly with --overwrite after examining the plan.

Two ways to import

Onboarding wizard

Detects the currently active Hermes home directory and profile, then displays a preview before performing the migration.

openclaw onboard --flow import

To target a particular source, use:

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

CLI

For scripted or repeatable executions, use openclaw migrate. The full reference is available at openclaw migrate.

openclaw migrate hermes --dry-run    # preview only
openclaw migrate apply hermes --yes  # apply with confirmation skipped

Include --from <path> to override automatic Hermes home and profile detection.

What gets imported

Model configuration

Default model selection is taken from Hermes config.yaml.
Configured model providers and custom endpoints are sourced from model, providers, and custom_providers. This includes the current Hermes Chat Completions, Codex Responses, and Anthropic Messages transports.

MCP servers

MCP server definitions from mcp_servers or mcp.servers are migrated, preserving disabled state, timeouts, parallel-tool support, OAuth scope, compatible TLS fields, and native, resource, and prompt tool policies. Literal environment variables and headers require credential import consent. Settings exclusive to Hermes, such as lifecycle, sampling, elicitation, preflight, keepalive, CA bundle, password-protected client key, and pre-registered OAuth client, are flagged for manual review rather than converted to invalid OpenClaw configuration.

Workspace files

SOUL.md and AGENTS.md are copied into the OpenClaw agent workspace.
memories/MEMORY.md and memories/USER.md are appended to the corresponding OpenClaw memory files, not overwritten.
Memory-only surfaces behave differently: the onboarding memory page and the Control UI Memory import page place these two files under memory/imports/hermes/ for indexed recall, leaving existing workspace memory unchanged.

Memory configuration

Memory configuration defaults to OpenClaw file memory. External memory providers, such as Honcho, are recorded as archive or manual review items so you can migrate them intentionally.

Skills

Skills containing a SKILL.md file anywhere under skills/ are discovered recursively, flattened into the OpenClaw workspace skill directory, and copied along with their supporting files. Per-skill configuration values from skills.config are retained.

Auth credentials

Interactive openclaw migrate prompts before importing authentication credentials, with yes preselected. Accepted imports include current Hermes OpenAI Codex OAuth entries, OpenCode OpenAI OAuth and GitHub Copilot entries, and the supported Hermes .env keys. Use --include-secrets for a non-interactive import, --no-auth-credentials to skip credentials entirely, or the onboarding --import-secrets flag. After importing Hermes OAuth, do not let both Hermes and OpenClaw share the same refresh grant; reauthenticate one side before running both simultaneously.

What stays archive-only

The provider copies these items into the migration report directory for manual inspection, but does not load them into the active OpenClaw configuration or credentials store.

plugins/
sessions/
logs/
cron/
mcp-tokens/
plans/, workspace/, skins/, and kanban/
pairing/ and platforms/ stores, plus gateway routing/process state
state.db, hermes_state.db, projects.db, response_store.db, memory_store.db, verification_evidence.db, kanban.db, and retaindb_queue.db

Because formats and trust assumptions may diverge between environments, OpenClaw will not automatically run or accept this state. After reviewing the archive, manually transfer only what you need.

Recommended flow

Preview the plan

openclaw migrate hermes --dry-run

Every change is listed in the plan, including conflicts, omitted entries, and sensitive items. Keys that look like nested secrets are hidden in the output.

Apply with backup

openclaw migrate apply hermes --yes

A backup is created and validated by OpenClaw prior to applying changes. This non-interactive example imports only non-secret state. Omit --yes to get an interactive credential prompt, or supply --include-secrets to handle supported credentials during an automated run.

Run doctor

openclaw doctor

Doctor runs any pending config migrations and checks for problems that arose during the import.

Restart and verify

openclaw gateway restart
openclaw status

Verify that the gateway is healthy and that your imported model, memory, and skills are present.

Conflict handling

When the plan shows conflicts (a file or config value already exists at the destination), Apply will not proceed.

Warning

Only rerun with --overwrite if you intend to replace the existing target. Providers may still create item-level backups for overwritten files inside the migration report directory.

On a fresh install, conflicts are rare. They usually appear when you run the import again against a system that already contains user modifications.

If a conflict occurs mid-apply (for instance, an unexpected race on a config file), that item is flagged as a conflict while other files, skills, credentials, archives, and config entries continue unaffected. Resolve the conflicting item and re-run the import; importing the same memory again is idempotent.

Secrets

Interactive openclaw migrate prompts about importing detected auth credentials, with yes as the default.

Accepting imports current Hermes OpenAI Codex OAuth entries, OpenCode OpenAI OAuth and GitHub Copilot entries, and the supported .env keys.
To import only non-secret state, use --no-auth-credentials or answer no at the prompt.
To import credentials in an unattended --yes run, use --include-secrets.
To import credentials from the onboarding wizard, use its --import-secrets flag.

JSON output for automation

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

With --json and without --yes, apply prints the plan and does not modify state. This is the safest option for CI and shared scripts.

Troubleshooting

Apply refuses with conflicts

Review the plan output. Every conflict shows the source path and the existing target. For each item, choose to skip it, edit the target, or re-run with --overwrite.

Hermes lives outside ~/.hermes

Pass --from /actual/path (CLI) or --import-source /actual/path (onboarding).

Onboarding refuses to import on an existing setup

Onboarding imports need a fresh setup. Either reset state and re-onboard, or use openclaw migrate apply hermes directly, which supports --overwrite and explicit backup control.

API keys did not import

When running interactively, openclaw migrate only imports API keys after you approve the credential prompt. For non-interactive --yes operations, --include-secrets is required; onboarding imports depend on --import-secrets. Only the supported .env keys are accepted, any other .env variables are disregarded.

openclaw migrate: complete CLI reference, plugin contract, and JSON schemas.
Onboarding: guided setup and non-interactive flags.
Migrating: transferring an OpenClaw installation to another machine.
Doctor: verification tool for post-migration integrity.
Agent workspace: location of SOUL.md, AGENTS.md, and memory files.