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

Before you start

This guide assumes you have:

• An OpenClaw install on Linux or macOS.
• Root or admin access to the machine.
• Docker installed (docker --version should work).
• 4 GB+ free RAM and 5 GB+ disk.

It takes about 45 minutes if nothing weird happens, twice that if your OpenClaw install has been running for more than three months.

Step 1 — Snapshot OpenClaw

Don't migrate yet. Dump everything to disk first so you can roll back.

# OpenClaw default location on Linux
OPENCLAW_HOME="${HOME}/.openclaw"

mkdir -p ~/openclaw-snapshot-$(date +%Y%m%d)
cd ~/openclaw-snapshot-$(date +%Y%m%d)

cp -r "${OPENCLAW_HOME}/config" ./config
cp -r "${OPENCLAW_HOME}/tools" ./tools
cp -r "${OPENCLAW_HOME}/memory" ./memory
cp "${OPENCLAW_HOME}/credentials.json" ./credentials.json
cp "${OPENCLAW_HOME}/agent.log" ./agent.log

If your OpenClaw install was on the public internet at any point, rotate every credential in `credentials.json` before doing anything else. The [security crisis post](/guides/openclaw-security-crisis-2026) explains why.

Step 2 — Install Hermes Agent

Hermes Agent ships as a single Docker container. Install with the official script:

curl -sSL https://hermes.nousresearch.com/install | bash

This pulls nousresearch/hermes-agent:latest, creates ~/.hermes, and adds a hermes CLI to /usr/local/bin.

Verify the install:

hermes version
# hermes-agent 2026.4.3
hermes status
# agent: not running

Step 3 — Port your tool definitions

This is the bulk of the work. OpenClaw stores tools as JSON files; Hermes expects YAML with explicit sandbox declarations.

OpenClaw tool format (~/.openclaw/tools/grep.json):

{
  "name": "grep",
  "description": "Search for a pattern in files.",
  "command": "grep -rn",
  "args": ["pattern", "path"]
}

Equivalent Hermes tool (~/.hermes/tools/grep.yaml):

name: grep
description: Search for a pattern in files.
command: grep -rn
args:
  - pattern
  - path
sandbox:
  network: deny
  filesystem:
    read: ["/workspace"]
    write: []
  resources:
    cpu_quota: 50
    memory_mb: 256

The pattern: every Hermes tool needs an explicit sandbox block. There's no implicit "trust the parent process" — if you don't declare it, the tool can't do it.

A small Python script automates the boring 80%:

import json, yaml
from pathlib import Path

src = Path.home() / ".openclaw/tools"
dst = Path.home() / ".hermes/tools"
dst.mkdir(parents=True, exist_ok=True)

DEFAULT_SANDBOX = {
    "network": "deny",
    "filesystem": {"read": ["/workspace"], "write": []},
    "resources": {"cpu_quota": 50, "memory_mb": 256},
}

for tool_file in src.glob("*.json"):
    tool = json.loads(tool_file.read_text())
    tool["sandbox"] = DEFAULT_SANDBOX
    out = dst / f"{tool['name']}.yaml"
    out.write_text(yaml.safe_dump(tool, sort_keys=False))
    print(f"migrated {tool['name']}")

Review every output file. Any tool that needs network access, write permissions, or more resources needs its sandbox block edited by hand. Tools that sounded fine in OpenClaw because there was no sandbox often turn out to need surprising privileges. That's the point.

Step 4 — Migrate credentials

Hermes uses a separate encrypted credential vault. Create the vault first:

hermes vault init
# Vault initialized at ~/.hermes/vault.enc
# Master key written to ~/.hermes/vault.key (mode 0600)

Then port credentials one at a time. Don't bulk-import the OpenClaw JSON file — half of those keys are probably stale or rotated by now.

hermes vault add anthropic_api_key
# Paste your Anthropic key, press Ctrl-D
hermes vault add openai_api_key
hermes vault add openrouter_api_key

Tools reference credentials by name in their YAML:

name: chat-anthropic
command: anthropic-cli
env:
  ANTHROPIC_API_KEY: ${vault.anthropic_api_key}

This is one of the genuine improvements over OpenClaw — there's no path from a prompt-injected agent to plaintext credentials on disk.

Step 5 — Memory and conversation history

If you depend on long-running conversation memory, you have two options:

Option A: drop it. For most agentic workflows, conversation history older than a week is noise. Starting clean is fine.

Option B: import. Hermes ships a one-shot importer for OpenClaw's SQLite-backed memory store:

hermes import openclaw \
  --memory ~/openclaw-snapshot-$(date +%Y%m%d)/memory \
  --target ~/.hermes/memory

The importer translates schemas, dedupes, and rejects entries with broken timestamps. Expect about 10% loss on a memory store that's been around for a few months.

Step 6 — Smoke test, then decommission

Run a basic task to make sure everything works:

hermes start
hermes run "List files in /workspace and summarize what this project does."

Watch the output. The first run is slow because Hermes is pulling provider SDKs. Subsequent runs are fast.

If it works, decommission OpenClaw cleanly:

# Stop and disable the service
systemctl --user stop openclaw
systemctl --user disable openclaw

# Or for non-systemd setups
pkill -f openclaw

# Remove the install but keep your snapshot
rm -rf ~/.openclaw

Don't rm -rf the snapshot directory. Keep it for at least a month. If something breaks in Hermes you couldn't anticipate, you'll want it.

Common gotchas

• Browser tool. Hermes uses a separate hermes-browser container. You need
• MCP servers. OpenClaw's MCP plugins need to be re-registered. Hermes uses
• Custom UI extensions. OpenClaw extensions are React components loaded at
• Telegram/Discord/WhatsApp bots. OpenClaw shipped these as built-ins.

What you gain, what you lose

You gain: a sandbox that exists, a credential vault that exists, an audit log that exists, an active maintainer team.

You lose: OpenClaw's slightly nicer dashboard UX, the ability to run completely unsandboxed (which you shouldn't have been doing anyway), and any custom extensions you wrote.

For 95% of self-hosters, the trade is worth it. For the other 5%, you probably already know what you need and can skip this guide.

What's next

If you're on macOS and don't need Linux portability, NanoClaw is a meaningfully simpler migration target — we'll cover that path in a follow-up. If you want fully offline, the same six steps work for ZeroClaw, but the credential and provider sections are different (no cloud LLMs to point at).

Subscribe to [the newsletter](/newsletter) to get the next guides.