Migrating from Hermes

OpenClaw imports Hermes state through a bundled migration provider. The provider previews everything before changing state, redacts secrets in plans and reports, and creates a verified backup before apply.

Two ways to import

text
Copy
```bash}
openclaw onboard --flow import
```

Or point at a specific source:

```bash}
openclaw onboard --import-from hermes --import-source ~/.hermes
```

text
Copy
```bash}
openclaw migrate hermes --dry-run    # preview only
openclaw migrate apply hermes --yes  # apply with confirmation skipped
```

Add `--from <path>` when Hermes lives outside `~/.hermes`.

What gets imported

What stays archive-only

The provider copies these into the migration report directory for manual review, but does not load them into live OpenClaw config or credentials:

• text

  Copy

  plugins/
• text

  Copy

  sessions/
• text

  Copy

  logs/
• text

  Copy

  cron/
• text

  Copy

  mcp-tokens/
• text

  Copy

  auth.json
• text

  Copy

  state.db

OpenClaw refuses to execute or trust this state automatically because the formats and trust assumptions can drift between systems. Move what you need by hand after reviewing the archive.

Recommended flow

text
Copy
The plan lists everything that will change, including conflicts, skipped items, and any sensitive items. Plan output redacts nested secret-looking keys.

text
Copy
OpenClaw creates and verifies a backup before applying. If you need API keys imported, add `--include-secrets`.

text
Copy
[Doctor](/gateway/doctor) reapplies any pending config migrations and checks for issues introduced during the import.

text
Copy
Confirm the gateway is healthy and your imported model, memory, and skills are loaded.

Conflict handling

Apply refuses to continue when the plan reports conflicts (a file or config value already exists at the target).

For a fresh OpenClaw install, conflicts are unusual. They typically appear when you re-run the import on a setup that already has user edits.

If a conflict surfaces mid-apply (for example, an unexpected race on a config file), Hermes marks remaining dependent config items as

Secrets

Secrets are never imported by default.

• Run
  text

  Copy

  openclaw migrate apply hermes --yes
  first to import non-secret state.
• If you also want supported
  text

  Copy

  .env
  keys copied across, rerun with
  text

  Copy

  --include-secrets
  .
• For SecretRef-managed credentials, configure the SecretRef source after the import completes.

JSON output for automation

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

With

Troubleshooting

Related

• text

  Copy

  openclaw migrate
  : full CLI reference, plugin contract, and JSON shapes.
• Onboarding: wizard flow and non-interactive flags.
• Migrating: move an OpenClaw install between machines.
• Doctor: post-migration health check.
• Agent workspace: where
  text

  Copy

  SOUL.md
  ,
  text

  Copy

  AGENTS.md
  , and memory files live.