Hermes Agent 接入 Telegram Bot：私聊、群组与文件完整指南

使用 BotFather 创建机器人

在 Telegram 找到 @BotFather，发送 `/newbot`，设置显示名和以 `bot` 结尾的唯一用户名，保存生成的 Bot Token。

1. 1. 打开 https://t.me/BotFather。
2. 2. 发送 /newbot。
3. 3. 设置名称和 username。
4. 4. 复制 Token 并存入密码管理器。

任何拿到 Token 的人都能控制机器人。泄露后立即在 BotFather 使用 /revoke。

获取数字 User ID

Hermes allowlist 使用永久的数字 User ID，而不是可修改的 @username。可以给 @userinfobot 或 @get_id_bot 发消息查询。

# 示例：数字 ID
123456789

配置 Hermes Gateway

推荐用向导选择 Telegram，填入 Bot Token 和允许的数字用户 ID。

hermes gateway setup
# 或写入 ~/.hermes/.env
TELEGRAM_BOT_TOKEN=123456789:ABC...
TELEGRAM_ALLOWED_USERS=123456789,987654321
hermes gateway start
hermes gateway status

群聊 Privacy Mode

BotFather 默认启用 Privacy Mode，此时机器人只能收到命令、对机器人消息的回复和部分服务消息。若需要观察普通群消息，关闭 Privacy Mode 或将机器人设为管理员。

1. 1. BotFather → /mybots → 选择机器人。
2. 2. Bot Settings → Group Privacy → Turn off。
3. 3. 把机器人从已有群移除后重新加入，刷新缓存的隐私设置。

关闭 Privacy Mode 后仍应启用群 allowlist 和 require_mention，避免群内每条消息都触发模型调用。

群组安全配置

允许机器人观察群聊上下文但只在被 @ 时响应，需要同时允许目标 chat ID、启用 mention 门控，并确保 Telegram 会下发普通群消息。

TELEGRAM_ALLOWED_CHATS=-1001234567890
TELEGRAM_GROUP_ALLOWED_CHATS=-1001234567890
TELEGRAM_OBSERVE_UNMENTIONED_GROUP_MESSAGES=true

• 群组 Chat ID 通常以 -100 开头。
• 共享群默认应按用户隔离会话。
• 团队使用时逐个收集数字 User ID 加入 allowlist。

图片、语音与文件

Telegram 适配器支持文本、语音、图片和文件。使用 Docker terminal backend 时，Gateway 运行在宿主机，Agent 返回的 `MEDIA:` 路径必须能被宿主机读取。

容器内的 /workspace/report.txt 如果没有挂载到宿主机，Telegram 无法发送。请写入共享卷并返回宿主机可见路径。

长期运行与排错

使用服务管理器保持 Gateway 在线。无回复时按 Token、allowlist、Privacy Mode、Chat ID 和 Gateway 状态的顺序检查。

hermes gateway status
hermes gateway restart
hermes doctor

• 一个 Bot Token 不能同时被多个 Profile 的 Gateway 独占使用。
• 修改命令菜单或 Skills 后重启 Gateway。
• 定时任务可投递到 telegram:CHAT_ID 或具体 topic thread。