OpenClaw → Hermes Agent

Migration Guide for Self-Hosted Discord AI Agents

PATH A

Claude Code Automated Migration

Done in ~2 minutes

PATH B

Manual Migration · Step by Step

9 steps, full understanding

Prerequisites: Node.js · npm · Running OpenClaw install · Anthropic API Key

What is Hermes Agent?

OpenClaw

Node.js event-driven architecture
Discord gateway
SOUL.md personality system
Memory & cron scheduling
Sub-agents

Hermes Agent ✦

Python sync loop — more reliable
Discord / Telegram / Slack
SOUL.md personality system ✓
Three-tier memory + Atropos RL
Sub-agents + MCP toolsets

✅ Same capabilities, better toolchain — hermes claw migrate auto-imports your existing config

PATH AClaude Code Automated Migration

For viewers who just want it done

①

Install Claude Code

②

Install Hermes

③

Hand it off to Claude Code

Claude Code will: read your existing config → run the migration tool → patch anything it couldn't auto-detect → verify the result

PATH AInstall Commands

Step A1 — Install Claude Code

npm install -g @anthropic/claude-code
claude --version

Step A2 — Install Hermes

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

PATH AHand it off to Claude Code

Step A3 — Run the migration prompt

claude --dangerously-skip-permissions "
Migrate my OpenClaw agent to Hermes Agent.
OpenClaw config: ~/.openclaw/openclaw.json
Secrets: ~/.openclaw/.env
Workspace: ~/my-agent/

Steps:
1. Run: hermes claw migrate
2. Verify ~/.hermes/config.yaml has correct model and API key
3. Set MESSAGING_CWD in ~/.hermes/.env to my workspace path
4. Set DISCORD_AUTO_THREAD=false in ~/.hermes/.env
5. Symlink SOUL.md: ln -sf ~/my-agent/SOUL.md ~/.hermes/SOUL.md
6. Update scripts calling 'openclaw' CLI — replace with hermes equivalents
7. Stop openclaw gateway, install and start hermes gateway service
8. Run: hermes doctor
9. Report any issues
"

Step A4 — Review the result

Run hermes doctor — all checks green → send a test message in Discord

PATH BManual Migration · Overview

For viewers who want to understand every step

1Install Hermes

2Run the auto-importer

3Verify model config

4Configure Discord settings

5Set workspace path

6Set up SOUL.md

7Update scripts calling OpenClaw CLI

8Swap the gateway service

9Verify

⚠️ Two critical gotchas in Step 4

PATH BStep 1 — Install Hermes

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
source ~/.bashrc
hermes --version
hermes doctor   # shows what's missing

PATH BStep 2 — Run the Auto-Importer

hermes claw migrate --dry-run   # preview first
hermes claw migrate             # execute

✅ Auto-handled: API keys · Model provider config · Discord token · Memory & skills data

⚠️ Manual follow-up needed: SOUL.md path · Workspace CWD · Scripts calling openclaw CLI directly

PATH BStep 3 — Verify Model Config

~/.hermes/config.yaml

model:
  default: claude-opus-4-6
  provider: anthropic

~/.hermes/.env

ANTHROPIC_API_KEY=sk-ant-your-key-here

PATH BStep 4 — Configure Discord ⚠️ Gotchas here

DISCORD_BOT_TOKEN=your-bot-token
DISCORD_ALLOWED_USERS=123456789012345678   # real user IDs only
DISCORD_FREE_RESPONSE_CHANNELS=111,222,333
DISCORD_AUTO_THREAD=false

⚠️ Gotcha 1: DISCORD_ALLOWED_USERS
Does NOT support * wildcard. Must be real Discord user IDs.
Get yours: Settings → Advanced → Developer Mode → right-click username → Copy User ID

⚠️ Gotcha 2: DISCORD_AUTO_THREAD
Defaults to true. Without this line, Hermes creates a new thread per message — your agent appears silent in the main channel

PATH BStep 5 — Set Workspace Path

# ~/.hermes/.env
MESSAGING_CWD=/path/to/your/workspace
TERMINAL_CWD=/path/to/your/workspace

Hermes auto-discovers AGENTS.md, MEMORY.md, and SOUL.md from this path on every session start

PATH BStep 6 — Set Up SOUL.md

ln -sf /path/to/your/workspace/SOUL.md ~/.hermes/SOUL.md

Hermes only reads the persona from ~/.hermes/SOUL.md. A symlink works fine.
If you don't have one, create it at that path — it's a plain text system prompt describing your agent's personality.

PATH BStep 7 — Update Scripts Calling OpenClaw CLI

grep -r "openclaw" ~/your-workspace/scripts/

OpenClaw	Hermes Equivalent
`source ~/.openclaw/.env`	`source ~/.hermes/.env`
`openclaw memory index`	`hermes memory index`
`openclaw browser navigate`	`agent-browser open`
`openclaw browser evaluate`	`agent-browser eval`
`openclaw acp`	`hermes acp`

agent-browser path: ~/.hermes/hermes-agent/node_modules/.bin/agent-browser

PATH BStep 8 — Swap the Gateway Service

# Stop OpenClaw
openclaw gateway stop
openclaw gateway uninstall

# Install Hermes as a systemd user service
hermes gateway install
hermes gateway start
hermes gateway status   # should show: active (running)

PATH BStep 9 — Verify

hermes doctor

✅ All hermes doctor checks green
✅ Send a message in Discord — agent responds with correct persona
✅ No new threads created in the main channel
✅ Run any cron pipelines manually to confirm
✅ hermes gateway status still running after a few minutes

Troubleshooting

Symptom	Cause	Fix
Agent offline after migration	Gateway not started	`hermes gateway start`
Agent creates threads, goes silent	`DISCORD_AUTO_THREAD` defaults to true	Add `DISCORD_AUTO_THREAD=false` to `.env`, restart gateway
"Unauthorized" on model calls	API key missing or wrong var name	Check `ANTHROPIC_API_KEY` is in `~/.hermes/.env`
Agent ignores messages	`DISCORD_ALLOWED_USERS` set to `*`	Replace with your actual Discord user ID
Wrong persona / no personality	SOUL.md not found	`ln -sf /your/SOUL.md ~/.hermes/SOUL.md`
Cron pipeline fails	Scripts still call `openclaw` CLI	`grep -r openclaw ~/scripts/` then replace
Memory / context not loading	`MESSAGING_CWD` not set	Add `MESSAGING_CWD=/your/workspace` to `.env`

Key Takeaways

PATH A

Claude Code handles the whole migration automatically in ~2 minutes

PATH B

9 manual steps — full understanding of every piece

⚠️ Two biggest gotchas: DISCORD_AUTO_THREAD=false and DISCORD_ALLOWED_USERS needs real user IDs

✅ SOUL.md must be at ~/.hermes/SOUL.md — symlink works fine

📚 Hermes Docs: https://hermes-agent.nousresearch.com/docs/

💻 GitHub: https://github.com/NousResearch/hermes-agent