将 Hermes Agent 接入 Telegram
运行 Hermes Agent 网关，在任意设备上访问你的 AI。发送语音备忘录、接收任务结果、在群聊中使用——全部通过你自己的 Telegram Bot。
你能做什么
Hermes Agent 网关将本地 Agent 连接到 Telegram——支持的所有功能，一个入口全搞定。
随时随地对话
Hermes Agent 运行在你的机器上，Telegram Bot 只是接口——手机、桌面、网页，任意有 Telegram 的地方都能用。
语音备忘录
在 Telegram 发送语音消息，Hermes 自动转写并以文字回复（如果配置了 TTS，也可以语音回复）。
定时任务推送
设置一个主频道，Hermes 会将定时任务结果、提醒和 Agent 触发的通知直接推送到该对话。
群聊支持
将 Bot 加入群组，控制哪些用户可以触发它、是响应所有消息还是只响应 @ 提及，并为不同话题绑定不同技能。
开始之前
运行配置向导前，请确认以下三项已准备就绪。
- ✓Hermes 已安装并正常运行→ /install
- ✓已配置可用的 LLM→ /models
- ✓拥有 Telegram 账号
Bot 不回复最常见的原因不是 Bot 本身——而是模型。
Telegram 只是消息通道。如果 LLM 提供商未配置或 API Key 已过期，Bot 会收到你的消息，然后彻底沉默——没有报错，没有回复。继续配置前，先运行 hermes model 确认当前设置是否正常。
配置步骤
通过 BotFather 创建 Bot
所有 Telegram Bot 都从这里开始。BotFather 是 Telegram 官方的 Bot 管理账号，负责签发将 Hermes 与你的 Bot 连接起来的 API Token。
- 打开 Telegram，向 @BotFather 发消息
- 发送 /newbot
- 输入显示名称（例如 Hermes Agent）——所有打开该 Bot 的人都能看到
- 输入用户名——必须唯一且以 bot 结尾（例如 my_hermes_bot）
- BotFather 会回复你的 Token：
保存好这个 Token，第 3 步会用到。
获取你的 Telegram 用户 ID
Hermes 使用数字用户 ID（而非用户名）来控制谁可以与你的 Bot 交互。你的用户 ID 是一串类似 123456789 的数字。
向 @userinfobot 发消息，它会立即回复你的 ID。复制下来。
配置 Hermes
运行交互式配置向导，它会询问 Bot Token 和用户 ID，然后自动写入配置文件。
出现提示后选择 Telegram，填入第 1 步的 Token 和第 2 步的用户 ID。
手动配置（进阶）
如果不想使用交互向导，可以直接编辑 ~/.hermes/.env：
启动网关
Bot 会在几秒内上线，你应该看到：
在 Telegram 给你的 Bot 发一条消息验证一下。收到回复就说明配置成功了。
要在群聊中使用 Hermes？请先读这条。
Telegram Bot 默认开启隐私模式。开启后，Bot 只能看到以 / 开头或直接回复它的消息——其他消息一概忽略。
解决方法：进入 BotFather → /mybots → 选择你的 Bot → Bot Settings → Group Privacy → Turn off。
重要： 关键：修改该设置后，必须将 Bot 从群组中移除再重新添加。Telegram 在 Bot 加入群组时会缓存隐私状态——重新加入才会生效。
另一个方法：将 Bot 提升为群管理员。管理员 Bot 始终能收到所有消息，不受隐私设置影响。
验证配置
向 Bot 发送以下消息，确认各层功能正常：
| 发送的消息 | 预期结果 |
|---|---|
Hello | Agent 以文字回复 |
| 一条语音消息 | Agent 转写并回复 |
/model | 显示当前模型 + 交互式选择器 |
/sethome | 将当前对话设置为定时任务推送的主频道 |
如果发送 Hello 没有回复，请查看下方常见问题。
常见问题
Bot 收到消息但从不回复
原因 A — 模型未配置或 API Key 已过期
这是最常见的原因。Telegram 将消息传递给了 Hermes，但因为 LLM 不可用，Hermes 无法生成回复。
如果 API Key 额度耗尽或已过期，失败是完全静默的——Telegram 侧没有任何报错或日志。请直接登录提供商后台检查。OpenRouter、OpenAI、Anthropic 等所有提供商均如此。
原因 B — Bot Token 错误
确认 Token 与 BotFather 签发的一致。如果不小心重新生成了 Token，更新 .env 文件并重启网关。
给 Bot 发消息时提示 unauthorized（未授权）
你的 Telegram 用户 ID 不在 TELEGRAM_ALLOWED_USERS 列表中。
确认数字用户 ID 已填入列表。如有需要，重新向 @userinfobot 获取。编辑 .env 后重启网关。
Bot 在私信中正常，但忽略群聊消息
隐私模式已开启。简短版本：
BotFather → /mybots → 你的 Bot → Bot Settings → Group Privacy → Turn off → 将 Bot 移出群组 → 重新添加。
完整说明见第 4 步中的警告框。
语音消息没有被转写
Hermes 需要配置语音识别提供商。默认本地方案使用 faster-whisper：
也可以在 ~/.hermes/.env 中配置云端提供商：
语音回复以音频文件形式出现，而不是语音气泡
这是 Edge TTS（默认免费 TTS 提供商）的行为，它输出 MP3 格式，Telegram 需要先用 ffmpeg 将其转换为 Opus 才能显示为语音气泡。
没有 ffmpeg 时音频仍然会正常发送——只是显示为矩形播放器而非圆形语音气泡。
部署到云服务器——需要开启 Webhook 模式吗？
是的，云端部署需要。默认的轮询模式会持续保持一条出站连接，导致机器无法休眠。Webhook 模式让 Telegram 主动推送更新到你的服务器，机器在消息间隔期间可以休眠。
Fly.io 完整部署说明请参阅 官方文档 ↗.
高级配置
面向进阶用户的可选配置项，按需阅读即可。
群聊 @ 触发控制
默认情况下，Hermes 会响应它能看到的群聊里所有消息。如果只想响应直接 @ 提及和命令：
启用此配置后，Bot 将响应 /命令、@botusername 提及、直接回复，以及任何匹配你的自定义规则的消息。
私聊话题（Private Chat Topics）
Bot API 9.4 允许 Bot 在 1 对 1 私聊中创建论坛式话题线程，每个话题拥有独立的会话、历史记录和上下文。
Hermes 会在启动时自动创建话题，并将 thread_id 写回配置文件。
消息表情反应
启用表情反应作为处理状态的反馈——思考中、成功、出错时分别显示对应表情：
也可以通过环境变量启用：TELEGRAM_REACTIONS=true
受限网络 / 代理
如果你的网络无法访问 api.telegram.org，Hermes 会自动尝试 DNS-over-HTTPS 备用 IP。如果需要显式代理：
无需额外配置——网关会自动读取标准的代理环境变量。
本指南介绍了 Hermes Agent Telegram 接入配置。同一个网关还支持 Discord、Slack、WhatsApp 和 Signal。Webhook 部署、群论坛话题技能绑定和完整配置参考，请查阅官方文档。