Migrating from Hermes Agent And OpenClaw

If you’re moving from Hermes Agent, EdgeCrab imports the directly compatible state in one step. If you’re moving from OpenClaw, EdgeCrab imports the native subset and archives the rest under ~/.edgecrab/migration/openclaw/ instead of guessing.

Hermes Import

Asset	Source	Destination
Configuration	`~/.hermes/config.yaml`	`~/.edgecrab/config.yaml`
Memories	`~/.hermes/memories/`	`~/.edgecrab/memories/`
Skills	`~/.hermes/skills/`	`~/.edgecrab/skills/`
Environment file	`~/.hermes/.env`	`~/.edgecrab/.env`

Hermes session history in state.db is imported when the source DB exists and the target session IDs do not already exist.

Hermes Dry Run

Always run the dry-run first to see exactly what will happen:

edgecrab migrate --dry-run
edgecrab migrate --source /path/to/.hermes

EdgeCrab Migration (dry-run) — no files will be written
────────────────────────────────────────────────────────────────
Source: ~/.hermes/

  Config:   ~/.hermes/config.yaml  →  ~/.edgecrab/config.yaml
            (provider: openai, model: gpt-4o)
  Memories: 7 files                →  ~/.edgecrab/memories/
  Skills:   12 files               →  ~/.edgecrab/skills/
  Env:      ~/.hermes/.env         →  ~/.edgecrab/.env
              (4 keys detected, will be merged)

No conflicts detected.

Run `edgecrab migrate` (without --dry-run) to execute.
────────────────────────────────────────────────────────────────

Hermes Execute

edgecrab migrate

EdgeCrab Migration
────────────────────────────────────────────────────────────────
✓  Config written         ~/.edgecrab/config.yaml
✓  Memories copied        7/7 files
✓  Skills copied          12/12 files
✓  Env merged             ~/.edgecrab/.env
────────────────────────────────────────────────────────────────
Migration complete. Run `edgecrab doctor` to verify.

OpenClaw Import

OpenClaw uses a different data model. EdgeCrab therefore splits the import into:

direct import for the parts that map cleanly into EdgeCrab
archival for the parts that do not

Run it with:

edgecrab claw migrate --dry-run
edgecrab claw migrate
edgecrab claw migrate --preset user-data
edgecrab claw migrate --preset full
edgecrab claw migrate --migrate-secrets
edgecrab claw migrate --workspace-target /absolute/workspace
edgecrab claw migrate --skill-conflict rename

OpenClaw items imported directly:

Asset	Source	Destination
Persona	`workspace/SOUL.md`	`~/.edgecrab/SOUL.md`
Memory	`workspace/MEMORY.md`, `workspace/USER.md`, `workspace/memory/*.md`	`~/.edgecrab/memories/`
Skills	`workspace/skills/`, shared skill directories	`~/.edgecrab/skills/openclaw-imports/`
Command allowlist	`exec-approvals.json`	`~/.edgecrab/command_allowlist.json`
Messaging/env	OpenClaw config and credentials files	`~/.edgecrab/.env`
Selected config	model, tts, MCP servers, terminal timeout, timezone, reasoning effort	`~/.edgecrab/config.yaml`

OpenClaw items archived instead of force-mapped:

gateway/session/browser/approval/skills-registry/ui/logging config
supplemental workspace docs such as IDENTITY.md, TOOLS.md, HEARTBEAT.md, BOOTSTRAP.md

Archive output lands under ~/.edgecrab/migration/openclaw/<timestamp>/.

Verify

edgecrab doctor

If everything is configured correctly, all checks should pass.

Handling Conflicts

If ~/.edgecrab/ already exists (e.g., you ran edgecrab setup first), the migration will skip files that already exist:

  Skills:   12 files               →  ~/.edgecrab/skills/
              ⚠ 3 files already exist — skipping (use --overwrite to replace)

Hermes import is intentionally conservative. It does not overwrite existing EdgeCrab files. If you want a clean re-import, move or remove the specific target files first, then rerun:

mv ~/.edgecrab/config.yaml ~/.edgecrab/config.yaml.backup
edgecrab migrate

For OpenClaw conflicts, use:

edgecrab claw migrate --overwrite
edgecrab claw migrate --skill-conflict rename

Or inspect the dry-run manually:

edgecrab migrate --dry-run > /tmp/migration-plan.txt
edgecrab claw migrate --dry-run > /tmp/openclaw-plan.txt
# Review and selectively copy files

Configuration Mapping

EdgeCrab uses the same provider names as Hermes. Your existing config.yaml provider settings will work directly. A few key differences:

Hermes config key	EdgeCrab config key
`llm.provider`	`provider`
`llm.model`	`model`
`tools.allowed_paths`	`tools.file.allowed_roots`
`memory.path`	`memory.dir`
`skills.path`	`skills.dir`

Skills Compatibility

EdgeCrab skills use the same Markdown format as Hermes Agent skills. All skills migrated from Hermes will work as-is.

The only difference: EdgeCrab’s skills system adds a capabilities frontmatter field for faster lookup. EdgeCrab will automatically upgrade skills to the new format the first time they are used.

Keeping Both Agents

You can run Hermes Agent and EdgeCrab side-by-side without conflict — they use different state directories (~/.hermes vs ~/.edgecrab). If you update memories in one, run the migration again to sync to the other.

Reverting

If you want to undo the migration, simply delete ~/.edgecrab/ (back it up first):

cp -r ~/.edgecrab ~/.edgecrab.pre-migration
rm -rf ~/.edgecrab

Your Hermes Agent installation is never modified by edgecrab migrate.

Pro Tips

Always run --dry-run first. It shows exactly what will be copied and flags any conflicts without making changes. Review it before committing.

Migrate incrementally. If you make improvements to your Hermes memories or skills after migration, re-run edgecrab migrate — it skips files that already exist (unless you use --overwrite).

After migration, use EdgeCrab for a week before removing Hermes. This ensures you’re comfortable before losing the fallback. Both can coexist indefinitely.

Frequently Asked Questions

Q: Why does OpenClaw migration archive some files instead of importing them?

Because EdgeCrab does not share OpenClaw’s config model. Archiving is safer than pretending a field maps cleanly when it does not.

Q: Some of my Hermes config keys aren’t recognized. What do I do?

EdgeCrab has a superset of Hermes config but some keys changed names (see the mapping table above). Run edgecrab doctor after migration — it highlights unrecognized config keys. Then update them using edgecrab config set <new-key> <value>.

Q: I use Hermes profiles. Are those migrated?

Profiles from ~/.hermes/profiles/ are migrated to ~/.edgecrab/profiles/. Each profile’s config, memories, and skills are migrated independently.

Q: Will edgecrab migrate break my Hermes installation?

Never. edgecrab migrate is read-only on the Hermes side — it only reads from ~/.hermes/ and writes to ~/.edgecrab/. Your Hermes setup is completely untouched.

Q: I want to keep Hermes as a fallback. Is that safe?

Yes. Both agents coexist. Just be aware that changes to ~/.edgecrab/memories/ are not automatically synced back to ~/.hermes/memories/. Run edgecrab migrate --overwrite periodically to freshen your EdgeCrab data from Hermes, or manage them independently.