NativePort
Sign in Get a key
← How-to

How to migrate from OpenClaw to Hermes Agent with NativePort

Move an OpenClaw setup's memory, skills and workspace instructions into Hermes Agent with hermes claw migrate, then point the result at NativePort.

Direction matters here, so start with this. This guide moves data from OpenClaw to Hermes Agent, using hermes claw migrate — a Hermes Agent CLI command. OpenClaw separately ships its own openclaw migrate hermes command, which does the opposite: it imports a Hermes Agent install’s data into OpenClaw. If you’re searching around and land on that command instead, you’re looking at the reverse migration. Make sure you’re running the one you mean.

Once your memory, skills and workspace instructions have moved over, pointing Hermes Agent at NativePort gets you the same benefit switching to Hermes was probably about in the first place: one key and one balance across whichever model you pick, instead of a per-provider credential for each one OpenClaw was configured against.

What you’ll need

  • OpenClaw already set up with the state you want to bring over (its default state root is ~/.openclaw).
  • Hermes Agent installed — see using Hermes Agent with NativePort for the current install command and prerequisites.
  • A NativePort API key for the step at the end. Sign up to get a key and $5 in credits.

Preview first, always

hermes claw migrate previews its plan before touching anything, and in a non-interactive session with no --yes flag, it stops after the preview rather than applying it. Run the dry run explicitly anyway, so the intent is clear in whatever script or terminal history you’re working from:

hermes claw migrate --source ~/.openclaw --preset user-data --dry-run

--source points at the OpenClaw state directory to read from; there’s no separate target flag — the destination is always wherever HERMES_HOME resolves to (~/.hermes by default). --preset controls how much configuration comes over: user-data (memory, skills, workspace instructions — the safe default to start with) or full (also configuration shape for providers, messaging, tools and agent behavior). --preset defaults to full if you omit it, so pass user-data explicitly the first time if that’s what you want.

Neither preset migrates secrets on its own. --migrate-secrets is a separate, opt-in flag — the only thing that pulls in the OpenClaw side’s stored provider API keys and messaging tokens. Leaving it off after a --preset full run means provider and channel config land in shape but stay keyless until you supply credentials yourself. This guide doesn’t walk through --migrate-secrets end to end: run it against a real OpenClaw install only once you’ve reviewed the dry-run output for that same call and are comfortable with what it’s about to read out of OpenClaw’s credential store.

Apply it

hermes claw migrate --source ~/.openclaw --preset user-data \
  --workspace-target ~/.hermes/workspace --yes

--workspace-target copies OpenClaw’s AGENTS.md workspace instructions into the directory you name; without it, that file isn’t copied anywhere. --yes skips the confirmation prompt — the preview still prints first either way.

Before writing anything, this also creates a backup zip of the target Hermes home under ~/.hermes/backups/pre-migration-*.zip (the last 5 are kept), and prints the restore command for it (hermes import <archive>) — worth noting even though you shouldn’t need it for a first migration into a clean profile.

A conflict you might hit on the very next run

If you already ran the dry run above against this same HERMES_HOME, be aware that Hermes’s own first-run bootstrap can write a generic SOUL.md into that home the moment any hermes command touches it — including a dry run. If the migration you’re applying also wants to write a SOUL.md (from OpenClaw’s persona file), the apply step then sees that as a real conflict and refuses:

✗ Plan has 1 conflict(s). Refusing to apply

This isn’t a sign anything is broken. Review what’s actually in the target’s SOUL.md before deciding how to proceed — if it’s just Hermes’s own generic bootstrap content, --overwrite is the right call:

hermes claw migrate --source ~/.openclaw --preset user-data \
  --workspace-target ~/.hermes/workspace --overwrite --yes

--overwrite applies to the whole run, so use it once you’ve actually looked at what would be replaced, not as a default first attempt. A genuinely fresh HERMES_HOME that’s never had any hermes command run against it avoids the conflict entirely.

Handling skill-name collisions

If a skill from OpenClaw shares a name with one already present on the Hermes side, --skill-conflict decides what happens: skip (the default — leave the existing one alone), overwrite, or rename (keep both, under distinct names). Pass whichever matches your intent; the default is the safe one if you’re not sure yet.

What actually moves, and what doesn’t

hermes claw migrate isn’t a drop-in parity tool — it’s a scoped translation between two different systems, and it says so in its own output. In broad terms:

Migrates cleanly (with --preset user-data or full): the persona file (SOUL.md), workspace instructions (AGENTS.md, via --workspace-target), memory (MEMORY.md, USER.md, daily notes — parsed, merged and deduplicated rather than dropped in as raw files), and skills from every location OpenClaw stores them in.

Migrates only with --preset full: the shape of provider and messaging configuration, agent behavior knobs (things like max turns, verbose mode, session-reset policy, sandbox settings), MCP server definitions, TTS settings, messaging-platform allowlists, approval mode and command allowlists, and browser automation config. Provider API keys, messaging-platform tokens, a configured search-provider key, and any gateway auth token specifically require --migrate-secrets on top of --preset full — none of that moves with full alone.

Archived for manual review, not migrated at all: OpenClaw-specific files and config that don’t have a Hermes equivalent — its identity/heartbeat/bootstrap files, cron jobs, plugin and hook/webhook config, its skills registry config, UI settings, logging/diagnostics config, multi-agent lists, and per-channel routing config beyond the allowlists above. These land under a timestamped archive directory inside the Hermes home rather than being silently dropped, so nothing disappears — but reconstructing them on the Hermes side, where there’s an equivalent at all, is a manual step this command doesn’t attempt for you.

Clean up the source once you’re confident

Once the migration’s applied and verified, hermes claw cleanup archives the leftover OpenClaw directories rather than deleting them outright:

hermes claw cleanup --source ~/.openclaw --dry-run
hermes claw cleanup --source ~/.openclaw --yes

Run the dry run first here too, for the same reason as the migration itself.

Point the result at NativePort and confirm it carried over

With memory and skills migrated, configure Hermes’s nativeport provider block exactly as in using Hermes Agent with NativePort. If you ran --preset full earlier and brought over OpenClaw’s original provider config shape without --migrate-secrets, this is a natural point to simplify rather than re-supply each of those original per-provider keys one at a time — point the migrated setup at NativePort’s one key and one balance instead.

Then confirm the migration actually took, with a plain one-shot query — no extra flags needed, since migrated memory and skills load by default:

hermes chat -q "Summarize what's in my memory file, and list any skills you have available."

A correct answer references the actual content from your migrated MEMORY.md/USER.md and names the skills that came over, without you having pointed at either explicitly.

Security

  • --migrate-secrets is the only thing that moves credentials; treat any migration command you run without it as config-only, and don’t assume the presence of provider entries after a --preset full run means keys came with them.
  • The pre-migration backup zip under ~/.hermes/backups/ is a plain, unencrypted archive of the target Hermes home. If you do run --migrate-secrets at some point, that backup will contain whatever secrets existed in the target before the migration — store or delete it with the same care as any other credential backup.
  • Keep NATIVEPORT_API_KEY (or whatever you name the key you export for the Hermes setup step) in an environment variable or secret manager, never written into a migrated config file directly.

Troubleshooting

  • ✗ Plan has 1 conflict(s). Refusing to apply, right after a dry run against a brand-new HERMES_HOME. This is the bootstrap-file collision described above, not a sign of a corrupted migration — review the conflicting file, then re-run with --overwrite if it’s safe to replace.
  • A skill didn’t come over. Check --skill-conflict; the default (skip) leaves an existing same-named skill in place rather than replacing it, which can look like a missed migration if you expected an overwrite.
  • Provider entries exist after migration but every call fails with an auth error. Expected if you ran --preset full without --migrate-secrets — those entries are config-only until you supply credentials. Point them at NativePort’s single key instead of trying to reconstruct the originals.
  • Migrated memory or a skill isn’t referenced in a reply. Confirm the migration report (printed at the end of the apply step, and saved alongside the backup) actually lists that item as migrated rather than archived — not everything OpenClaw stores has a direct Hermes equivalent, and archived items need manual reconstruction.
  • You’re following openclaw migrate hermes instructions and nothing here matches. That’s the reverse command — see the note at the top of this guide.

Where to go next