Hermes Agent Gateway Troubleshooting: Telegram or Discord Bot Not Replying

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.

Recent Hermes community support threads (May 2026) surfaced two specific gateway failure patterns worth knowing about: Discord bots stopping silently after a gateway drain or restart without recovering (AttributeError: 'DiscordAdapter' object has no attribute 'message_len_fn'), and gateway restarts that say the service is running while the agent loop is still stale from a prior shutdown timeout. Both look like bot failures but are really gateway process state problems.

The latest query/page data also shows separate Discord and Telegram setup pages already ranking for setup intent, so this page owns the narrower problem query: a Hermes gateway, Telegram bot, or Discord bot that should answer but does not. Setup guides explain creation; this troubleshooting guide explains recovery.

Fast triage flow#

Use this order before rotating tokens or rebuilding the bot:

1. Prove the core agent works: run hermes doctor and hermes chat -q "reply ok" from the same machine/profile.
2. Check the long-running gateway: run hermes gateway status, inspect ~/.hermes/logs/agent.log, and restart the service if code/config changed.
3. Verify the active profile: tokens, allowed chats, topic IDs, skills, and tools must live in the profile that the gateway actually runs. The Hermes Web UI dashboard is useful here because it shows profile/config state visually, while its local browser Chat tab can prove the backend TUI works without proving Telegram or Discord delivery.
4. Test the real channel: send a real Telegram or Discord message in the exact DM, group, forum topic, thread, or channel. A generic API getMe check does not prove topic routing.
5. Only then rotate secrets: if the bot still fails, check platform permissions, privacy settings, duplicate polling, provider credits/rate limits, and allowlist rules.

If Telegram or Discord is not replying, do this first#

Do not rotate tokens or rebuild the container first. Most “Hermes bot not replying” incidents are one of six things: the base CLI is unhealthy, the gateway process is stale, the active profile is not the profile you edited, the chat/topic is gated, the provider is out of credits, or the platform adapter never received the message.

Run the checks in this order:

hermes doctor
hermes chat -q "reply with ok"
hermes gateway status
tail -120 ~/.hermes/logs/agent.log

Then test the exact platform path. For Telegram, confirm BotFather token, privacy mode, allowed_chats, forum topic IDs, and require_mention behavior. For Discord, confirm bot intents, channel permissions, thread access, allowed guild/channel settings, and whether the bot can see the message at all.

Use the Hermes Dashboard / Web UI as a status checkpoint, but finish with a real end-to-end message in the target chat. Connected is not the same as replying.

Telegram bot not replying: checks that matter#

If the symptom is “my Hermes Telegram bot is connected but not replying,” do not stop at BotFather or getMe. Those only prove the token exists. Check the full Telegram path:

1. Token and active profile: confirm the token is in the .env for the profile used by the running gateway, not another Hermes profile. Use Hermes profiles when one bot should be isolated from another.
2. Allowed chats and mention rules: verify telegram.allowed_chats, telegram.require_mention, group privacy, and whether the topic is configured as a free-response thread.
3. Forum topics: a private t.me/c/... link contains the supergroup and message ID, not necessarily the message_thread_id. Test the exact topic, not only the parent group.
4. Duplicate polling or webhook state: one bot token cannot be polled by two running gateway processes at once. Check getWebhookInfo, process lists, and gateway logs before rotating tokens.
5. Provider and auxiliary failures: if the bot receives the update but never answers, inspect provider credits and fallback settings with the provider cost guide and provider fallback guide.
6. End-to-end proof: send one real message in the exact DM, group, or forum topic after restarting the gateway.

For initial setup rather than incident recovery, use the Telegram setup guide or the Telegram integration overview.

Discord agent not working: checks that matter#

If Hermes works in the CLI but not in Discord, the likely failure is platform-side routing or the long-running gateway process, not the core agent. Check:

• Bot token and intents: the bot needs the right Discord developer-portal intents for the events you expect.
• Server and channel permissions: verify the bot can read messages, create or read threads, and send replies in the target channel.
• Thread behavior: support channels often use threads; test the exact thread/channel rather than only the guild.
• Allowed guild/channel rules: make sure Hermes is not ignoring the message due to allowlists, mention gating, or channel prompts.
• Gateway logs: current activity is often in ~/.hermes/logs/agent.log, while gateway.log can be stale depending on how the service was launched.

For first-time Discord setup, pair this incident checklist with the Discord setup guide, the Discord integration page, and the Hermes Dashboard / Web UI as a visual status checkpoint.

macOS, launchd, Docker, and stale gateway processes#

On macOS and VPS installs, “gateway connected but no reply” often means the service is stale, started with a reduced PATH, or still running old Python modules after an update. Use this recovery ladder before deleting config:

PATH="$HOME/.local/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:$PATH" hermes gateway status
PATH="$HOME/.local/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:$PATH" hermes gateway restart
tail -160 ~/.hermes/logs/agent.log

If launchd claims the service is running but Telegram or Discord still says nothing, hard-restart the service and verify the actual process. If Docker is involved, confirm the container sees the same ~/.hermes volume, .env, workdir, and provider keys as the CLI smoke test. The install/update troubleshooting guide, Docker setup guide, VPS deployment guide, and server security checklist cover the surrounding infrastructure.

What counts as fixed#

A gateway is not fixed because the dashboard loaded, the service says “running,” or Telegram getMe returned a username. Count the incident as fixed only when all four checks pass:

1. hermes doctor passes in the same profile or service environment.
2. hermes chat -q "reply ok" works from the same machine.
3. hermes gateway status and recent logs show the active platform connected without current errors.
4. A real Telegram topic or Discord channel/thread receives a reply from Hermes.

If the business requirement is always-on phone access and you do not want to maintain launchd/systemd, Docker, provider keys, gateway restarts, and platform permissions, compare self-hosted vs hosted AI agents and the managed FlyHermes pricing path.

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.

If you are building the gateway to run all day rather than debugging a one-off reply, use the 24/7 AI agent setup checklist to verify the runtime, provider lane, dashboard, messaging channel, and cron delivery as one system.

When the dashboard says connected but the bot is silent#

A dashboard or status screen can prove that a process started; it does not prove that a user message can travel all the way through Telegram or Discord, Hermes, the model provider, tools, and back to the same thread. Treat Hermes Web UI as the visual checkpoint, then run a transport test.

Use this order before rotating tokens:

hermes doctor
hermes chat -q "reply ok"
hermes gateway status
tail -120 ~/.hermes/logs/agent.log
tail -120 ~/.hermes/logs/errors.log

Then send one real message in the exact destination: Telegram DM, Telegram forum topic, Discord channel, Discord thread, or cron delivery target. If the bot only fails in one topic/thread, keep the provider and base gateway alone and inspect chat IDs, message_thread_id, Discord intents, app mention rules, allowed chats/channels, and profile-specific config.

This is why the dashboard page and gateway troubleshooting page now cross-link: dashboard searches have strong GSC volume, while community support threads show the actual failure is often profile drift, stale long-running gateway code, provider limits, or topic/thread routing rather than “the dashboard is broken.”