Migrate from OpenClaw to Hermes Agent: Manual Guide

You Made The Call. Now Comes The Weekend.

You already decided. Maybe you read the Hermes Agent vs OpenClaw comparison and concluded that the focused agent runtime fits the way you actually work. Maybe a teammate did. Either way, the decision is behind you. What sits in front of you is a real piece of operational work: getting a live OpenClaw setup, with months of accumulated memory and tuned skills, onto a clean Hermes Agent install without losing anything that matters.

Hermes ships an official migration command. The package hermes-migrate was released on March 10, 2026 and the hermes claw migrate flow is documented to import settings, memories, skills, channels and API keys. That handles the happy path. What it does not handle is the surrounding work: provisioning a host, translating provider config from OpenClaw's old shape to Hermes's snake_case schema, locking down secrets at rest, re-pairing your Telegram bot, and verifying end to end before you tell your team the new bot is live.

This guide walks the whole thing manually so you know exactly what you are signing up for. At the end, there is a 1-minute alternative.

Step 1: Freeze And Export Your OpenClaw State

Do not start by installing Hermes. Start by making the OpenClaw side stand still.

OpenClaw's own migration documentation tells you to stop the gateway before copying state, because conversation history and channel sessions write under your feet otherwise. The default state directory is ~/.openclaw/, which holds openclaw.json, gateway settings, auth-profiles.json, provider credentials, sessions, channel state for WhatsApp and Telegram, and your workspace files including MEMORY.md, USER.md, skills and prompts.

openclaw gateway stop
cd ~
tar -czf openclaw-state-$(date +%Y%m%d).tgz .openclaw
sha256sum openclaw-state-*.tgz

If you set a custom path with OPENCLAW_STATE_DIR, or if you run profiles such as ~/.openclaw-work or ~/.openclaw-personal, archive each one separately. The migration is only as complete as the directories you remember to capture, and the failure mode of forgetting a profile is silent: Hermes will boot fine and your weekend personality will simply be gone.

Copy the archives to the new host before you change anything else. If you skip this and the new host install fails, you want a clean rollback path that does not depend on the old machine still being healthy.

Step 2: Provision A Host And Install Hermes

You now need somewhere for Hermes to live. The two realistic options are a small VPS or a local Docker host.

For a VPS, a 2 vCPU / 4 GB box is a comfortable floor. You will spend the next hour on the parts no one writes blog posts about: choosing a region close to your messaging users, hardening SSH, configuring a firewall that allows only the ports you actually need, setting up unattended security upgrades, and deciding whether the agent runs as root (it should not) or as a dedicated service user with a locked-down home directory.

For local Docker, the work is different but not shorter. You write a Compose file, decide where state volumes live, decide how the container restarts on host reboot, and figure out how the container reaches the outside world without exposing more than it should.

Once the host exists, install Hermes:

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
hermes setup

hermes setup will look for ~/.openclaw/ and offer to migrate. If you uploaded your tarball to a different path, extract it first so the wizard finds it.

A terminal extracting an OpenClaw state archive on a fresh server

Step 3: Translate The Provider Config

This is the step where most manual migrations silently break.

OpenClaw and Hermes both let you point the agent at OpenAI, Anthropic, OpenRouter, vLLM, Ollama or a custom OpenAI-compatible endpoint. The fields look similar. They are not the same shape.

Hermes recognises snake_case only in provider config. A hand-edited apiKey or baseUrl will be silently dropped. Use api_key and base_url. When base_url is set, Hermes ignores the provider name and calls that endpoint directly using api_key or the OPENAI_API_KEY environment variable for authentication.

The minimum manual mapping looks like this for each provider you carry over:

| OpenClaw field | Hermes field | Notes | |---|---|---| | provider | provider | Match the lowercase slug Hermes expects (openai, anthropic, openrouter, ollama, vllm, custom) | | model | model | Same string, no translation | | apiKey | api_key | snake_case is mandatory, camelCase is dropped | | baseUrl | base_url | snake_case is mandatory, only set if you really need a custom endpoint | | apiMode | api_mode | Confirm Hermes still supports the value you used |

Repeat this for every provider you have configured. If you are running fallback chains (primary plus a cheap backup), do them one at a time and test each before moving on.

Step 4: Port Persona, Skills And Memory

OpenClaw stores persona under workspace/SOUL.md and IDENTITY.md, with optional per-personality folders under personalities/, plus USER.md, MEMORY.md and daily memory files. Skills live in your workspace skills directory.

A clean manual port is a per-file decision, not a directory copy. Open each persona file and confirm:

The voice and constraints still match how you want the new agent to behave.
References to OpenClaw-specific tools (Control UI, plugin names, gateway behaviors) are removed or rephrased.
Skill names do not collide with Hermes's built-in skills, otherwise the imported version may shadow or be shadowed without warning.

Then move the files into Hermes's expected layout:

~/.hermes/SOUL.md for persona
~/.hermes/memories/ for MEMORY.md, USER.md and daily files
~/.hermes/skills/openclaw-imports/ for skills, with conflict resolution done by hand

Memory files are where most teams underestimate the work. After a year of OpenClaw use, MEMORY.md can have hundreds of entries that mix obsolete project context with still-relevant facts. The migration is the right moment to dedupe and prune, not to copy blindly.

Step 5: Secure Your Secrets

This step has no shortcut. Hermes stores credentials in ~/.hermes/, with sensitive auth tokens placed at paths like ~/.hermes/auth/google_oauth.json using chmod 0600, atomic writes and cross-process file locks. That is the floor, not the ceiling.

A manual migration that takes secrets seriously needs:

A clear inventory of every API key you are bringing over, with rotation done at migration time so any keys leaked during your OpenClaw period are invalidated.
File permissions on ~/.hermes/.env set to 0600, owned by the service user, never readable by other accounts on the host.
Encryption at rest for the volume holding ~/.hermes/, especially if the host is a shared VPS.
Off-host backups that are themselves encrypted, with a tested restore procedure, because a backup you have never restored is not really a backup.
Documented allowlists of who and what can read these files, so the next person on call does not have to guess.

If you skip the rotation step, you have not actually migrated your security posture, you have just relocated it.

Step 6: Reattach Telegram And Test End To End

Telegram is the most common Hermes channel and the easiest one to break in transit. You need the bot token, the allowed-users list, and any channel-specific settings such as group IDs or admin-only flags. Hermes reads these from environment variables in ~/.hermes/.env. After importing, the gateway must be restarted before the bot starts answering.

hermes status
hermes gateway restart

If you have not deployed Hermes on Telegram before, the Hermes Agent on Telegram setup guide covers the bot creation and webhook details. Once the gateway is back up, run an end-to-end test from the actual Telegram client, not from hermes status. Send a message that exercises memory recall, a message that exercises a migrated skill, and a message that exercises your provider chain. If any of the three fails, fix it before you tell anyone the migration is done.

Step 7: Troubleshooting The Usual Suspects

Realistically, you will hit at least one of these. Plan for it.

Port conflicts: the OpenClaw gateway and Hermes gateway both want a port. If you co-located them during testing, stop OpenClaw first.
Provider auth errors: almost always a snake_case mistake or a stale key. Re-check api_key and base_url, then hermes status.
Missing or incompatible skills: imported skills sometimes reference OpenClaw-only tools. Read the failing skill and either rewrite it or remove it.
Memory encoding: if your MEMORY.md came from a Windows OpenClaw install with CRLF line endings, run it through dos2unix before copying.
Persona drift: the agent feels different even though the persona file is identical. Check that you are not loading two persona files at once and that no Hermes default persona is overriding yours.

If something works in hermes status but not in Telegram, the issue is almost always gateway, not agent.

Or Do All Of This In Under 1 Minute With Hermify

Read back through the last seven sections. That is somewhere between a focused weekend and an unfocused week of evenings, depending on how clean your OpenClaw setup was when you started.

Hermify ships a one-click OpenClaw migration wizard inside the dashboard that does the same work without the weekend. You upload your OpenClaw export, the wizard previews the migration with counts for persona, skills, memories, secrets, providers and Telegram before applying anything, and the apply step writes everything into a managed Hermes install with secrets encrypted at rest. There is no host to provision, no snake_case translation to remember, no backup script to write.

The article you just read is what the wizard runs through under the hood. If the manual path is the experience you want, the steps above are accurate and complete. If the outcome is what you want, the wizard gets you there in about a minute.

Get started with Hermify and migrate from OpenClaw before the weekend you were planning to spend on it.