Migrating from OpenClaw to Hermes Agent: Zero-Downtime Guide

🟢 Beginner⏱ 7 min read📅 2026-04-14👤 HermesAgent Community

Why Migrate to Hermes Agent?

OpenClaw was one of the earliest AI agent frameworks, and many users started their journey there. Hermes Agent is the natural successor, built by NousResearch with significant improvements across the board.

Here's what you gain by migrating:

| Feature | OpenClaw | Hermes Agent |

|---------|----------|--------------|

| Model support | ~20 models | 200+ models via OpenRouter |

| Memory system | Basic | Persistent + contextual |

| Skills ecosystem | Limited | 100+ community skills |

| Multi-agent | ❌ | ✅ Sub-agent orchestration |

| Messaging | Telegram only | Telegram, Discord, Slack, Signal |

| Cron scheduling | ❌ | ✅ Built-in |

| MCP support | ❌ | ✅ Full integration |

| Self-learning | Limited | ✅ Skill learning loop |

| Active development | Maintenance | Active (74.9k ⭐) |

Important: This guide assumes you're running OpenClaw v2.x or later. Earlier versions may have different file structures.

Pre-Migration Checklist

Before starting, gather the following from your OpenClaw installation:

# Find your OpenClaw data directory echo $OPENCLAW_HOME # Usually: ~/.openclaw # Check installed skills openclaw skills list > my-skills-backup.txt # Export conversation history openclaw export --all > conversations-backup.json # Backup configuration cp ~/.openclaw/config.json ~/openclaw-config-backup.json

Make sure you have:

[ ] API key (you'll reuse this with Hermes)
[ ] List of installed skills
[ ] Exported conversations (if you want to keep them)
[ ] Configuration backup
[ ] Any custom scripts or automations

Step 1: Install Hermes Agent

Install Hermes alongside OpenClaw — you don't need to uninstall OpenClaw first:

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

Verify the installation:

hermes --version # hermes-agent v0.8.x

Both tools can coexist with no conflicts. This lets you test Hermes before fully committing.

Step 2: Migrate Configuration

API Key

Your OpenRouter or OpenAI API key works with both tools:

# Get your API key from OpenClaw config cat ~/.openclaw/config.json | grep api_key # Set it in Hermes hermes config set api_key "your-api-key-here"

Model Settings

OpenClaw and Hermes use slightly different model naming:

| OpenClaw Format | Hermes Format |

|----------------|---------------|

| claude-3-sonnet | anthropic/claude-3.5-sonnet |

| gpt-4 | openai/gpt-4o |

| llama-70b | meta-llama/llama-3.1-70b-instruct |

# Set your preferred model hermes config set default_model anthropic/claude-3.5-sonnet hermes config set provider openrouter

Behavior Settings

Map your OpenClaw preferences to Hermes:

# If OpenClaw had auto_execute: true hermes config set auto_confirm true # If OpenClaw had verbose: true hermes config set verbose true # Temperature hermes config set temperature 0.7

Step 3: Migrate Conversations

Hermes includes a built-in migration tool for OpenClaw conversations:

# Migrate all conversations hermes migrate openclaw --source ~/.openclaw/sessions # Migrate specific sessions hermes migrate openclaw --source ~/.openclaw/sessions/project-alpha # Dry run (preview without changes) hermes migrate openclaw --source ~/.openclaw/sessions --dry-run

Migration Preview:
  Sessions found: 12
  Total messages: 847
  Destination: ~/.hermes/sessions/
  
  ✅ project-alpha (142 messages)
  ✅ web-scraper (89 messages)
  ✅ daily-reports (203 messages)
  ⚠️ old-test (3 messages, skipping — too short)
  ...

Proceed? [y/N]

Manual Conversation Import

If the automatic migration doesn't work, you can import conversations manually:

# Export from OpenClaw
openclaw export --session project-alpha --format json > project-alpha.json

# Import into Hermes
hermes session import project-alpha.json

Step 4: Migrate Skills

Most OpenClaw skills have Hermes equivalents. Here's the mapping:

| OpenClaw Skill | Hermes Equivalent |

|---------------|-------------------|

| web-search | web-search (built-in) |

| file-reader | file-manager (built-in) |

| code-exec | code-runner (built-in) |

| github-tool | hermes skill install github-integration |

| email-sender | hermes skill install email-tool |

Install the equivalent skills:

# Install common skills hermes skill install github-integration hermes skill install email-tool hermes skill install web-scraper # List all available community skills hermes skill search ""

Custom Skills

If you wrote custom OpenClaw skills, they need to be ported to Hermes format. The key differences:

// OpenClaw skill format (old)
module.exports = {
  name: "my-skill",
  execute: async (args, context) => {
    return { result: "done" };
  }
};

// Hermes skill format (new)
export default {
  name: "my-skill",
  version: "1.0.0",
  description: "My custom skill",
  parameters: {
    input: { type: "string", required: true }
  },
  execute: async ({ input }, { agent, memory }) => {
    return { success: true, output: "done" };
  }
};

Key changes:

Use ES modules (export default) instead of CommonJS

Add version and description fields

Define parameters schema

The execute function receives destructured params and a richer context object

Step 5: Migrate Automations

If you used OpenClaw's scheduling (via external cron), Hermes has built-in support:

# Old approach: external crontab # 0 9 * openclaw run "Generate daily report" --session daily # New approach: Hermes built-in cron hermes cron add "Generate daily report" --schedule "0 9 *" --session daily-reports

List and manage scheduled tasks:

hermes cron list hermes cron enable daily-report hermes cron disable daily-report hermes cron delete daily-report

Step 6: Verify Everything Works

Run through this checklist to make sure the migration is complete:

# 1. Test connection hermes --test-connection # 2. Test a conversation hermes "Hello! Tell me a joke." # 3. Check migrated sessions hermes session list # 4. Verify skills hermes skill list # 5. Check memory hermes memory list # 6. Test cron (if used) hermes cron list

Step 7: Decommission OpenClaw

Once you've verified everything works in Hermes, you can safely remove OpenClaw:

# Backup OpenClaw data (just in case)
tar -czf openclaw-backup.tar.gz ~/.openclaw

# Uninstall OpenClaw
npm uninstall -g openclaw

# Remove data directory (optional)
rm -rf ~/.openclaw

Tip: Keep the backup (openclaw-backup.tar.gz) for at least a month, just in case you need to reference old conversations.

Troubleshooting Migration Issues

"Conversation format not recognized"

This usually means you're migrating from OpenClaw v1.x. Try:

hermes migrate openclaw --source ~/.openclaw/sessions --format v1

"Skill not compatible"

Some OpenClaw skills don't have direct Hermes equivalents. Check the community skills directory or port the skill manually.

"API key rejected"

If you were using OpenClaw's built-in API proxy, you'll need to get a direct API key from OpenRouter or your preferred provider.

Next Steps

Welcome to Hermes Agent! Now explore what's new:

Your first Hermes conversation — Learn the new interaction patterns
Choose the right AI model — 200+ models to choose from
Multi-agent orchestration — The feature OpenClaw never had

Last updated: April 15, 2026 · Hermes Agent v0.8

← Back to TutorialsTutorial Index