Hermes Agent Gateway Troubleshooting: Fix a Bot That Is Not Replying

A Hermes Agent gateway can look healthy while Telegram, Discord, or another channel stays silent. “Connected” only proves that the platform adapter started. It does not prove that the message passed the allowlist, reached the right profile, completed a model turn, and returned to the same chat or thread.

The five-minute gateway triage#

Run these commands from a normal terminal on the machine that hosts the gateway:

hermes doctor
hermes chat -q "reply with gateway-smoke-test"
hermes gateway status
hermes status --all
tail -160 ~/.hermes/logs/agent.log
tail -160 ~/.hermes/logs/errors.log

For a named profile, add -p <profile> to the Hermes commands:

hermes -p support-bot chat -q "reply with ok"
hermes -p support-bot gateway status

Use the Hermes Dashboard and Web UI to inspect profiles, sessions, providers, cron jobs, and gateway state, but do not treat a green dashboard as end-to-end proof. hermes dashboard is the backend plus browser UI; hermes serve is the headless remote-Desktop backend; neither replaces the messaging gateway. Finish with one real message in the exact destination that failed.

Diagnose the symptom before changing anything#

The bot is online but never receives the message#

This is usually a platform or gating failure:

• the human sender, group, guild, or channel is not allowed;
• Telegram privacy or mention rules suppress the message;
• the Discord bot lacks message-content intent or channel/thread access;
• the message was sent to a forum topic or thread that is not configured;
• a network or proxy problem prevents the adapter from reaching the platform API.

Look for the inbound message in ~/.hermes/logs/agent.log. If no matching update appears, changing the model will not help.

The inbound message appears, but no agent turn starts#

Inspect allowlists, mention gating, topic/thread routing, and the active profile. The token may be valid while the human sender is still unauthorized. The Telegram setup guide explains user IDs, chat IDs, and forum topics; the Discord setup guide covers intents, permissions, and threads.

The agent turn starts, then fails#

Search the logs for provider errors, exhausted credits, timeouts, compression failures, or tool exceptions. A connected gateway can still fail every reply because the selected provider or auxiliary model cannot complete the turn. Test the same profile with hermes chat -q and use the provider fallback guide if the failure follows the model route.

The bot replies twice#

Assume duplicate gateway processes before blaming Discord or Telegram. A recent community case had both the current launchd service and a stale legacy profile service handling every Discord message. Check the deep status and process list:

hermes gateway status --deep --full
ps -axo pid,ppid,lstart,command | grep -E '[h]ermes.*gateway|[p]ython.*gateway'

On macOS, also inspect loaded Hermes launchd jobs:

launchctl list | grep -i hermes

Restart all managed gateway processes from a normal terminal:

hermes gateway restart --all

If a stale legacy launchd job immediately respawns, unload that specific legacy service instead of repeatedly restarting the current one. Do not kill processes blindly until you have identified which profile and service each PID belongs to.

The service says running, but every channel is silent#

A supervisor can be alive while the agent loop is stale, the child process is crash-looping, or an old process still has pre-update code in memory. Restart the gateway service—not only the chat session—and inspect fresh log timestamps:

hermes gateway restart
hermes gateway status --deep --full
tail -160 ~/.hermes/logs/agent.log

Use hermes gateway run --replace for a foreground recovery when you need to replace a stale process and watch startup output directly. Keep that terminal open while testing.

Telegram bot connected but not replying#

Telegram has separate identity and routing layers. Verify each one.

1. Distinguish the bot ID from the human user ID#

The numeric prefix in a bot token identifies the bot. It is not your personal Telegram user ID. If logs say blocked unauthorized user, use the human sender ID in the effective allowlist. Current configuration supports sender and group scopes such as allow_from, group_allow_from, and group_allowed_chats.

Do not print or paste the bot token while debugging. Use /whoami or the gateway's pairing/authorization flow where appropriate, then restart the correct profile's gateway after changing configuration.

2. Test the exact destination#

A parent-group test does not prove a forum topic works. Verify:

• the supergroup chat_id;
• the topic's message_thread_id;
• require_mention behavior;
• free-response topic or chat settings;
• group sender/chat allowlists;
• that the bot can read and send in that topic.

A private t.me/c/... link contains a group and message reference, not enough information by itself to prove the thread ID. Use current logs or the channel directory to confirm the actual routing values.

3. Check for network-specific Telegram failures#

If several Telegram bots fail while Discord and internal cron jobs keep working, test access to api.telegram.org from the gateway host. A July 2026 community incident traced silent Telegram bots to a network path that timed out against Telegram's API. Hermes supports an HTTP, HTTPS, or SOCKS5 Telegram proxy:

hermes config set telegram.proxy_url socks5://127.0.0.1:1080
hermes gateway restart

You can also use TELEGRAM_PROXY in the correct profile environment. A proxy is a network workaround, not a fix for wrong user IDs or topic routing.

For a complete first-time setup, use Connect Telegram to Hermes Agent. For incident recovery, keep following this page.

Discord bot online but not responding#

Discord's online indicator is not proof that Hermes can read and answer in the target location. Check:

• Intents: enable the intents required for ordinary message handling.
• Permissions: verify read, send, message-history, and thread permissions in the target channel.
• Allowlist policy: confirm the human user, role, or channel is authorized.
• Mention rules: test both an explicit mention and the intended free-response path.
• Threads: verify access to the parent channel and the exact active thread.
• Duplicate processes: two gateways can generate two different replies to one message.

If the CLI works and the logs show no inbound Discord message, stay on Discord permissions, intents, or channel gating. If the inbound message appears and the model turn fails, move to provider or tool diagnostics.

The Discord integration page explains the product boundary; Connect Hermes Agent to Discord covers first-time configuration.

Profile drift: the gateway is running the wrong configuration#

Hermes profiles isolate config, .env, sessions, memory, skills, and gateway services. That isolation is useful, but it creates a common failure mode: you fix the default profile while the production bot runs under another profile.

Check the profile explicitly:

hermes profile list
hermes -p support-bot config path
hermes -p support-bot config env-path
hermes -p support-bot gateway status

Desktop remote-gateway settings can also be scoped. A community case showed new Desktop profiles inheriting a local gateway because the remote URL was saved only for one named profile rather than “All profiles.” Verify which host each profile targets before changing remote files.

Read the Hermes Agent profiles guide before sharing one bot, secret set, or memory boundary across unrelated projects.

Remote gateway and Desktop problems#

Hermes Desktop, the self-hosted Dashboard, the optional OpenAI-compatible API server, and messaging gateways are adjacent but separate surfaces:

• Desktop Remote Gateway and the Dashboard use the dashboard backend, normally on port 9119.
• The optional OpenAI-compatible API server normally uses port 8642.
• Telegram, Discord, Slack, and other adapters run through profile-specific gateway services.

A working Desktop connection proves the control plane is reachable. It does not prove that Telegram or Discord can receive and send in a target thread. Conversely, a port collision on 8642 can crash a profile's child process while the supervisor remains visible.

For remote setups, use the Desktop remote backend guide and keep the Dashboard private behind localhost, SSH, Tailscale, or an authenticated HTTPS reverse proxy.

Restart safely on macOS, Linux, and Docker#

macOS launchd#

Use the Hermes service commands first:

hermes gateway restart
hermes gateway status --deep --full

If a reduced service PATH prevents standard binaries from resolving, retry with an explicit macOS path:

PATH="$HOME/.local/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:$PATH" hermes gateway status --deep --full

Do not trust launchd state alone; test a real channel message after recovery.

Linux systemd#

For a user service, inspect both Hermes and systemd:

hermes gateway status
systemctl --user status hermes-gateway
journalctl --user -u hermes-gateway -n 160 --no-pager

Run a restart from SSH or a normal shell outside the gateway process. A gateway cannot safely replace itself from inside the active agent turn in every environment.

Docker and s6#

Confirm that the CLI test and gateway use the same mounted HERMES_HOME, profile, .env, and provider credentials. Current official container supervision keeps per-profile gateway state and logs; a container can restart while preserving the intended running/stopped state. Inspect the Hermes Docker troubleshooting guide before rebuilding volumes or deleting state.

Use logs as a timeline, not a keyword dump#

Read log timestamps around one controlled test message. Look for this sequence:

1. platform connected;
2. inbound message received;
3. authorization/gating decision;
4. agent turn started;
5. provider/model response or error;
6. outbound send success or failure.

Current gateway activity is commonly visible in ~/.hermes/logs/agent.log; gateway.log can be stale depending on how the service was launched. If support needs a reproducible bundle, create a redacted debug report:

hermes debug share --lines 500

Review the report before sharing it. Never paste raw .env files, bot tokens, provider keys, or private conversation content into a public issue.

What counts as fixed#

Do not close the incident because the Dashboard loads or the adapter says connected. Require all of these:

• hermes doctor passes under the gateway profile;
• hermes chat -q "reply with ok" completes under that profile;
• hermes gateway status --deep --full shows the intended service and profile;
• fresh logs show the controlled inbound test;
• the exact Telegram DM/topic or Discord channel/thread receives one reply;
• no duplicate process produces a second reply;
• the next restart or host reboot preserves the healthy state.

When managed hosting is the better answer#

Self-hosting is the right choice when you want full control over files, models, tools, and network boundaries. It is still an operations commitment: provider credits, bot permissions, Docker or systemd, updates, logs, backups, remote access, and incident recovery remain yours.

If the real requirement is “reach my agent reliably from a browser or phone” rather than “operate an agent server,” compare self-hosted versus hosted Hermes and the managed FlyHermes path. FlyHermes is the hosted browser/mobile/channel experience; the self-hosted Dashboard remains the configuration and monitoring surface.

Prove delivery while the client is closed#

A connected gateway status is not proof of an always-on workflow. Send one real message to the exact chat or topic, schedule one harmless follow-up, close Desktop, and verify the runtime delivers without manual intervention. If the agent lives on a laptop, sleep ends the test; the self-hosted vs hosted guide explains the always-on ownership boundary.

If the gateway is spending on the wrong model#

Treat unexpected provider spend as an incident, not as a normal “bot not replying” retry loop. Restrict the affected channel or pause its scheduled work, capture the active profile/provider/model and usage window, then inspect gateway logs and config history before reauthenticating. Restart the owning gateway only after restoring the intended route, and verify one real message plus provider usage. The provider cost and rate-limit guide has the full stop, preserve, cap, and re-enable sequence.