How to Troubleshoot Hermes Agent Gateways

When a Hermes Agent gateway fails, the visible symptom is usually vague: Telegram stops replying, Discord ignores a thread, a cron alert never arrives, or a restart says the gateway is connected while the bot stays silent. The fix is to debug the message path in layers instead of changing tokens, config, Docker, and model providers all at once.

The gateway failure map#

A gateway message crosses more layers than a terminal chat:

1. The platform receives the message.
2. The platform adapter sees the update.
3. Chat, channel, or topic gating allows the message.
4. Hermes starts an agent turn.
5. The selected model provider responds.
6. Tools run if needed.
7. Hermes sends the reply back through the platform.

A failure at any layer can look like “the bot is broken.” That is why the first rule is to avoid debugging from the user interface alone.

Step 1: prove Hermes works without the gateway#

Before touching Telegram or Discord, run:

hermes doctor
hermes chat -q "reply with gateway-smoke-test"

If the CLI cannot answer, the gateway is not the first problem. Fix model provider, config, terminal backend, tool requirements, or API keys with the Hermes setup guide and API keys guide. A gateway cannot hide a broken base agent.

Step 2: check the gateway process#

Run:

hermes gateway status
hermes status --all

On macOS, also remember that launchd can report a process as loaded even when the agent loop is wedged after a restart. If the platform looks connected but every message gets ignored, restart the real gateway process rather than trusting one status line.

Useful recovery commands include:

hermes gateway restart
hermes gateway run --replace

For always-on setups, compare the VPS hosting guide and Docker install guide. Local laptop gateways are easy to test but easy to break with sleep, PATH changes, or stale processes.

Step 3: verify platform credentials without leaking secrets#

Do not paste bot tokens into chat or logs. Instead, verify the platform response with a local command or built-in gateway status.

For Telegram, the high-level checks are:

• The bot token belongs to the bot you are messaging.
• Bot privacy settings match your group or topic expectations.
• The chat ID and thread ID are correct.
• The bot has permission to read and send in that group.
• telegram.require_mention, allowlists, and free-response topics are set intentionally.

For Discord, the high-level checks are:

• The bot was invited to the right server.
• Required intents are enabled.
• Channel permissions allow read and send.
• Thread access is not blocked by server rules.
• The Hermes profile running the gateway has the Discord token.

If you are still setting up, use Telegram setup or Discord setup instead of starting from this troubleshooting page.

Step 4: debug topic and thread routing#

Forum topics and Discord threads add a routing layer. A group-level send test does not prove topic-level delivery.

For Telegram forum topics, confirm:

• chat_id points to the supergroup.
• message_thread_id points to the topic.
• the topic is not closed or hidden from the bot.
• require-mention and free-response settings match the intended behavior.
• the gateway logs show the inbound update for that topic.

For Discord threads, confirm:

• the bot can see the parent channel.
• the bot has access to the thread.
• the bot can read message content if normal text triggers are expected.
• slash commands and ordinary messages are not being confused.

If the logs do not show the inbound message at all, the problem is platform delivery or permissions. If logs show the message but Hermes skips it, the problem is gating or routing config.

Step 5: separate provider failures from gateway failures#

A bot that receives messages but never replies may be hitting provider errors. Common causes include:

• exhausted credits,
• model rate limits,
• auxiliary model failures during compression or memory work,
• a stale provider configuration after a model switch,
• network timeouts from a self-hosted VPS.

Use the model provider costs and rate limits guide and provider fallbacks guide for this layer. Gateway uptime is not just process uptime; it also depends on the model stack being able to answer.

Step 6: read the right logs#

Depending on how the gateway was started, useful logs may live in different places. Check the Hermes logs directory and the platform adapter output before editing config.

Look for:

• startup lines that say the platform connected,
• duplicate polling or webhook conflicts,
• skipped messages due to gating,
• provider errors,
• send failures,
• restart or shutdown messages,
• stack traces after dependency updates.

If you recently updated Hermes, restarted a gateway, or changed tools, stale long-running processes can keep old code in memory. Restart the gateway process, not just the conversation session.

Step 7: use profiles as blast-radius control#

Profiles are the practical boundary for gateway debugging. A Telegram bot, Discord bot, and Claude Desktop MCP bridge do not need to share the same secrets or tool surface. Use the Hermes Agent profiles guide to isolate:

• production bot credentials,
• experimental MCP servers,
• personal memory,
• client or project tools,
• risky browser or shell permissions.

This also makes troubleshooting faster: if one profile breaks, you know which config, .env, sessions, and gateway process to inspect.

When to stop self-hosting the gateway#

Self-hosted gateways are worth it when you want full control and enjoy operating the stack. They are less attractive when the business value is simply “message my agent reliably from my phone.”

Move to a managed path when:

• missed replies cost more than the hosting bill,
• provider credits and rate limits keep interrupting work,
• Docker, launchd, or VPS restarts become routine chores,
• the team needs shared uptime rather than one laptop process,
• you want Telegram or Discord access without owning every operational edge case.

For that decision, compare self-hosting, VPS hosting, and FlyHermes pricing.