Hermes + Telegram 配置与使用

📋 前置条件

Telegram 账号（手机号注册即可）
能访问 Telegram API 的网络环境
Hermes Agent 已安装且能正常运行

🔑 Telegram 配置所需参数

配置 Hermes 连接 Telegram 只需少数几个值：

#	配置项	.env 变量 / 用途	获取方式	必填
①	Bot Token	`TELEGRAM_BOT_TOKEN`	私聊 @BotFather → `/newbot` → 按提示创建 → 获得 token	✅
②	你的 User ID	`TELEGRAM_CHAT_ID`	私聊 @userinfobot → 返回的数字 ID	✅ DM
③	Group Chat ID	`cron deliver target` `send_message`	仅 Cron 定时推送 / 主动发消息时需要，详见下方说明	🔶 仅推送
④	API ID / Hash	`TELEGRAM_API_ID` `TELEGRAM_API_HASH`	访问 my.telegram.org/apps → 登录 → 创建应用	❌ 可选

📖 详细获取步骤

① Bot Token — @BotFather 创建机器人

打开 Telegram，搜索并私聊 @BotFather
发送 /newbot → 按提示设置 Bot 名称（如 Hermes Bot）和用户名（如 hermes_bot）
创建成功后 BotFather 会返回一条消息：

Use this token to access the HTTP API:
1234567890:ABCdefGHIjklMNOpqrsTUVwxyz
将冒号后的 token 复制到 TELEGRAM_BOT_TOKEN

💡 后续可随时用 /token 查看当前 token，用 /revoke 重新生成

② User ID — @userinfobot

搜索并私聊 @userinfobot
它自动返回你的 Telegram User ID（纯数字，如 123456789）
复制到 TELEGRAM_CHAT_ID

③ Group Chat ID — ⚠️ 仅 Cron 主动推送时需要

如果你只用 Group + Topics 做 @bot 交互 Session 隔离，你完全不需要这个值。
Hermes 会自动感知你在哪个群哪个 Topic 发的消息，自动回复到正确位置。

这个 ID 只有在以下场景才用得到：

Cron 定时任务主动推送到指定 Topic — 如每天早上日报自动投递到 #日报 Topic
Hermes 主动向某个群/Topic 发消息 — 不经过用户触发，由脚本或事件驱动
send_message 指定目标 — target: "telegram:-100chat_id:topic_id"

获取方式（以后需要时再查）：

在群里的目标 Topic 中发一条消息 @bot 触发 Hermes
查看 Hermes 日志：grep chat_id ~/.hermes/logs/gateway.log
日志中会打印类似 chat_id=-1001234567890, topic_id=17585 的信息
组合成 telegram:-1001234567890:17585 用于 cron deliver

💡 也可用 @getidsbot 获取群组 ID（带负号 -）

④ API ID / Hash（可选）

仅在使用某些高级功能时需要，基本的 Bot 模式不需要。

🏗️ 架构示意图

用户层	Telegram 平台	Hermes 服务端
👤 私聊 (DM) 直接给 Bot 发消息会话保持，随聊随回	🤖 Telegram Bot API `api.telegram.org` 消息收发 / 命令解析 🔄 Long Polling Hermes 主动轮询更新 🔗 Webhook 可选（需公网地址）	📬 Telegram Adapter 消息接收 / 发送 / 去重 ↓ 🚪 Gateway Core 消息路由 / Session 管理 ↓ 🧠 Hermes Agent Core LLM + Tools + Skills + Cron ↓ 回复消息 → 发回 Telegram
👥 群聊 (Group + Topics) @Bot 提及触发 / 命令触发 Topic 隔离多任务上下文
⏰ 定时任务 (Cron) 自动推送结果到指定 Topic 日报 / 预警 / 数据看板

消息交互链路

用户入口 — 在 Telegram 中私聊 Bot、群聊 @提及、或通过定时 Cron 触发
Bot API — Hermes 通过 Long Polling 轮询 Telegram 服务器获取新消息（或可选 Webhook）
Telegram Adapter — 负责消息接收解析、去重、命令识别
Gateway Core — 路由消息到正确的 Session，管理 Topic 隔离和上下文
Agent Core — LLM 处理 + Tools 执行 + Skills 调用，生成回复
回复路径 — 回复走反向路径发回 Telegram

⚠️ 镜像升级重启后 Telegram 找不到依赖：容器内触发懒加载
python3 -c "from tools.lazy_deps import ensure; ensure('platform.telegram', prompt=False)"

🔄 Telegram 使用生命周期

📌 阶段一：创建与配置

通过 @BotFather 创建 Bot，拿到 Token
将 Token 配置到 Hermes 的 ~/.hermes/.env
启动 Gateway：hermes gateway run
验证：私聊 Bot → 发送 /help → 查看 Hermes 是否回复

📌 阶段二：私聊（Bot 模式）

在 Telegram 中搜索创建好的 Bot（如 @hermes_bot）
进入对话，直接发送消息，Hermes 实时回复
每条消息是同一个 Session，上下文连续
用 /new 重置 Session，/model 切换模型

💡 适用：个人助手、快速问答、文件分析

📌 阶段三：群聊（Group + Topics 模式）

创建 Telegram 群组 → 设置 → 开启 Topics
将 Bot 加入群组并设为管理员
1. 如果是先加bot为管理员，再开启topics，则需要重新加一次bot为管理员
@提及触达：在任意 Topic 中 @Bot + 消息 → 仅该 Topic 响应该上下文
Topic 即 Session：每个 Topic 是独立的 Hermes 会话，上下文不交叉
/new 只重置当前 Topic 的会话，不影响其他 Topic

📌 阶段四：定时任务（Cron / 看板模式）

Cron 定时推送结果到指定 Topic（deliver: "telegram:-100xxx:topic_id"）
Hermes 自动分析、生成内容并投递
Topic 内保留历史推送记录，形成数据看板

📌 阶段五：管理维护

Token 轮换 — 私聊 @BotFather 用 /revoke 重新生成，更新 .env 后重启 Gateway
Bot 权限 — 群聊中 Bot 需要「管理员」权限才能读取所有消息和 Topic
Session 清理 — 用 /new 重置，日志中自动清理过期上下文
/platforms — 查看 Telegram 连接状态

💡 最佳实践与技巧

Topic = 项目看板 — 每个项目一个 Topic，所有讨论、决策、输出沉淀在内，形成可回溯的项目日志
Topic = Agent 调试台 — 用 #debug Topic 专门测试新能力，不干扰主线
Topic = 知识沉淀 — 完成调研后 @bot 总结 → 保存到 Trilium，Topic 本身保留原始讨论过程
跨 Topic 转移上下文 — 在 #调研 Topic 完成后 @bot「把刚才的结论总结到 #日报 Topic」

要点速查

确保 Telegram Group 启用 Topics — Group 设置 → Topics → 开启 → Hermes 自动感知 topic_id
send_message 支持精确定位 — telegram:-100chat_id:thread_id 格式
Session 隔离 — 每个 Topic 独立 Session，/new 只重置当前 Topic
Cron deliver — 可指定目标 Topic，实现数据看板