Gateway Issues

Hermes Agent connects to Telegram, Discord, WeChat, Feishu, and other platforms through message gateways. When the Bot fails to respond or has connection issues, this page helps you quickly locate and resolve the problem.

Bot Not Responding to Messages

Symptom: User sends message but Bot doesn’t reply.

Troubleshooting Steps:

# 1. Confirm Hermes Agent main process is running
ps aux | grep hermes    # Linux / macOS
# Or
docker ps               # Docker deployment

# 2. Check logs for error messages
hermes logs --tail 50
# Docker:
docker logs hermes-agent --tail 50

# 3. Confirm gateway configuration is correct
hermes doctor

# 4. Test if LLM connection is working
hermes chat -q "hello"

Common Causes and Fixes

Cause	Fix
Main process not started	hermes chat --platform telegram
API Key invalid	hermes model to reconfigure
Bot Token error	Check Token in gateway config
Network unreachable	Check proxy settings and firewall

Connection Drops or Frequent Disconnections

Symptom: Bot stops responding after running for a while, logs show connection dropped.

Solutions:

# 1. Check network stability
ping api.telegram.org
ping gateway.discord.gg

# 2. Enable auto-reconnect

~/.hermes/config.yaml

gateway:
  reconnect:
    enabled: true
    max_retries: 10
    retry_interval: 30    # seconds

# 3. Use systemd or Docker auto-restart
# systemd:
[Service]
Restart=always
RestartSec=10

# Docker:
docker compose up -d    # restart: unless-stopped

Tip

If using Docker deployment, ensure restart: unless-stopped is configured so the container automatically restarts on abnormal exit.

Telegram Bot Issues

Bot Token Invalid

# Verify Token is valid
curl https://api.telegram.org/bot<YOUR_TOKEN>/getMe

# Returns {"ok":true,...} means Token is valid
# Returns {"ok":false,"error_code":401} means Token is invalid

Webhook vs Long Polling

# If using Webhook mode, ensure:
# 1. Server has publicly accessible HTTPS address
# 2. SSL certificate is valid
# 3. Firewall allows the corresponding port

# Recommended: Use Long Polling mode (no public address needed):

gateway:
  telegram:
    mode: polling    # Use Long Polling

Accessing Telegram from China

# Telegram API requires proxy in mainland China
export HTTPS_PROXY=http://127.0.0.1:7890

# Or specify proxy in config file

gateway:
  telegram:
    proxy: http://127.0.0.1:7890

Discord Bot Issues

Bot Permission Insufficient

Ensure the Bot has necessary permissions in Discord Developer Portal:

• Send Messages — Send messages
• Read Message History — Read message history
• Add Reactions — Add emoji reactions
• Attach Files — Send files

Bot Offline

# 1. Confirm gateway is started
hermes chat --platform discord

# 2. Check Discord Bot Token is correct
# 3. Confirm Bot has been invited to target server
# 4. Check Intents are enabled

Enable Message Content Intent in Discord Developer Portal, otherwise the Bot cannot read message content.

WeChat Integration Issues

QR Code Login Failure

# WeChat connects via wechaty protocol, need to confirm:
# 1. wechaty service is running
# 2. Using supported puppet (like wechat4u, padlocal)
# 3. Retry if QR code times out

Message Delay

WeChat protocol limitations may cause message delays, which is normal. If delay exceeds 30 seconds:

# 1. Check wechaty service status
# 2. Restart wechaty service
# 3. Consider using WeCom (more stable)

Feishu Integration Issues

App Review Not Approved

Ensure Feishu app has passed review and obtained these permissions:

• im:message — Send messages
• im:message.receive_v1 — Receive messages
• im:resource — Resource management

Event Callback Configuration Error

# Confirm Feishu app callback address is configured correctly
gateway:
  feishu:
    app_id: cli_xxxxx
    app_secret: xxxxx
    verification_token: xxxxx
    encrypt_key: xxxxx

User Authorization Issues

Symptom: Non-admin users cannot interact with Bot, or access is denied.

Cause: Hermes Agent user authorization mechanism not configured correctly.

Solutions:

~/.hermes/config.yaml

gateway:
  auth:
    mode: allowlist     # allowlist or open
    allowed_users:
      - user_id_1
      - user_id_2
    admin_users:
      - admin_id        # Admins have all permissions

# View current authorization config
hermes config show | grep -A 10 auth

# Use open mode (anyone can use, use with caution!)
# gateway.auth.mode: open

Caution

Using open mode in public groups means anyone can use your API quota. Recommended to use allowlist mode and only add trusted users.

Multiple Gateways Running Simultaneously

Hermes Agent supports connecting to multiple messaging platforms simultaneously:

# Start Telegram and Discord at the same time
hermes chat --platform telegram --platform discord

# Or enable multiple gateways in config file

gateway:
  platforms:
    - telegram
    - discord
    - feishu

Note

Each gateway uses independent connections but shares the same Agent core and LLM configuration. Ensure sufficient API quota to handle requests from multiple platforms.

Logging and Debugging

# View detailed logs
hermes logs --level debug --tail 100

# Docker environment
docker logs hermes-agent --tail 100 -f

# Export logs to file
hermes logs --export hermes-debug.log

# Enable debug mode
hermes chat --platform telegram --debug

Related Pages

• Common Errors — Common runtime errors
• Model Issues — LLM connection issues
• Security Best Practices — Security hardening guide
• VPS Deployment — Production environment deployment