0xNyk/openclaw-to-hermes

openclaw-to-hermes

Migrate from OpenClaw to Hermes Agent — a complete, battle-tested migration tool.

Built from a real production migration. Fixes every issue we found in the existing hermes-migrate tool.

Note: As of Hermes Agent v0.3.0+, the native hermes claw migrate command now covers the full migration path — including the bugs this tool was originally built to fix. For new migrations, use the native command first:

hermes claw migrate              # Interactive migration
hermes claw migrate --preset full --overwrite  # Full migration

This tool remains useful as a reference implementation and for users on older Hermes versions (pre-v0.3.0) where the native migration had known issues.

What It Does

• Discovers all OpenClaw agents, workspaces, channels, and credentials
• Migrates SOUL.md, MEMORY.md, workspace files, skills, and memory archives
• Maps OpenClaw config → Hermes config.yaml (models, channels, tools, advanced settings)
• Handles dict-type model configs (primary/fallbacks) correctly
• Migrates credentials from both ~/.openclaw/ and /etc/openclaw-tenants/
• Writes auth.json in the correct Hermes nested format
• Sets up systemd gateway service with lingering
• Creates backup archive before any destructive operations
• Supports dry-run mode for safe preview

Quick Start

# Install
pip install openclaw-to-hermes
# or
pipx install openclaw-to-hermes

# Preview what will happen
oc2hermes --dry-run

# Run full migration
oc2hermes

# Migrate a specific agent
oc2hermes --agent quant

# Skip auto-start of hermes gateway
oc2hermes --no-start

What Gets Migrated

Prerequisites

• OpenClaw installed and configured (~/.openclaw/openclaw.json exists)
• Hermes Agent installed (hermes CLI available or auto-installed)
• Python 3.10+

Architecture

~/.openclaw/
├── openclaw.json              # Main config (agents, models, channels, tools)
├── state/
│   └── agents/{id}/agent/
│       └── auth-profiles.json # OAuth tokens, API keys
└── .env                       # (optional) env vars

/etc/openclaw-tenants/
└── {user}.env                 # System-level secrets (bot tokens, gateway tokens)

~/clawd/                       # Agent workspace (configurable path)
├── SOUL.md                    # Persona
├── MEMORY.md                  # Agent memory
├── USER.md                    # User profile
├── IDENTITY.md                # Identity config
├── AGENTS.md                  # Multi-agent setup
├── TOOLS.md                   # Tool documentation
├── HEARTBEAT.md               # Heartbeat config
├── memory/                    # Daily logs, research notes
└── skills/                    # Agent skills

        ↓ oc2hermes ↓

~/.hermes/
├── config.yaml                # Unified config
├── SOUL.md                    # Persona
├── auth.json                  # OAuth (nested providers format)
├── .env                       # API keys, bot tokens
├── memories/
│   ├── MEMORY.md
│   ├── USER.md
│   ├── IDENTITY.md
│   ├── openclaw_archive/      # Memory history
│   └── openclaw_skills/       # Migrated skills
└── cron/
    └── jobs.json              # Scheduled tasks

Known Issues with hermes-migrate

This tool exists because the official hermes-migrate (v1.2.1) has several bugs:

1. Crashes on dict model configs — agents.list[].model can be {"primary": "...", "fallbacks": [...]}, not just a string
2. Wrong auth.json format — writes flat structure instead of nested providers.{id}.tokens
3. Misses workspace files — doesn't detect SOUL.md, MEMORY.md, etc. in the agent workspace directory
4. No system env handling — doesn't read /etc/openclaw-tenants/{user}.env for bot tokens
5. Stale OAuth tokens — can't refresh expired tokens, needs device-code re-auth
6. Missing croniter dependency — hermes-agent venv lacks croniter for cron job creation
7. Gateway restart hangs — hermes gateway restart can block indefinitely

Post-Migration Steps

After running oc2hermes:

1. Verify credentials: hermes status — check API keys and auth providers
2. Re-authenticate OAuth (if tokens expired): The tool will prompt you
3. Approve Telegram pairing: Send a message to your bot, then run the pairing command it shows
4. Set home channel: Type /sethome in your Telegram chat with the bot
5. Verify cron jobs: hermes cron list

Configuration

Create ~/.oc2hermes.yaml to customize behavior:

# Override workspace detection
workspace: /home/user/clawd

# Skip specific migration steps
skip:
  - credentials   # Don't migrate credentials
  - cron          # Don't create cron jobs

# Custom model mapping (OpenClaw model → Hermes model)
model_map:
  "openai-codex/gpt-5.3-codex": "openrouter/auto"
  "ollama/qwen3.5:9b": "qwen/qwen3.5-9b"

# OpenRouter as default provider
provider: openrouter
openrouter_model: "openrouter/auto"

# System env file path (for bot tokens)
tenant_env: /etc/openclaw-tenants/{user}.env

Development

git clone https://github.com/0xNyk/openclaw-to-hermes.git
cd openclaw-to-hermes
uv venv && source .venv/bin/activate
uv pip install -e ".[dev]"

# Run tests
pytest

# Lint
ruff check .

License

MIT