Hermes Agent Troubleshooting Guide

Running into issues with Hermes Agent? You're not alone. Based on real support threads from the Discord community and Reddit, here's what's actually going wrong — and how to fix it.

⚠️ Easier alternative: If self-hosting Hermes feels like fighting battles you didn't sign up for, try OpenClaw Cloud instead. Same capabilities, less maintenance, starts at free.

---

1. Token Overhead via Telegram — 2-3x CLI Usage

Problem: User kerichuu nailed this one:

"With some tools/skills enabled, and a close to default SOUL.md file, Hermes uses around 6-8k input tokens in CLI, and around 15-20k input tokens when using Telegram"

That's 2-3x the token cost for the exact same conversation. The root cause: gateway spawning in the hermes-agent directory loads development AGENTS.md and other "garbage data" that shouldn't be there.

Solution: teknium fixed this — Hermes should now start in the user's home directory instead. Update to the latest version:

hermes update
hermes gateway restart

If still seeing bloat, check your working directory. The gateway should be starting from $HOME, not the Hermes source folder.

---

2. Local Models Lose Web Access

Problem: You've got Ollama running locally with a good model. But suddenly the browser tools don't work. Cloud models (Anthropic, OpenRouter) work fine, but local models act like they have no internet.

This is a known issue where web tools only get enabled when the configured web backend passes certain checks — checks that local models often fail.

Solution:

1. Use a cloud provider for browsing tasks — switch to MiniMax, GLM, or DeepSeek for web-heavy work
2. Check your Firecrawl/scrape config — make sure the web backend is properly configured:

hermes config get web
hermes config set web provider firecrawl

Local models are great for offline reasoning, but for now, keep cloud models as your "web access" backup.

---

3. Tirith Blocking Commands Without Approval

Problem: Tirith is Hermes's security module. But it's blocking commands like curl | sh with a hard block instead of giving you an approval prompt. User expected:

"Wait, are you sure? This command looks risky. Allow?"

What they got: outright rejection with no option to proceed.

Solution: This is by design for safety, but the community wants an interactive approval flow. For now:

• Split your commands — run the fetch and the pipe separately
• Use the terminal directly for risky commands (not the gateway):

curl https://example.com/script.sh -o script.sh
bash script.sh

⚠️ Security note: Hard blocks exist for good reason. If Tirith is blocking something, there's usually a safer way to accomplish the same task.

---

4. GPT-5 / Codex Intermittent Errors

Problem: Users hitting intermittent API errors through Codex:

"most of the times the agent retries, but other times it gets stuck"

This happens with GPT-5 and some cloud providers. Not every call fails, but enough to be frustrating.

Solution:

1. Add auto-retry in your config:

hermes config set retry attempts 3
hermes config set retry backoff exponential

2. Switch to a more stable provider while debugging:

hermes config set defaultprovider minimax

3. Check provider status pages — sometimes it's their infrastructure, not yours

---

5. Hermestrons Can't Find Hermes (Fresh Install)

Problem: User kidtaroi ran into this — fresh install, hermes-agent command not found.

Solution:

1. Check your PATH:

echo $PATH
which hermes-agent

2. Reinstall properly:

curl -L https://hermes-agent.nousresearch.com/install | sh

3. Restart your shell — new installs need a fresh terminal session

---

6. Setup Issues for Beginners

Problem: New users hit a wall right at the start. The setup docs assume knowledge that beginners don't have.

Solution:

1. Start with the one-command migration from OpenClaw:

hermes claw migrate

2. Use the starter config:

hermes init --template minimal

3. Join the community — #hermes-agent on Discord has helpful folks answering questions within hours

Pro tip from the Discord community: "I'd chose something cheap or free at first so you get the hang of things before you jump yourself out of house and home with some of the higher end models"

---

7. High Token Consumption (The Elephant in the Room)

Problem: Reddit user u/Typical_Ice_3645 put it plainly:

"4 million tokens in 2 hours of light usage... 21K tokens just asking about the weather"

Solution from the community:

1. Delete unused built-in skills (pokemon, minecraft) — they load on every request
2. Use a cost-effective provider:
   • MiniMax Token Plan: $10/month, 1500 requests/5h window
   • DeepSeek V4: $0.30/M input → $0.03/M on cache hits (90% off)
3. Load skills lazily instead of all at once — saves ~2.2K tokens per request
4. Platform-specific toolsets — don't load browser tools for messaging channels

---

Still Stuck?

• Discord: #hermes-agent channel in the Nous Research server
• Reddit: r/hermesagent (2,900+ members, active discussions)
• Docs: hermes-agent.nousresearch.com/docs

Or, if all this troubleshooting feels like a second job — try OpenClaw Cloud. Same agent capabilities, starts working in minutes.