.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
The annoying thing about hermes claw migrate is that it usually doesn't fail loudly. It finishes with a tidy summary, exits 0 and you find out something went wrong only the next day when a skill you used to rely on doesn't fire. This guide collects the silent-failure modes I've seen hit real installs over the last six weeks of helping people on the Hermes Discord, with the fix or workaround for each.
Before troubleshooting, run hermes doctor. It catches a surprising number of post-migration issues on its own, especially anything to do with provider credentials or the state DB. If hermes doctor is clean and you still have problems, this is the article you want.
The migration "succeeded" but no skills appear
Symptom: you run hermes claw migrate, it tells you "imported 24 skills", you start hermes, you type /skills and only the built-in skills show up.
The most common cause: the skills did import to ~/.hermes/skills/openclaw-imports/, but the directory permissions came out as 600 or 640 instead of 755 because of how the tarball was extracted before the migration ran. Hermes can read the SKILL.md files but not enter the directories, so the skill registry sees zero. Fix:
chmod -R u+rwX,go+rX ~/.hermes/skills/Then restart Hermes (or run /skills reload inside the CLI if your version supports it). The imported skills should appear.
Second cause: the SKILL.md files are there but their YAML frontmatter is malformed in a way Hermes silently rejects. The migration tool patches obvious tool-name renames, but if your OpenClaw skill used a tool prefix Hermes doesn't recognise, the skill loader silently drops the skill instead of erroring. Run hermes with HERMES_LOG_LEVEL=debug set and grep the log for skill load failed. Whichever skills appear there need their frontmatter tools: section trimmed to only tools Hermes really has.
Telegram works for a few minutes, then goes silent
This is the gateway-collision problem and it's by far the most reported post-migration bug.
What's happening: your old OpenClaw gateway is still running somewhere on the same machine, polling the same Telegram bot token Hermes is now also polling. Telegram delivers each incoming message to one of the two long-polls at random. From your perspective, half your messages get answered by Hermes, the other half get answered by OpenClaw. Since the OpenClaw replies look identical to Hermes ones (you migrated the persona), it just feels like your bot is forgetful.
Diagnose with:
ps aux | grep -E 'openclaw|hermes' | grep -v grep
sudo systemctl status openclaw 2>/dev/null
sudo systemctl status hermes 2>/dev/nullIf you see two gateway processes alive, kill or stop the OpenClaw one. The migration only updates Hermes's config; it doesn't touch your OpenClaw service.
If you only see one gateway alive but Telegram still goes silent intermittently, check that you're not running an old tmux session with OpenClaw started inside it. tmux ls followed by tmux attach -t <name> on each session, kill anything that shouldn't be there.
Memories migrated but the agent acts like it doesn't know me
You verified ~/.hermes/memories/USER.md has content. The persona file is in place. But the agent answers questions about your projects with generic responses, as if it never read the files.
Two things to check.
First, the memory loading order. Hermes loads SOUL.md, MEMORY.md and USER.md in that order at session start. They get joined into the system prompt. If any of them is over a hard size limit (around 32K characters in the current code, give or take), Hermes truncates and may drop later files entirely. Run wc -c ~/.hermes/SOUL.md ~/.hermes/memories/MEMORY.md ~/.hermes/memories/USER.md. If any single file is over about 30K, that's likely the issue. Trim or split the file.
Second, the format. The migration tool preserves the OpenClaw memory format, which uses a slightly different heading convention than Hermes's native MEMORY.md format. Specifically, OpenClaw uses ## entry separators with timestamp lines, while Hermes expects ## YYYY-MM-DD topic. The migration tool's converter handles most of these, but if your OpenClaw memory file had any custom formatting, the converter may have left non-standard sections in place. Open the file, scan for headings that don't match the date-prefixed pattern, fix or remove them.
Bot token migrated but Telegram returns 401
You see 401 Unauthorized in the gateway logs after migration. The token migrated, you can see it in ~/.hermes/.env, but Telegram refuses it.
This is almost always the secret-key encoding. OpenClaw and Hermes both store API keys in .env, but they handle keys with special characters slightly differently. If your Telegram bot token contains a colon (it always does, that's the standard format) and the migration step copied it in unquoted, you're fine. If the migration tool wrapped it in single quotes (it should not, but in some cases does), the wrapper preserves the quotes when reading and the colon parsing breaks.
Open ~/.hermes/.env. Make sure your bot token line looks like:
TELEGRAM_BOT_TOKEN=123456789:ABCDEF-GhIjKlMnOpQrStUvWxYzNot:
TELEGRAM_BOT_TOKEN='123456789:ABCDEF-GhIjKlMnOpQrStUvWxYz'Strip the quotes if they're there. Restart the gateway.
The gateway crashes on startup with a Python tracetrace
If hermes gateway start crashes immediately with a long Python tracetrace, the migration brought across a config option that points at something that no longer exists. Common culprits:
An EMAIL_IMAP_HOST that's been deprecated by your provider. Gmail's IMAP host changed last year for OAuth-only accounts; if your OpenClaw config still pointed at the old hostname, Hermes fails to connect during gateway init and crashes the whole process. Comment out the email block in ~/.hermes/.env until you can update it.
A WHATSAPP_SESSION_DIR that points at a path under ~/.openclaw/ instead of ~/.hermes/. The migration tool tries to fix these, but if your OpenClaw config stored an absolute path rather than a relative one, the migrated config inherits the absolute path. Edit it, change the path to ~/.hermes/whatsapp/, restart.
An LLM provider that requires an env var the migration didn't carry across. NVIDIA NIM and certain regional providers want extra config beyond just an API key (a base URL, a region, etc.). Run hermes doctor right after the migration to catch these before you start the gateway; doctor's provider check often flags the missing field.
Skill conflicts you didn't know you had
You ran the migration with --skill-conflict rename and now you have two skills with similar names doing similar things. The renamed skill from OpenClaw has a suffix like -imported-2026-05-05. Practical question: which one is going to fire when you trigger the underlying functionality?
Hermes resolves skill matching by exact name first, then by alias. The renamed import has the original name plus a timestamp suffix, so if the agent matches by user prompt to "the cron skill", it picks Hermes's built-in cron over your renamed cron-imported-2026-05-05. If you want your imported version to take precedence, rename it back to cron (which means deleting or renaming Hermes's stock one) or alias it explicitly in the SKILL.md frontmatter:
---
name: cron-imported-2026-05-05
aliases:
- cron
- schedule
description: My customised cron skill from OpenClaw
---The aliases field lets your renamed import respond to "cron" matches without having to rename the file on disk.
The migration archive folder fills up your disk
Six months in, you notice ~/.hermes/migration/openclaw/ is taking 2 GB. Every time you re-run the migration (because you tweaked a flag, because you tried a dry-run that wasn't quite a dry-run, because you forgot you'd done one), Hermes creates a new timestamped folder.
You can safely delete old archive folders. They're snapshots of the pre-migration Hermes state. Once you're sure the migration worked you don't need them. Keep the most recent one as a rollback point, delete the rest:
cd ~/.hermes/migration/openclaw
ls -lt | head
# Inspect, then:
ls -lt | tail -n +3 | awk '{print $NF}' | xargs rm -rfInspect first, delete second. The tail -n +3 keeps the two newest, removes the rest.
The dry-run output and the real run don't match
Sometimes the dry-run shows 24 skills will be imported and the real run only imports 19. The five missing ones aren't always reported in the real-run output as skipped; they just don't appear.
This is a known issue when the OpenClaw skill directory contains skills that import other skills via a requires: field. The dependency resolution differs subtly between the dry-run and the real run. The fix: set HERMES_MIGRATE_VERBOSE=1 before running the real migration. The verbose mode logs each skill skip with a reason, so you can see which deps weren't met. Then either copy those skills manually or, if they're skills you barely use, leave them.
Re-running migration without losing edits
After your first migration, you'll probably want to refine things: edit a skill, prune the memory file, add a new persona line. Sometime later, you might want to re-run the migration to pick up something from the OpenClaw side that's changed. The default behaviour with --overwrite is to clobber your edits.
The pattern that works: skip skills entirely on the second run with --skill-conflict skip, do a memory diff manually rather than re-merging via the migration tool, only re-import the OpenClaw config if you specifically need an updated bot token. If you're micromanaging the second run that hard, doing it by hand with rsync and a few targeted file edits is often less work than wrestling with migrate flags.
Running on a fresh box from a tarball
Some of these silent failure modes only show up when the migration is run on the same box where OpenClaw was installed, because Hermes inherits weirdness from the local environment. If you're running into intractable post-migration problems, an alternative is to migrate to a fresh server. The LumaDock Hermes Agent VPS template ships an Ubuntu 24.04 image with the install already done. You scp a tarball of ~/.openclaw/ across, untar it, run the migration with --source <path> and you've eliminated all the "but my old box has a quirk" failure modes in one go. Once you've validated the migrated setup on the fresh box, you can either keep it as the new home or copy ~/.hermes/ back to your original server. Our VPS setup guide covers the dashboard pairing and SSH tunnel on the new server so you can verify the migration through a browser before changing anything else.
When all else fails, look at the migration log
Hermes writes a per-run log to ~/.hermes/migration/openclaw/<timestamp>/migrate.log. It's plaintext, line-per-event and it logs more than the console output shows. If you've got a silent failure, that log usually has the answer:
less ~/.hermes/migration/openclaw/$(ls -t ~/.hermes/migration/openclaw/ | head -1)/migrate.logSearch for WARN and ERROR lines. The summary at the bottom of the log lists every skip with a reason code, even when the console summary just said "imported X items".
If you've still got a problem after all of the above, file an issue with the relevant migrate.log excerpt, your Hermes version, your OpenClaw version and the exact hermes claw migrate command line you ran. The maintainers respond fastest to issues that include the log; vague reports tend to bounce around for weeks.
