How to migrate from OpenClaw to Hermes Agent: step-by-step

Before you start

Until October 2026 this guide described a manual migration that does not match Hermes Agent: a Docker-only install, per-tool YAML files with sandbox blocks, a hermes vault command, Telegram as a plugin. None of that is in Hermes Agent. This version follows the project's own migration guide and security docs, read on 18 October 2026 (Hermes Agent v0.22.2). We have not run the migration ourselves: the steps are the documented ones, not a test report.

You need:

• An OpenClaw install whose state lives in ~/.openclaw (legacy ~/.clawdbot and ~/.moltbot directories are detected too).
• Shell access to the machine, as the user that runs OpenClaw.
• Linux, macOS, WSL2 or native Windows for Hermes Agent.

Step 1: Rotate what may have leaked

If your OpenClaw Control UI ever ran a version older than 2026.1.29, a crafted link could make it send its gateway token to an attacker (CVE-2026-25253 on NVD). Treat every key the agent could read as exposed: create new keys at each provider now, and put them in Hermes at step 6. The security crisis post explains why.

Step 2: Install Hermes Agent

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
source ~/.bashrc
hermes doctor

On native Windows the PowerShell one-liner is iex (irm https://hermes-agent.nousresearch.com/install.ps1). The script also installs a browser tool with its own Chromium; pass --skip-browser to leave it out (README, install script options).

Step 3: Preview the migration

hermes claw migrate --dry-run

It reads ~/.openclaw by default (pass --source for another path) and lists what would be imported, skipped and archived, then stops. By default it refuses to apply a plan with conflicts: --overwrite replaces existing Hermes files, and --skill-conflict picks skip, overwrite or rename for skills.

Step 4: Migrate

hermes claw migrate --preset full --migrate-secrets

It shows the preview again and asks you to confirm (--yes skips that). Before applying, it writes a restore point under ~/.hermes/backups/pre-migration-*.zip, which hermes import restores. What comes across:

--preset user-data leaves infrastructure settings out. Neither preset copies secrets unless you pass --migrate-secrets, and even then only for a fixed list: OpenRouter, OpenAI, Anthropic, DeepSeek, Gemini, Z.AI, MiniMax and ElevenLabs keys, the Telegram bot token and a voice-tools key. AGENTS.md comes across only if you pass --workspace-target.

Step 5: Decide where commands run

The import does not decide this for you. If OpenClaw ran tools in a Docker sandbox (agents.defaults.sandbox.backend set to docker), the migration sets Hermes's terminal.backend to docker and copies the image. If it did not, Hermes uses its default local backend: commands run on the host, and the ones that match its list of dangerous patterns need approval (terminal backends). OpenClaw's own sandbox is off by default (sandboxing docs), so most migrated installs land on local.

hermes config get terminal.backend
hermes config set terminal.backend docker   # run the agent's commands in a container

The terminal backend confines the shell and file tools only. Hermes's security policy treats the approval gate as a heuristic, not a boundary, and asks for the whole agent inside its Docker image, or NVIDIA OpenShell, once it reads input you don't control: the open web, email, group chats.

Step 6: Review what was archived, then verify

Settings with no direct Hermes equivalent are saved under ~/.hermes/migration/openclaw/<timestamp>/archive/ for you to redo by hand: cron jobs (recreate them with hermes cron create), plugins, hooks and webhooks, IDENTITY.md (merge it into SOUL.md), HEARTBEAT.md (use cron jobs), multi-agent lists (use Hermes profiles), channel bindings and the more complex channel settings. Idle and daily session resets are not imported: Hermes conversations last until /new or /reset.

Then check that everything answers:

hermes status                             # provider authentication
systemctl --user restart hermes-gateway   # if you migrated platform tokens
hermes whatsapp                           # WhatsApp needs a new QR pairing

Imported skills and memory load in a new session, not the current one. Put the keys you rotated at step 1 in ~/.hermes/.env. The security docs ask for proper file permissions on it; chmod 600 ~/.hermes/.env leaves it readable by you alone.

Step 7: Retire OpenClaw

When Hermes works, stop and remove OpenClaw's gateway service, then let Hermes rename the leftovers so the two never read the same state:

openclaw gateway stop
openclaw gateway uninstall
hermes claw cleanup   # renames leftover OpenClaw directories to .pre-migration/

To remove OpenClaw completely instead, openclaw uninstall lets you choose the service, the state, the workspace and the app (uninstall docs). Keep the pre-migration restore point until you are sure.

Troubleshooting

• "OpenClaw directory not found". The migration checks ~/.openclaw, then ~/.clawdbot, then ~/.moltbot. Pass --source with your path.
• "No provider API keys found". Keys can sit inline in openclaw.json, in ~/.openclaw/.env, in the env block of openclaw.json or in agents/main/agent/auth-profiles.json; the migration checks all four. Secrets stored as a file or exec SecretRef cannot be resolved: add them with hermes config set.
• Skills missing. They land in ~/.hermes/skills/openclaw-imports/ and load in a new session; /skills lists what is loaded.

What you gain, what you lose

You gain: an import command instead of a hand port, command approvals on from the first run, a chat gateway that refuses everyone until you allowlist or pair them, a choice of seven terminal backends, and a security policy that says plainly where its boundary is.

You lose, until you redo them: whatever lands in the archive (cron jobs, plugins, hooks, multi-agent setups), the session reset timers, and your WhatsApp pairing. You do not gain a sandbox by default: neither OpenClaw nor Hermes Agent turns one on for you. Until October 2026 this section said Hermes brings "a sandbox that exists, a credential vault that exists, an audit log that exists"; both projects have a sandbox, both leave it off, and Hermes documents no credential vault.

What's next

• OpenClaw vs Hermes Agent, side by side
• The OpenClaw alternatives, if Hermes is not the right target
• The Hermes Agent page, with its CVEs from NVD

Subscribe to the newsletter to get the next guides.

Sources

Read on 18 October 2026: Hermes Agent migration guide, README (v0.22.2), terminal backends, security docs, SECURITY.md; OpenClaw sandboxing and uninstall docs; CVE-2026-25253 on NVD.