网关问题

Hermes Agent 通过消息网关连接到 Telegram、Discord、微信、飞书等平台。当 Bot 无法响应或连接异常时，本页帮助你快速定位和解决问题。

Bot 无法响应消息

症状： 用户发送消息后 Bot 没有任何回复。

排查步骤：

# 1. 确认 Hermes Agent 主进程正在运行
ps aux | grep hermes    # Linux / macOS
# 或
docker ps               # Docker 部署

# 2. 检查日志中的错误信息
hermes logs --tail 50
# Docker:
docker logs hermes-agent --tail 50

# 3. 确认网关配置正确
hermes doctor

# 4. 测试 LLM 连接是否正常
hermes chat -q "hello"

常见原因与修复

原因	修复方法
主进程未启动	`hermes chat --platform telegram`
API Key 无效	`hermes model` 重新配置
Bot Token 错误	检查网关配置中的 Token
网络不通	检查代理设置和防火墙

连接断开或频繁掉线

症状： Bot 运行一段时间后停止响应，日志显示连接断开。

解决方案：

# 1. 检查网络稳定性
ping api.telegram.org
ping gateway.discord.gg

# 2. 启用自动重连

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

# 3. 使用 systemd 或 Docker 自动重启
# systemd:
[Service]
Restart=always
RestartSec=10

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

Telegram Bot 问题

Bot Token 无效

# 验证 Token 是否有效
curl https://api.telegram.org/bot<YOUR_TOKEN>/getMe

# 返回 {"ok":true,...} 说明 Token 有效
# 返回 {"ok":false,"error_code":401} 说明 Token 无效

Webhook 与 Long Polling

# 如果使用 Webhook 模式，确保：
# 1. 服务器有公网可访问的 HTTPS 地址
# 2. SSL 证书有效
# 3. 防火墙放行了对应端口

# 推荐使用 Long Polling 模式（无需公网地址）：

gateway:
  telegram:
    mode: polling    # 使用 Long Polling

国内访问 Telegram

# Telegram API 在中国大陆需要代理
export HTTPS_PROXY=http://127.0.0.1:7890

# 或在配置文件中指定代理

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

Discord Bot 问题

Bot 权限不足

确保在 Discord Developer Portal 中为 Bot 授予了必要的权限：

Send Messages — 发送消息
Read Message History — 读取消息历史
Add Reactions — 添加表情反应
Attach Files — 发送文件

Bot 不在线

# 1. 确认网关已启动
hermes chat --platform discord

# 2. 检查 Discord Bot Token 是否正确
# 3. 确认 Bot 已被邀请到目标服务器
# 4. 检查 Intents 是否已开启

在 Discord Developer Portal 中启用 Message Content Intent（消息内容意图），否则 Bot 无法读取消息内容。

微信接入问题

扫码登录失败

# 微信通过 wechaty 协议接入，需要确认：
# 1. wechaty 服务正在运行
# 2. 使用的是支持的 puppet（如 wechat4u、padlocal）
# 3. 扫码超时时重新尝试

消息延迟

微信协议的限制可能导致消息延迟，这是正常现象。如果延迟超过 30 秒：

# 1. 检查 wechaty 服务状态
# 2. 重启 wechaty 服务
# 3. 考虑使用企业微信（更稳定）

飞书接入问题

应用审核未通过

确保飞书应用已通过审核并获得了以下权限：

im:message — 发送消息
im:message.receive_v1 — 接收消息
im:resource — 资源管理

事件回调配置错误

# 确认飞书应用的回调地址配置正确
gateway:
  feishu:
    app_id: cli_xxxxx
    app_secret: xxxxx
    verification_token: xxxxx
    encrypt_key: xxxxx

用户授权问题

症状： 非管理员用户无法与 Bot 交互，或被拒绝访问。

原因： Hermes Agent 的用户授权机制未正确配置。