Telegram Bot 接入 Hermes Agent 教程

1. Telegram 接入流程

Telegram Bot 接入 Hermes Agent 的本质，是让 Telegram Gateway 持续接收用户消息，把平台消息转换成 Agent 标准输入，再把 Agent 响应发送回聊天窗口。

在 BotFather 创建 Bot，拿到 Bot Token。
在 Hermes Agent 配置中启用 Telegram Gateway。
选择 Long Polling 或 Webhook 作为消息接收方式。
配置 Agent 的模型、记忆、工具和 Prompt 边界。
部署为长期运行进程，并配置日志和重启策略。

建议：个人助手和小团队 Bot 优先使用 Long Polling。它不需要公网 HTTPS 地址，部署简单，也更适合先验证 Agent 工作流。

2. 使用 BotFather 创建机器人

在 Telegram 中搜索 BotFather，依次执行 /newbot、输入机器人名称和 username。创建完成后，BotFather 会返回形如 123456:ABC... 的 Token。

/newbot
My Hermes Agent
my_hermes_agent_bot

Token 相当于机器人的登录凭证，应该写入环境变量，而不是直接提交到代码仓库。调试时可以先放在本机 shell，生产部署时建议放进进程管理器或服务器环境变量。

export TELEGRAM_BOT_TOKEN="123456:replace_with_your_token"

3. Gateway 配置示例

Telegram Gateway 的配置通常包含启用状态、Token、消息模式、允许的用户或群组。不同项目的字段名可能略有差异，但核心配置思路一致。

gateways:
  telegram:
    enabled: true
    token: "${TELEGRAM_BOT_TOKEN}"
    mode: "polling"
    allowed_users:
      - 123456789
    allowed_chats:
      - -1001234567890

如果 Bot 面向公开群组，务必增加权限边界：限制群组 ID、限制危险工具、在系统 Prompt 中声明不能泄露密钥和内部文件。

接入时常用工具

配置 Gateway 时经常需要检查 JSON、YAML、Token 和时间戳，建议边配置边校验。

YAML 格式化整理 config.yaml 缩进和结构 JSON 格式化查看 Telegram Update 事件 JWT 解码器调试平台 Token 与载荷 AI 提示词编写机器人系统提示词

4. 群组消息与隐私模式

Telegram Bot 在群组里默认启用 Privacy Mode，只能看到命令和被提及的消息。如果你希望 Agent 能读取普通群消息，需要在 BotFather 中关闭隐私模式。

/mybots
选择 Bot
Bot Settings
Group Privacy
Turn off

注意：关闭隐私模式后，Bot 可能接收群内大量消息。建议只在可信群组使用，并在 Gateway 层过滤 allowed_chats，避免无关消息消耗模型额度。

5. 生产部署建议

生产环境需要保证 Gateway 进程持续运行。可以使用 systemd、Docker Compose 或进程管理器，并把日志、环境变量和重启策略明确下来。

[Service]
Environment=TELEGRAM_BOT_TOKEN=123456:replace
ExecStart=/usr/bin/hermes-agent --gateway telegram
Restart=always
RestartSec=5

场景	推荐模式	原因
个人助手	Long Polling	不需要公网地址，部署最简单
小团队群组	Long Polling + 群组白名单	控制风险和模型费用
高并发公开服务	Webhook	延迟更低，便于水平扩展

6. 常见排错

Bot 不响应：检查 Token 是否正确，确认没有同时运行 Webhook 和 Polling。
群组里无响应：检查是否关闭 Privacy Mode，是否给 Bot 管理员权限。
响应很慢：检查 Agent 是否正在调用外部工具，可以先回复“处理中”。
额度消耗异常：检查 allowed_users 和 allowed_chats，避免公开群消息全量进模型。