Migrating from OpenClaw to Hermes Agent: A Hands-On Guide

TL;DR — OpenClaw is now maintenance-only and the migration window has opened. Hermes Agent v0.14 ships hermes claw migrate, which reads ~/.openclaw/config.yaml, transplants your API keys, models, custom skills, and memory into ~/.hermes/, and leaves the source untouched. Most OpenClaw users finish the switch in under ten minutes — the real work is unlearning the tier-routing mental model and trusting Hermes’ skill loop to fill the gap. This guide walks through the exact command, the config-key mapping, what doesn’t migrate, and how to verify the result before you archive the old install.

Why the OpenClaw → Hermes migration is happening now

The big push started April 4, when Anthropic killed OAuth access for third-party tools. OpenClaw setups that routed Claude requests through a personal Claude Pro or Max subscription stopped working overnight. Moving to a direct API key (Anthropic, ofox.ai, or any other gateway) was always the recommended path; the ban turned it into a forcing function.

Around the same window, OpenClaw quietly moved into maintenance mode. Releases still ship, the YAML config layer and tier-routing engine remain stable, but the original team has stopped adding agent-level features. Everything novel in agent-land this year — persistent skills, cross-surface deployment, dialectic memory — is happening elsewhere.

That elsewhere is Hermes Agent. Nous Research’s self-improving AI agent shipped v0.14 on May 16, crossed 140K GitHub stars, and overtook OpenClaw on OpenRouter’s daily token rankings on May 10. The migration tool itself, hermes claw migrate, is the clearest signal: when the new platform builds a first-class importer for the old one, the direction of travel is settled.

You don’t have to migrate today. You probably do want to plan it within a quarter.

What migrates, what doesn’t

The migrator handles the things you’d dread doing by hand and skips the things that don’t map cleanly:

The tier-routing skip is the one most people stumble on. OpenClaw’s mental model was “configure three tiers, let the framework decide.” Hermes’ model is “pick a default with hermes model, then let the agent’s skill loop opt into stronger models when a skill says so.” It’s not worse, but it’s different — give yourself a week of real use before deciding the routing story doesn’t carry over.

The migration command

Install Hermes first if you haven’t already. On Linux, macOS, WSL2, or Termux:

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

The installer drops a hermes binary on your PATH and creates ~/.hermes/. Once it’s there, the migration is a single command:

hermes claw migrate

If ~/.openclaw/ exists, hermes setup will also detect it and offer the same migration interactively. Either path works; the standalone command is easier to script and re-run.

The flags you’ll actually use:

# See what would be migrated without changing anything
hermes claw migrate --dry-run

# Migrate only user data (skills, memory, preferences) — skip credentials
hermes claw migrate --preset user-data

# Overwrite Hermes state that already exists from a previous setup
hermes claw migrate --overwrite

# Point at a non-default OpenClaw config root
hermes claw migrate --source ~/work/.openclaw

--dry-run is what you want the first time. It writes a manifest of every file that would be read, every credential that would be transplanted, and every skill that would be copied, then exits without touching ~/.hermes/. Run it, eyeball the manifest, and only then drop the flag.

The --preset user-data mode is the right call when you’re moving to a fresh machine or a shared workstation where you’d rather re-enter credentials manually than copy them off the source. Your skills and memory still carry over — those are the parts that took you months to accumulate.

Config-key mapping in practice

The OpenClaw-to-Hermes config translation is mostly direct, but a few keys deserve attention before you eyeball your old file and wonder “where did that go?”

Provider credentials. OpenClaw nests them in providers.<name>:

# ~/.openclaw/config.yaml (before)
providers:
  ofox:
    api_key: sk-your-ofox-key
    base_url: https://api.ofox.ai/v1

Hermes reads them flat from environment in ~/.hermes/.env:

# ~/.hermes/.env (after)
OPENAI_API_KEY=sk-your-ofox-key
OPENAI_BASE_URL=https://api.ofox.ai/v1

If you were using ofox or any other OpenAI-compatible gateway in OpenClaw, this is the smoothest part of the whole migration. Hermes follows the same conventions documented in the OpenAI SDK migration guide, so anything you’d configured to talk to ofox keeps working with no behavioral change.

Default model. OpenClaw stored provider: anthropic plus model: claude-sonnet-4.6 at the top level. Hermes stores the equivalent under its own config, but the canonical way to set it is interactive:

hermes model

This opens a picker over your provider’s catalog. For ofox users, the pickable IDs include anthropic/claude-opus-4.7, anthropic/claude-sonnet-4.6, deepseek/deepseek-v4-pro, openai/gpt-5.5, and the rest of the catalog you’d see in your dashboard.

Agent behavior. OpenClaw’s agent.max_tokens, agent.temperature, and agent.max_retries don’t have a one-to-one Hermes equivalent. Hermes assumes sensible defaults and lets you override per-skill or via prompt flags. If you’d manually tuned these in OpenClaw, you usually don’t need them in Hermes — the defaults are tighter and the skill system absorbs much of what max_retries used to handle.

Tier routing. This is the one place OpenClaw users sometimes want to fight the migration. OpenClaw’s three-tier models.yaml doesn’t transplant. The Hermes-native pattern, if you genuinely need cost-aware routing, is:

1. Set your default to a mid-tier model with hermes model (Sonnet 4.6 or DeepSeek V4 Pro are common picks).
2. Write small skills that explicitly call out a stronger model for tasks that need it — in the SKILL.md frontmatter, that means a metadata.hermes.model block with provider: anthropic and model: claude-opus-4.7. Hermes swaps to that model for the skill’s turn and switches back when it returns.
3. Let the skill loop handle escalation rather than a routing config.

It’s a different shape, but it ends up doing the same job with less YAML. The API cost reduction playbook covers the routing-by-task-difficulty pattern in detail — most of it ports directly to the new model.

Verifying the migration

Don’t trust the migrator’s “done” message until you’ve spot-checked a few things:

# 1. Confirm Hermes can see your credentials and reach the provider
hermes status

# 2. Walk the skill list and make sure your custom ones came across
hermes skills list

# 3. Open the memory file and check it isn't empty
cat ~/.hermes/memories/MEMORY.md

# 4. Do a single round-trip against your default model
hermes chat -q "respond with 'migration ok' and nothing else"

If any of those four fail, the most common cause is permissions on ~/.openclaw/ blocking the migrator’s read. Re-run with --dry-run and check the manifest for skip warnings.

The other gotcha worth checking: if you’d configured OpenClaw’s auto_approve: true for file edits, Hermes defaults to requiring confirmation. That’s a deliberate safety choice. Hermes’ permission model is closer to Claude Code’s than to OpenClaw’s older “trust the agent” approach. If you genuinely want the OpenClaw behavior back, it’s a config toggle, but most people leave the new default in place.

Routing your migrated setup through ofox

The single most-cited reason developers give for migrating is wanting cleaner multi-model access. If you were already using ofox in OpenClaw, you’ll skip this section. If you were using Anthropic + OpenAI keys directly and copy-pasting each one, this is where Hermes pays off immediately.

Replace your .env with:

# ~/.hermes/.env
OPENAI_BASE_URL=https://api.ofox.ai/v1
OPENAI_API_KEY=sk-your-ofox-key

Then run hermes model and you’ll see the full ofox catalog as pickable options. One key, one base URL, the whole catalog — that’s the API aggregation pattern the rest of the agent ecosystem is converging on. Hermes’ skill loop benefits especially: when a skill says “use Opus 4.7 for this step and DeepSeek V4 Pro for the next,” both calls go through the same authenticated endpoint with no provider juggling.

For picking which model fits which workload, the best AI model for agents 2026 breakdown has the up-to-date task-by-task recommendations. The short version: Sonnet 4.6 as the default workhorse, Opus 4.7 for tasks where reasoning quality genuinely matters, DeepSeek V4 Pro when token volume is the dominant cost.

When you should not migrate yet

A few cases where waiting is the right call. CI/CD pipelines that invoke openclaw with specific subcommands won’t survive the move untouched — Hermes’ CLI surface is different enough that you’ll be rewriting glue scripts, so plan the migration as a project rather than a five-minute task. The same caution applies if your team has internal skills assuming OpenClaw’s tier routing: migrate one user first, document the new pattern, then move everyone else. And if you’re mid-deliverable, don’t change your tooling in the last week of a sprint. Migrate during slack time.

A narrower case worth naming: if you rely on an OpenClaw-specific search provider plugin that doesn’t have a Hermes equivalent, file an issue on the Hermes repo before assuming you’re stuck. Most search-tool gaps have been closed in the last two release cycles.

For everyone else (solo developer, small team, normal interactive use), there’s no good reason to defer. The migrator does the hard work, the source files stay where they are, and you can always uninstall Hermes and go back to OpenClaw the same day if it doesn’t fit. Most people don’t.

The migration mindset shift

The thing that took me longest to adjust to wasn’t the new CLI — it was giving up the “configure everything up front” mental model. OpenClaw rewarded careful YAML; Hermes rewards letting the agent build up its own working knowledge of you over a few weeks. The first three days feel emptier than your old setup. By week three, the skill library has filled in and the agent is doing things your OpenClaw install never could because it never persisted what it learned.

Run hermes claw migrate --dry-run, then hermes claw migrate, then hermes setup to confirm everything’s wired. Give it a week of real use before deciding what, if anything, you miss.