Telegram 配置

Hermes Agent 与 Telegram 的集成提供了完整的对话式 Bot 体验。连接后，你可以从任何设备与 Agent 聊天、发送自动转录的语音消息、接收定时任务结果，并在群组中使用 Agent。

第一步：通过 BotFather 创建 Bot

每个 Telegram Bot 都需要由 @BotFather 颁发的 API Token。

打开 Telegram 搜索 @BotFather，或访问 t.me/BotFather
发送 /newbot
选择一个显示名称（如 “Hermes Agent”）— 可以随意命名
选择一个用户名 — 必须唯一且以 bot 结尾（如 my_hermes_bot）
BotFather 返回你的 API Token，格式如下：

123456789:ABCdefGHIjklMNOpqrSTUvwxYZ

第二步：自定义 Bot（可选）

通过 BotFather 改善用户体验：

命令	用途
`/setdescription`	”这个 Bot 能做什么？” 的描述文字
`/setabouttext`	Bot 个人资料页的简短文字
`/setuserpic`	上传 Bot 头像
`/setcommands`	定义命令菜单（聊天中的 / 按钮）
`/setprivacy`	控制 Bot 是否能看到所有群组消息

第三步：隐私模式（群组关键设置）

Telegram Bot 默认启用隐私模式，这是使用 Bot 时最常见的困惑来源。

隐私模式开启时，Bot 只能看到：

以 / 命令开头的消息
直接回复 Bot 自身消息的消息
服务消息（成员加入/离开、置顶消息等）
Bot 是管理员的频道中的消息

隐私模式关闭时，Bot 接收群组中的所有消息。

关闭隐私模式

向 @BotFather 发送消息
发送 /mybots
选择你的 Bot
进入 Bot Settings → Group Privacy → Turn off

观察群组消息但不自动回复

配置 Telegram 让 Bot 能看到普通群组消息，但只在被直接提及时才回复：

telegram:
  allowed_chats:
    - "-1001234567890"
  group_allowed_chats:
    - "-1001234567890"
  require_mention: true
  observe_unmentioned_group_messages: true

在此模式下，未提及的群组消息会作为观察上下文追加到会话记录，但不会触发 Agent。

第四步：查找你的用户 ID

Hermes Agent 使用数字形式的 Telegram 用户 ID 控制访问。用户 ID 不是用户名 — 它是一串数字，如 123456789。

方法一（推荐）：向 @userinfobot 发送消息 — 它会立即回复你的用户 ID
方法二：向 @get_id_bot 发送消息

保存这个数字，下一步需要用到。

第五步：配置 Hermes

方式 A：交互式设置（推荐）

hermes gateway setup

选择 Telegram，向导会询问你的 Bot Token 和允许的用户 ID，然后自动写入配置。

方式 B：手动配置

在 ~/.hermes/.env 中添加：

TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrSTUvwxYZ
TELEGRAM_ALLOWED_USERS=123456789    # 多个用户用逗号分隔

启动网关

hermes gateway

Bot 应该在几秒内上线。在 Telegram 上给 Bot 发送消息来验证。

Docker 终端下的文件发送

如果终端后端是 Docker，请注意 Telegram 附件是由网关进程发送的，不是从容器内部发送的。这意味着最终的 MEDIA:/... 路径必须在运行网关的宿主机上可读。

推荐模式：

terminal:
  backend: docker
  docker_volumes:
    - "/home/user/.hermes/cache/documents:/output"

然后在容器内写入文件到 /output/...，发送时使用宿主机路径：

MEDIA:/home/user/.hermes/cache/documents/report.txt

Webhook 模式

默认情况下，Hermes 使用长轮询连接 Telegram。对于云部署（Fly.io、Railway、Render 等），Webhook 模式更具成本效益。

方面	轮询（默认）	Webhook
方向	网关 → Telegram（出站）	Telegram → 网关（入站）
适用场景	本地、常开服务器	有自动唤醒的云平台
空闲成本	机器必须持续运行	机器可在消息间休眠

配置

在 ~/.hermes/.env 中添加：

TELEGRAM_WEBHOOK_URL=https://my-app.fly.dev/telegram
TELEGRAM_WEBHOOK_SECRET="$(openssl rand -hex 32)"    # 必填
# TELEGRAM_WEBHOOK_PORT=8443                           # 可选，默认 8443

变量	必填	说明
`TELEGRAM_WEBHOOK_URL`	是	Telegram 发送更新的公开 HTTPS URL
`TELEGRAM_WEBHOOK_SECRET`	是（设置 URL 时）	Telegram 在每个 Webhook 请求中回显的验证密钥
`TELEGRAM_WEBHOOK_PORT`	否	Webhook 服务器监听的本地端口（默认 8443）

代理支持

如果 Telegram API 被屏蔽或需要通过代理路由，可以设置 Telegram 专用代理：

telegram:
  proxy_url: "socks5://127.0.0.1:1080"

或环境变量：TELEGRAM_PROXY=socks5://127.0.0.1:1080

支持的协议：http://、https://、socks5://

主频道

在任何 Telegram 聊天（DM 或群组）中使用 /sethome 命令将其指定为主频道。定时任务（cron）的结果会投递到此频道。

手动配置：

TELEGRAM_HOME_CHANNEL=-1001234567890
TELEGRAM_HOME_CHANNEL_NAME="我的笔记"

语音消息

接收语音（语音转文字）

你发送的语音消息会被 Hermes 配置的 STT 提供商自动转录并作为文本注入对话：

local — 在运行 Hermes 的机器上使用 faster-whisper，无需 API Key
groq — 使用 Groq Whisper，需要 GROQ_API_KEY
openai — 使用 OpenAI Whisper，需要 VOICE_TOOLS_OPENAI_KEY

发送语音（文字转语音）

Agent 通过 TTS 生成的音频会以原生 Telegram 语音气泡形式投递 — 圆形的、可内联播放的那种。

OpenAI 和 ElevenLabs 原生输出 Opus — 无需额外设置
Edge TTS（默认免费提供商）输出 MP3，需要 ffmpeg 转换为 Opus

大文件支持（>20MB）

Telegram 公共 Bot API 将文件下载限制在 20 MB。如需处理更大的文件，可以运行本地 telegram-bot-api 服务器，将限制提升至 2 GB。

获取 Telegram API 凭据

访问 my.telegram.org/apps 并登录
创建新应用（任意名称和简短描述即可）
复制 api_id 和 api_hash

运行本地服务器

使用 Docker Compose：

services:
  tg-bot-api:
    image: aiogram/telegram-bot-api:latest
    container_name: tg-bot-api
    restart: unless-stopped
    ports:
      - "127.0.0.1:8081:8081"
    environment:
      TELEGRAM_API_ID: "12345"           # 你的 api_id
      TELEGRAM_API_HASH: "abcdef..."     # 你的 api_hash
      TELEGRAM_LOCAL: "1"                # 启用 --local 模式（20MB → 2GB）
    volumes:
      - ./tg-bot-api-data:/var/lib/telegram-bot-api

指向 Hermes

在 ~/.hermes/config.yaml 中：

platforms:
  telegram:
    extra:
      base_url: "http://127.0.0.1:8081/bot"
      base_file_url: "http://127.0.0.1:8081/file/bot"
      local_mode: true