跳到主要内容

Telegram 设置

Hermes Agent 与 Telegram 作为全功能对话机器人集成。连接后，你可以从任何设备与你的代理聊天，发送自动转录的语音备忘录，接收计划任务结果，并在群聊中使用代理。该集成基于 python-telegram-bot 并支持文本、语音、图像和文件附件。

步骤 1：通过 BotFather 创建机器人​

每个 Telegram 机器人都需要一个由 @BotFather（Telegram 官方机器人管理工具）颁发的 API 令牌。

  1. 打开 Telegram 并搜索 @BotFather，或访问 t.me/BotFather
  2. 发送 /newbot
  3. 选择一个显示名称（例如"Hermes Agent"）——这可以是任何内容
  4. 选择一个用户名——这必须是唯一的且以 bot 结尾（例如 my_hermes_bot）
  5. BotFather 回复你的 API 令牌。它看起来像这样：
123456789:ABCdefGHIjklMNOpqrSTUvwxYZ
注意

保持你的机器人令牌秘密。拥有此令牌的任何人都可以控制你的机器人。如果泄露，立即通过 /revoke 在 BotFather 中撤销。

步骤 2：自定义你的机器人（可选）​

这些 BotFather 命令改善用户体验。向 @BotFather 发送消息并使用：

命令用途
/setdescription在用户开始聊天前显示的"此机器人可以做什么？"文本
/setabouttext机器人个人资料页面上的简短文本
/setuserpic为你的机器人上传头像
/setcommands定义命令菜单（聊天中的 / 按钮）
/setprivacy控制机器人是否看到所有群消息（参见步骤 3）
提示

对于 /setcommands，一套有用的起始命令：

help - 显示帮助信息
new - 开始新的对话
sethome - 将此聊天设置为主频道

步骤 3：隐私模式（群组的关键）​

Telegram 机器人默认启用****隐私模式。这是在群组中使用机器人时最常见的混淆来源。

隐私模式开启时，你的机器人只能看到：

  • 以 / 命令开头的消息
  • 直接回复机器人自己消息的消息
  • 服务消息（成员加入/离开、置顶消息等）
  • 机器人为管理员的频道中的消息

隐私模式关闭时，机器人接收群组中的每条消息。

如何禁用隐私模式​

  1. 向 @BotFather 发送消息
  2. 发送 /mybots
  3. 选择你的机器人
  4. 进入 Bot Settings → Group Privacy → Turn off
注意

更改隐私设置后，你必须移除并重新添加机器人到任何群组。 Telegram 在机器人加入群组时缓存隐私状态，在移除并重新添加之前不会更新。

提示

禁用隐私模式的替代方案：将机器人提升为群组管理员。管理员机器人无论隐私设置如何都始终接收所有消息，并且避免了切换全局隐私模式的必要性。

步骤 4：找到你的用户 ID​

Hermes Agent 使用数字 Telegram 用户 ID 来控制访问。你的用户 ID 不是你的用户名——它是一个像 123456789 这样的数字。

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

方法 2： 向 @get_id_bot 发送消息——另一个可靠选项。

保存这个数字；你需要在下一步中使用它。

步骤 5：配置 Hermes​

选项 A：交互式设置（推荐）​

hermes gateway setup

当提示时选择 Telegram。向导会询问你的机器人令牌和允许的用户 ID，然后为你写入配置。

选项 B：手动配置​

将以下内容添加到 ~/.hermes/.env：

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

启动网关​

hermes gateway

机器人应在几秒钟内上线。在 Telegram 上向它发送消息以验证。

Webhook 模式​

默认情况下，Hermes 使用长轮询连接到 Telegram——网关向 Telegram 的服务器发出出站请求以获取新更新。这适用于本地和常驻部署。

对于云部署（Fly.io、Railway、Render 等），webhook 模式更具成本效益。这些平台可以在入站 HTTP 流量上自动唤醒暂停的机器，但不能在出站连接上唤醒。由于轮询是出站的，轮询机器人永远不会休眠。Webhook 模式翻转方向——Telegram 将更新推送到你机器人的 HTTPS URL，实现空闲时休眠的部署。

轮询（默认）Webhook
方向网关 → Telegram（出站）Telegram → 网关（入站）
适用于本地、常驻服务器带自动唤醒的云平台
设置无需额外配置设置 TELEGRAM_WEBHOOK_URL
空闲成本机器必须保持运行机器可以在消息之间休眠

配置​

将以下内容添加到 ~/.hermes/.env：

TELEGRAM_WEBHOOK_URL=https://my-app.fly.dev/telegram
# TELEGRAM_WEBHOOK_PORT=8443        # 可选，默认为 8443
# TELEGRAM_WEBHOOK_SECRET=mysecret  # 可选，推荐用于生产
变量必需描述
TELEGRAM_WEBHOOK_URL是Telegram 将发送更新的公共 HTTPS URL。URL 路径自动提取（例如，上面示例中的 /telegram）。
TELEGRAM_WEBHOOK_PORT否webhook 服务器监听本地端口（默认：8443）。
TELEGRAM_WEBHOOK_SECRET否用于验证更新确实来自 Telegram 的秘密令牌。强烈推荐用于生产部署。

当设置 TELEGRAM_WEBHOOK_URL 时，网关启动 HTTP webhook 服务器而不是轮询。未设置时，使用轮询模式——与以前版本没有行为变化。

云部署示例（Fly.io）​

  1. 将环境变量添加到你的 Fly.io 应用 secrets：
fly secrets set TELEGRAM_WEBHOOK_URL=https://my-app.fly.dev/telegram
fly secrets set TELEGRAM_WEBHOOK_SECRET=$(openssl rand -hex 32)
  1. 在你的 fly.toml 中暴露 webhook 端口：
[[services]]
  internal_port = 8443
  protocol = "tcp"

  [[services.ports]]
    handlers = ["tls", "http"]
    port = 443
  1. 部署：
fly deploy

网关日志应显示：[telegram] Connected to Telegram (webhook mode)。

主频道​

在任何 Telegram 聊天（DM 或群组）中使用 /sethome 命令来指定它为主频道。计划任务（cron 作业）将结果交付到此频道。

你也可以在 ~/.hermes/.env 中手动设置：

TELEGRAM_HOME_CHANNEL=-1001234567890
TELEGRAM_HOME_CHANNEL_NAME="My Notes"
提示

群组聊天 ID 是负数（例如 -1001234567890）。你的个人 DM 聊天 ID 与你的用户 ID 相同。

语音消息​

传入语音（语音转文本）​

你在 Telegram 上发送的语音消息会自动通过 Hermes 配置的 STT 提供商转录并作为文本注入对话中。

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

传出语音（文本转语音）​

当代理通过 TTS 生成音频时，它作为原生 Telegram 语音气泡传递——圆形的、内联可播放的那种。

  • OpenAI 和 ElevenLabs 原生生成 Opus——无需额外设置
  • Edge TTS（默认免费提供商）输出 MP3，需要 ffmpeg 转换为 Opus：
# Ubuntu/Debian
sudo apt install ffmpeg

# macOS
brew install ffmpeg

如果没有 ffmpeg，Edge TTS 音频作为常规音频文件发送（仍然可播放，但使用矩形播放器而不是语音气泡）。

在 config.yaml 的 tts.provider 键下配置 TTS 提供商。

群组聊天使用​

Hermes Agent 在 Telegram 群组聊天中工作，有一些注意事项：

  • 隐私模式决定机器人能看到哪些消息（参见步骤 3）
  • TELEGRAM_ALLOWED_USERS 仍然适用——只有授权用户可以触发机器人，即使在群组中
  • 你可以用 telegram.require_mention: true 防止机器人响应普通群组闲聊
  • 使用 telegram.require_mention: true 时，群组消息在以下情况下被接受：
    • 斜杠命令
    • 回复机器人自己的消息之一
    • @botusername 提及
    • 匹配你在 telegram.mention_patterns 中配置的某个正则表达式唤醒词
  • 如果 telegram.require_mention 未设置或为 false，Hermes 保持之前开放群组行为，并响应它能看到的所有正常群组消息

群组触发配置示例​

将此添加到 ~/.hermes/config.yaml：

telegram:
  require_mention: true
  mention_patterns:
    - "^\\s*chompy\\b"

此示例允许所有常规直接触发加上以 chompy 开头的消息，即使它们没有使用 @mention。

关于 mention_patterns 的注意事项​

  • 模式使用 Python 正则表达式
  • 匹配不区分大小写
  • 模式对文本消息和媒体标题进行检查
  • 无效的正则表达式模式被忽略，在网关日志中显示警告而不是崩溃机器人
  • 如果你希望模式只在消息开头匹配，用 ^ 锚定它

私有聊天主题（Bot API 9.4）​

Telegram Bot API 9.4（2026年2月）引入了私有聊天主题——机器人可以直接在 1 对 1 DM 聊天中创建论坛风格的主题线程，无需超级群组。这让你可以在与 Hermes 的现有 DM 中运行多个隔离的工作区。

使用场景​

如果你在几个长期运行的项目上工作，主题保持它们的上下文分开：

  • "网站"主题 — 处理你的生产 Web 服务
  • "研究"主题 — 文献综述和论文探索
  • "常规"主题 — 杂项任务和快速问题

每个主题获得自己的对话会话、历史和上下文——与其他主题完全隔离。

配置​

在 ~/.hermes/config.yaml 的 platforms.telegram.extra.dm_topics 下添加主题：

platforms:
  telegram:
    extra:
      dm_topics:
      - chat_id: 123456789        # 你的 Telegram 用户 ID
        topics:
        - name: General
          icon_color: 7322096
        - name: Website
          icon_color: 9367192
        - name: Research
          icon_color: 16766590
          skill: arxiv              # 在此主题中自动加载技能

字段：

字段必需描述
name是主题显示名称
icon_color否Telegram 图标颜色代码（整数）
icon_custom_emoji_id否主题图标的自定义表情符号 ID
skill否在此主题中新会话时自动加载的技能
thread_id否创建后自动填充——不要手动设置

工作原理​

  1. 在网关启动时，Hermes 为每个还没有 thread_id 的主题调用 createForumTopic
  2. thread_id 自动保存回 config.yaml——后续重启跳过 API 调用
  3. 每个主题映射到隔离的会话键：agent:main:telegram:dm:{chat_id}:{thread_id}
  4. 每个主题中的消息有自己的对话历史、记忆刷新和上下文窗口

技能绑定​

带有 skill 字段的主题在新会话在该主题中开始时自动加载该技能。这与在对话开始时输入 /skill-name 完全相同——技能内容被注入第一条消息，随后的消息在对话历史中看到它。

例如，带有 skill: arxiv 的主题在其会话重置时（由于空闲超时、每日重置或手动 /reset）会预加载 arxiv 技能。

提示

在配置之外创建的主题（例如通过手动调用 Telegram API）在 forum_topic_created 服务消息到达时自动被发现。你也可以在网关运行期间将主题添加到配置——它们会在下一次缓存未命中时被拾取。

群组论坛主题技能绑定​

启用了主题模式（也称为"论坛主题"）的超级群组已经获得每个主题的会话隔离——每个 thread_id 映射到自己的对话。但你可能希望在消息到达特定群组主题时自动加载技能，就像 DM 主题技能绑定工作一样。

使用场景​

带有不同工作流论坛主题的团队超级群组：

  • 工程主题 → 自动加载 software-development 技能
  • 研究主题 → 自动加载 arxiv 技能
  • 常规主题 → 无技能，通用助手

配置​

在 ~/.hermes/config.yaml 的 platforms.telegram.extra.group_topics 下添加主题绑定：

platforms:
  telegram:
    extra:
      group_topics:
      - chat_id: -1001234567890       # 超级群组 ID
        topics:
        - name: Engineering
          thread_id: 5
          skill: software-development
        - name: Research
          thread_id: 12
          skill: arxiv
        - name: General
          thread_id: 1
          # 无技能——通用目的

字段：

字段必需描述
chat_id是超级群组的数字 ID（以 -100 开头的负数）
name否主题的人类可读标签（仅供信息参考）
thread_id是Telegram 论坛主题 ID——在 t.me/c/<group_id>/<thread_id> 链接中可见
skill否在此主题中新会话时自动加载的技能

工作原理​

  1. 当消息到达映射的群组主题时，Hermes 在 group_topics 配置中查找 chat_id 和 thread_id
  2. 如果匹配条目有 skill 字段，该技能为会话自动加载——与 DM 主题技能绑定相同
  3. 没有 skill 键的主题仅获得会话隔离（现有行为，不变）
  4. 未映射的 thread_id 或 chat_id 值静默顺延——无错误，无技能

与 DM 主题的区别​

DM 主题群组主题
配置键extra.dm_topicsextra.group_topics
主题创建如果缺少 thread_id，Hermes 通过 API 创建主题管理员在 Telegram UI 中创建主题
thread_id创建后自动填充必须手动设置
icon_color / icon_custom_emoji_id支持不适用（管理员控制外观）
技能绑定✓✓
会话隔离✓✓（论坛主题已内置）
提示

要找到主题的 thread_id，在 Telegram Web 或 Desktop 中打开主题，查看 URL：https://t.me/c/1234567890/5——最后一个数字（5）是 thread_id。超级群组的 chat_id 是带 -100 前缀的群组 ID（例如，群组 1234567890 变为 -1001234567890）。

最近的 Bot API 功能​

  • Bot API 9.4（2026年2月）： 私有聊天主题——机器人可以通过 createForumTopic 在 1 对 1 DM 聊天中创建论坛主题。参见上面的私有聊天主题。
  • 隐私政策： Telegram 现在要求机器人有隐私政策。通过 BotFather 使用 /setprivacy_policy 设置一个，否则 Telegram 可能会自动生成占位符。如果你的机器人是面向公众的，这尤其重要。
  • 消息流式传输： Bot API 9.x 添加了对流式长响应的支持，这可以改善冗长代理回复的感知延迟。

交互式模型选择器​

当你在 Telegram 聊天中发送不带参数的 /model 时，Hermes 显示一个交互式内联键盘用于切换模型：

  1. 提供商选择 — 按钮显示每个可用提供商及模型数量（例如，"OpenAI (15)"，"✓ Anthropic (12)" 表示当前提供商）。
  2. 模型选择 — 分页模型列表，带 Prev/Next 导航、Back 按钮返回提供商，以及 Cancel。

当前模型和提供商显示在顶部。所有导航通过就地编辑同一条消息进行（无聊天混乱）。

提示

如果你知道确切模型名称，直接输入 /model <name> 跳过选择器。你也可以输入 /model <name> --global 以在会话之间保持更改。

Webhook 模式​

默认情况下，Telegram 适配器通过长轮询连接——网关向 Telegram 的服务器发出出站连接。这在所有地方都有效，但保持持久连接打开。

Webhook 模式是一种替代方案，Telegram 通过 HTTPS 将更新推送到你的服务器。这对于无服务器和云部署（Fly.io、Railway 等）非常理想，在这些环境中入站 HTTP 可以唤醒暂停的机器。

配置​

设置 TELEGRAM_WEBHOOK_URL 环境变量以启用 webhook 模式：

# 必需——你的公共 HTTPS 端点
TELEGRAM_WEBHOOK_URL=https://app.fly.dev/telegram

# 可选——本地监听端口（默认：8443）
TELEGRAM_WEBHOOK_PORT=8443

# 可选——用于更新验证的秘密令牌（如果未设置则自动生成）
TELEGRAM_WEBHOOK_SECRET=my-secret-token

或在 ~/.hermes/config.yaml 中：

telegram:
  webhook_mode: true

当设置 TELEGRAM_WEBHOOK_URL 时，网关启动 HTTP 服务器监听 0.0.0.0:<port> 并向 Telegram 注册 webhook URL。URL 路径从 webhook URL 提取（默认为 /telegram）。

注意

Telegram 需要 webhook 端点上的有效 TLS 证书。自签名证书将被拒绝。使用反向代理（nginx、Caddy）或提供 TLS 终止的平台（Fly.io、Railway、Cloudflare Tunnel）。

DNS-over-HTTPS 后备 IP​

在某些受限网络中，api.telegram.org 可能解析为无法访问的 IP。Telegram 适配器包括后备 IP 机制，在保持正确 TLS 主机名和 SNI 的同时透明地重试替代 IP 的连接。

工作原理​

  1. 如果设置了 TELEGRAM_FALLBACK_IPS，则直接使用这些 IP。
  2. 否则，适配器自动通过 DNS-over-HTTPS（DoH）向 Google DNS 和 Cloudflare DNS 查询 api.telegram.org 的替代 IP。
  3. 与系统 DNS 结果不同的 DoH 返回的 IP 用作后备。
  4. 如果 DoH 也被阻止，则使用硬编码种子 IP（149.154.167.220）作为最后手段。
  5. 一旦后备 IP 成功，它会变得"粘性"——后续请求直接使用它而不先重试主路径。

配置​

# 显式后备 IP（逗号分隔）
TELEGRAM_FALLBACK_IPS=149.154.167.220,149.154.167.221

或在 ~/.hermes/config.yaml 中：

platforms:
  telegram:
    extra:
      fallback_ips:
        - "149.154.167.220"
提示

你通常不需要手动配置这个。DoH 的自动发现处理大多数受限网络场景。只有当 DoH 在你的网络上也被阻止时，才需要 TELEGRAM_FALLBACK_IPS 环境变量。

代理支持​

如果你的网络需要 HTTP 代理来访问互联网（在企业环境中很常见），Telegram 适配器自动读取标准代理环境变量并通过代理路由所有连接。

支持的变量​

适配器按顺序检查这些环境变量，使用第一个设置的：

  1. HTTPS_PROXY
  2. HTTP_PROXY
  3. ALL_PROXY
  4. https_proxy / http_proxy / all_proxy（小写变体）

配置​

在启动网关之前在环境中设置代理：

export HTTPS_PROXY=http://proxy.example.com:8080
hermes gateway

或将其添加到 ~/.hermes/.env：

HTTPS_PROXY=http://proxy.example.com:8080

代理适用于主传输和所有后备 IP 传输。无需额外的 Hermes 配置——如果设置了环境变量，就会自动使用。

备注

这涵盖了 Hermes 用于 Telegram 连接的自定义后备传输层。在其他地方使用的标准 httpx 客户端已经原生尊重代理环境变量。

消息反应​

机器人可以添加表情符号反应到消息作为视觉处理反馈：

  • 👀 当机器人开始处理你的消息时
  • ✅ 当响应成功传递时
  • ❌ 如果处理过程中发生错误

反应默认禁用。在 config.yaml 中启用：

telegram:
  reactions: true

或通过环境变量：

TELEGRAM_REACTIONS=true
备注

与 Discord（那里的反应是附加的）不同，Telegram 的 Bot API 在单个调用中替换所有机器人反应。从 👀 到 ✅/❌ 的转换是原子发生的——你不会同时看到两者。

提示

如果机器人在群组中没有添加反应的权限，反应调用会静默失败，消息处理继续正常进行。

故障排除​

问题解决方案
机器人完全不响应验证 TELEGRAM_BOT_TOKEN 正确。在 hermes gateway 日志中检查错误。
机器人用"未授权"响应你的用户 ID 不在 TELEGRAM_ALLOWED_USERS 中。用 @userinfobot 仔细检查。
机器人在群组消息中忽略隐私模式可能开启。禁用它（步骤 3）或让机器人成为群组管理员。更改隐私后记得移除并重新添加机器人。
语音消息未转录验证 STT 可用：安装 faster-whisper 用于本地转录，或在 ~/.hermes/.env 中设置 GROQ_API_KEY / VOICE_TOOLS_OPENAI_KEY。
语音回复是文件而不是气泡安装 ffmpeg（Edge TTS Opus 转换需要）。
机器人令牌被撤销/无效通过 BotFather 的 /revoke 然后 /newbot 或 /token 生成新令牌。更新你的 .env 文件。
Webhook 未接收更新验证 TELEGRAM_WEBHOOK_URL 可公开访问（用 curl 测试）。确保你的平台/反向代理将从 URL 端口的入站 HTTPS 流量路由到你配置的本地监听端口（它们不需要是相同的数字）。确保 SSL/TLS 处于活动状态——Telegram 仅发送到 HTTPS URL。检查防火墙规则。

Exec 审批​

当代理尝试运行潜在危险命令时，它会在聊天中请求你批准：

⚠️ 此命令可能危险（递归删除）。回复"yes"以批准。

回复"yes"/"y"以批准或"no"/"n"以拒绝。

安全​

注意

始终设置 TELEGRAM_ALLOWED_USERS 以限制谁可以与你的机器人交互。没有它，网关默认拒绝所有用户作为安全措施。

切勿公开分享你的机器人令牌。如果泄露，立即通过 BotFather 的 /revoke 命令撤销。

有关更多详细信息，请参阅安全文档。你也可以使用 DM 配对 获得更动态的用户授权方法。