OpenClaw to Hermes Migration: Import Memories and Skills

Moving from OpenClaw to Hermes Agent does not have to mean rebuilding your persona, memory, and skills by hand. The OpenClaw Migration skill imports an existing OpenClaw setup into Hermes, converting what maps cleanly and archiving the rest for review. It is aimed at anyone who has been running OpenClaw and wants to carry their configuration across without losing track of what changed.

What it does

The skill wraps a helper script, scripts/openclaw_to_hermes.py, that reads an OpenClaw installation and writes the compatible parts into a Hermes home directory. The pieces it handles are:

SOUL.md is imported into the Hermes home directory as SOUL.md.
OpenClaw MEMORY.md and USER.md are transformed into Hermes memory entries.
OpenClaw command approval patterns are merged into the Hermes command_allowlist.
Hermes-compatible messaging settings such as TELEGRAM_ALLOWED_USERS are migrated, and OpenClaw workspace settings are mapped to Hermes working-directory configuration.
OpenClaw skills are copied into ~/.hermes/skills/openclaw-imports/.
Optionally, the OpenClaw workspace instructions file is copied into a chosen Hermes workspace.
Compatible workspace assets such as workspace/tts/ are mirrored into ~/.hermes/tts/.
Non-secret docs that have no direct Hermes destination are archived.
A structured report is produced listing migrated items, conflicts, skipped items, and reasons.

The result is not a blind copy. The script distinguishes between what it can convert, what it must skip, and what it archives, and it records all three in the report.

Before you start

This is an optional skill, installed on demand rather than shipped by default. Its path is optional-skills/migration/openclaw-migration, version 1.0.0, authored by Hermes Agent (Nous Research) under the MIT license. It runs on linux, macos, and windows.

The helper script depends on ruamel.yaml. When you run it with Hermes' Python environment, that dependency is already present. If you are using a standalone Python environment, install ruamel.yaml==0.18.17 first.

You also need an existing OpenClaw installation to migrate from. The script expects the primary workspace at ~/.openclaw/workspace/; workspace.default/ is only a fallback when the primary files are missing.

Path resolution

The helper script lives inside the skill directory at scripts/openclaw_to_hermes.py. When the skill is installed from the Skills Hub, the normal location is:

~/.hermes/skills/migration/openclaw-migration/scripts/openclaw_to_hermes.py

Do not guess a shorter path like ~/.hermes/skills/openclaw-migration/.... Before running the helper:

Prefer the installed path under ~/.hermes/skills/migration/openclaw-migration/.
If that path fails, inspect the installed skill directory and resolve the script relative to the installed SKILL.md.
Only use find as a fallback if the installed location is missing or the skill was moved manually.
When calling the terminal tool, do not pass workdir: "~". Use an absolute directory such as the user's home directory, or omit workdir entirely.

CLI command

For a quick, non-interactive migration, Hermes ships a built-in CLI command that runs the same migration script described below:

hermes claw migrate              # Full interactive migration
hermes claw migrate --dry-run    # Preview what would be migrated
hermes claw migrate --preset user-data   # Migrate without secrets
hermes claw migrate --overwrite  # Overwrite existing conflicts
hermes claw migrate --source /custom/path/.openclaw  # Custom source

Use the skill itself, through the agent, when you want an interactive, guided migration with dry-run previews and per-item conflict resolution. The CLI is the faster route when you already know what you want.

First-time setup is handled for you: the hermes setup wizard automatically detects ~/.openclaw and offers migration before configuration begins.

Default workflow

The skill follows a fixed sequence:

Inspect first with a dry run.
Present a simple summary of what can be migrated, what cannot be migrated, and what would be archived.
If the clarify tool is available, use it for user decisions instead of asking for a free-form prose reply.
If the dry run finds imported skill directory conflicts, ask how those should be handled before executing.
Ask the user to choose between the two supported migration modes before executing.
Ask for a target workspace path only if the user wants the workspace instructions file brought over.
Execute the migration with the matching preset and flags.
Summarize the results, especially what was migrated, what was archived for manual review, and what was skipped and why.

User interaction protocol

Hermes CLI supports the clarify tool for interactive prompts, but it is limited to one choice at a time, up to 4 predefined choices, and an automatic Other free-text option. It does not support true multi-select checkboxes in a single prompt.

For every clarify call:

always include a non-empty question
include choices only for real selectable prompts
keep choices to 2-4 plain string options
never emit placeholder or truncated options such as ...
never pad or stylize choices with extra whitespace
never include fake form fields in the question such as enter directory here, blank lines to fill in, or underscores like _____
for open-ended path questions, ask only the plain sentence; the user types in the normal CLI prompt below the panel

If a clarify call returns an error, inspect the error text, correct the payload, and retry once with a valid questions array and clean choices.

When clarify is available and the dry run reveals any required user decision, your next action must be a clarify tool call. Do not end the turn with a normal assistant message such as "Let me present the choices", "What would you like to do?", or "Here are the options". If a user decision is required, collect it via clarify before producing more prose. If multiple unresolved decisions remain, do not insert an explanatory assistant message between them. After one clarify response is received, your next action should usually be the next required clarify call.

Treat workspace-agents as an unresolved decision whenever the dry run reports kind="workspace-agents", status="skipped", and a reason containing No workspace target was provided. In that case, you must ask about workspace instructions before execution. Do not silently treat that as a decision to skip.

Because of that limitation, use this simplified decision flow:

For SOUL.md conflicts, use clarify with choices such as keep existing, overwrite with backup, or review first.
If the dry run shows one or more kind="skill" items with status="conflict", use clarify with choices such as keep existing skills, overwrite conflicting skills with backup, or import conflicting skills under renamed folders.
For workspace instructions, use clarify with choices such as skip workspace instructions, copy to a workspace path, or decide later.
If the user chooses to copy workspace instructions, ask a follow-up open-ended clarify question requesting an absolute path.
If the user chooses skip workspace instructions or decide later, proceed without --workspace-target.
For migration mode, use clarify with these 3 choices: user-data only, full compatible migration, or cancel.
user-data only means: migrate user data and compatible config, but do not import allowlisted secrets.
full compatible migration means: migrate the same compatible user data plus the allowlisted secrets when present.
If clarify is not available, ask the same question in normal text, but still constrain the answer to user-data only, full compatible migration, or cancel.

Execution gate:

Do not execute while a workspace-agents skip caused by No workspace target was provided remains unresolved.
The only valid ways to resolve it are: the user explicitly chooses skip workspace instructions, the user explicitly chooses decide later, or the user provides a workspace path after choosing copy to a workspace path.
Absence of a workspace target in the dry run is not itself permission to execute.
Do not execute while any required clarify decision remains unresolved.

Use these exact clarify payload shapes as the default pattern:

{"question":"Your existing SOUL.md conflicts with the imported one. What should I do?","choices":["keep existing","overwrite with backup","review first"]}
{"question":"One or more imported OpenClaw skills already exist in Hermes. How should I handle those skill conflicts?","choices":["keep existing skills","overwrite conflicting skills with backup","import conflicting skills under renamed folders"]}
{"question":"Choose migration mode: migrate only user data, or run the full compatible migration including allowlisted secrets?","choices":["user-data only","full compatible migration","cancel"]}
{"question":"Do you want to copy the OpenClaw workspace instructions file into a Hermes workspace?","choices":["skip workspace instructions","copy to a workspace path","decide later"]}
{"question":"Please provide an absolute path where the workspace instructions should be copied."}

Decision-to-command mapping

Map user decisions to command flags exactly:

If the user chooses keep existing for SOUL.md, do not add --overwrite.
If the user chooses overwrite with backup, add --overwrite.
If the user chooses review first, stop before execution and review the relevant files.
If the user chooses keep existing skills, add --skill-conflict skip.
If the user chooses overwrite conflicting skills with backup, add --skill-conflict overwrite.
If the user chooses import conflicting skills under renamed folders, add --skill-conflict rename.
If the user chooses user-data only, execute with --preset user-data and do not add --migrate-secrets.
If the user chooses full compatible migration, execute with --preset full --migrate-secrets.
Only add --workspace-target if the user explicitly provided an absolute workspace path.
If the user chooses skip workspace instructions or decide later, do not add --workspace-target.

Before executing, restate the exact command plan in plain language and make sure it matches the user's choices.

Post-run reporting rules

After execution, treat the script's JSON output as the source of truth.

Base all counts on report.summary.
Only list an item under "Successfully Migrated" if its status is exactly migrated.
Do not claim a conflict was resolved unless the report shows that item as migrated.
Do not say SOUL.md was overwritten unless the report item for kind="soul" has status="migrated".
If report.summary.conflict > 0, include a conflict section instead of silently implying success.
If counts and listed items disagree, fix the list to match the report before responding.
Include the output_dir path from the report when available so the user can inspect report.json, summary.md, backups, and archived files.
For memory or user-profile overflow, do not say the entries were archived unless the report explicitly shows an archive path. If details.overflow_file exists, say the full overflow list was exported there.
If a skill was imported under a renamed folder, report the final destination and mention details.renamed_from.
If report.skill_conflict_mode is present, use it as the source of truth for the selected imported-skill conflict policy.
If an item has status="skipped", do not describe it as overwritten, backed up, migrated, or resolved.
If kind="soul" has status="skipped" with reason Target already matches source, say it was left unchanged and do not mention a backup.
If a renamed imported skill has an empty details.backup, do not imply the existing Hermes skill was renamed or backed up. Say only that the imported copy was placed in the new destination and reference details.renamed_from as the pre-existing folder that remained in place.

Migration presets

Prefer these two presets in normal use: user-data and full.

user-data includes soul, workspace-agents, memory, user-profile, messaging-settings, command-allowlist, skills, tts-assets, and archive.

full includes everything in user-data plus secret-settings.

The helper script still supports category-level --include / --exclude, but treat that as an advanced fallback rather than the default UX.

Commands

Run the helper with Hermes' Python environment, which includes ruamel.yaml. For a standalone Python environment, install ruamel.yaml==0.18.17 first.

Dry run with full discovery:

python ~/.hermes/skills/migration/openclaw-migration/scripts/openclaw_to_hermes.py

When using the terminal tool, prefer an absolute invocation pattern such as:

{"command":"python /home/USER/.hermes/skills/migration/openclaw-migration/scripts/openclaw_to_hermes.py","workdir":"/home/USER"}

Dry run with the user-data preset:

python ~/.hermes/skills/migration/openclaw-migration/scripts/openclaw_to_hermes.py --preset user-data

Execute a user-data migration:

python ~/.hermes/skills/migration/openclaw-migration/scripts/openclaw_to_hermes.py --execute --preset user-data --skill-conflict skip

Execute a full compatible migration:

python ~/.hermes/skills/migration/openclaw-migration/scripts/openclaw_to_hermes.py --execute --preset full --migrate-secrets --skill-conflict skip

Execute with workspace instructions included:

python ~/.hermes/skills/migration/openclaw-migration/scripts/openclaw_to_hermes.py --execute --preset user-data --skill-conflict rename --workspace-target "/absolute/workspace/path"

Do not use $PWD or the home directory as the workspace target by default. Ask for an explicit workspace path first.

Important rules

Run a dry run before writing unless the user explicitly says to proceed immediately.
Do not migrate secrets by default. Tokens, auth blobs, device credentials, and raw gateway config should stay out of Hermes unless the user explicitly asks for secret migration.
Do not silently overwrite non-empty Hermes targets unless the user explicitly wants that. The helper script will preserve backups when overwriting is enabled.
Always give the user the skipped-items report. That report is part of the migration, not an optional extra.
Prefer the primary OpenClaw workspace (~/.openclaw/workspace/) over workspace.default/. Only use the default workspace as fallback when the primary files are missing.
Even in secret-migration mode, only migrate secrets with a clean Hermes destination. Unsupported auth blobs must still be reported as skipped.
If the dry run shows a large asset copy, a conflicting SOUL.md, or overflowed memory entries, call those out separately before execution.
Default to user-data only if the user is unsure.
Only include workspace-agents when the user has explicitly provided a destination workspace path.
Treat category-level --include / --exclude as an advanced escape hatch, not the normal flow.
Do not end the dry-run summary with a vague "What would you like to do?" if clarify is available. Use structured follow-up prompts instead.
Do not use an open-ended clarify prompt when a real choice prompt would work. Prefer selectable choices first, then free text only for absolute paths or file review requests.
After a dry run, never stop after summarizing if there is still an unresolved decision. Use clarify immediately for the highest-priority blocking decision.
Priority order for follow-up questions: SOUL.md conflict, imported skill conflicts, migration mode, workspace instructions destination.
Do not promise to present choices later in the same message. Present them by actually calling clarify.
After the migration-mode answer, explicitly check whether workspace-agents is still unresolved. If it is, your next action must be the workspace-instructions clarify call.
After any clarify answer, if another required decision remains, do not narrate what was just decided. Ask the next required question immediately.

When not to use it

If you only need a quick, non-interactive transfer, the built-in hermes claw migrate CLI command is the better fit. The skill exists for cases where you want the agent to walk through dry-run previews and resolve conflicts item by item. If you are unsure which mode to pick, default to user-data only; it leaves secrets out of Hermes and keeps the migration conservative.

Limits and gotchas

Secrets are not migrated by default. Even with --migrate-secrets, only a small allowlisted set of Hermes-compatible secrets is imported, currently TELEGRAM_BOT_TOKEN. Unsupported auth blobs are reported as skipped.
The clarify tool cannot do multi-select. Each decision is a separate prompt, so the skill asks them in priority order.
A workspace-agents skip with reason No workspace target was provided is not permission to execute. You must resolve it explicitly.
Do not use $PWD or the home directory as a workspace target by default. Ask for an explicit absolute path.
The helper script preserves backups when overwriting is enabled, but only if you enable overwriting. Silent overwrites of non-empty Hermes targets are not allowed.
The skipped-items report is mandatory. It is part of the migration, not an optional extra.
If the dry run shows a large asset copy, a conflicting SOUL.md, or overflowed memory entries, call those out separately before execution.

Expected result

After a successful run, the user should have Hermes persona state imported, Hermes memory files populated with converted OpenClaw knowledge, OpenClaw skills available under ~/.hermes/skills/openclaw-imports/, and a migration report showing any conflicts, omissions, or unsupported data.

What pairs with it

The source lists hermes-agent as a related skill. That is the natural companion: once the migration is done, the Hermes Agent skill is where you continue working with the imported persona, memory, and skills inside Hermes.