Telegram 配置

Hermes Agent 與 Telegram 集成，作為功能完整的對話機器人。連接成功後，您可從任意設備與您的 Agent 聊天，發送語音備忘錄（自動轉錄）、接收定時任務結果，並在群組聊天中使用該 Agent。該集成基於 python-telegram-bot，支持文本、語音、圖片和文件附件。

第一步：通過 BotFather 創建機器人

每個 Telegram 機器人都需要由 @BotFather（Telegram 官方機器人管理工具）頒發的 API 密鑰。

打開 Telegram 並搜索 @BotFather，或訪問 t.me/BotFather
發送 /newbot
選擇一個 顯示名稱（例如：“Hermes Agent”）—— 可以是任意內容
選擇一個 用戶名 —— 必須唯一且以 bot 結尾（例如：my_hermes_bot）
BotFather 會回覆您的 API 密鑰。格式如下：

123456789:ABCdefGHIjklMNOpqrSTUvwxYZ

注意

請保密您的機器人密鑰。任何持有此密鑰的人都可以控制您的機器人。如果密鑰洩露，請立即通過 BotFather 中的 /revoke 命令撤銷。

第二步：自定義您的機器人（可選）

以下 BotFather 命令可提升用戶體驗。請向 @BotFather 發送以下命令：

命令	用途
`/setdescription`	用戶開始聊天前顯示的“此機器人能做什麼？”文本
`/setabouttext`	機器人個人資料頁面上的簡短文本
`/setuserpic`	上傳機器人的頭像
`/setcommands`	定義命令菜單（聊天中的 `/` 按鈕）
`/setprivacy`	控制機器人是否查看群組中的所有消息（參見第三步）

提示

對於 /setcommands，一個有用的初始設置：

help - Show help information
new - Start a new conversation
sethome - Set this chat as the home channel

第三步：隱私模式（群組使用的關鍵）

Telegram 機器人默認啟用 隱私模式。這是在群組中使用機器人時最常見的困惑來源。

當隱私模式開啟時，您的機器人只能看到：

以 / 開頭的命令消息
直接回復機器人自身消息的消息
服務消息（成員加入/離開、置頂消息等）
機器人是管理員的頻道中的消息

當隱私模式關閉時，機器人將接收群組中的每一條消息。

如何關閉隱私模式

向 @BotFather 發送消息
發送 /mybots
選擇您的機器人
進入 Bot 設置 → 群組隱私 → 關閉

注意

在更改隱私設置後，您必須從群組中移除並重新添加機器人。Telegram 在機器人加入群組時會緩存其隱私狀態，除非機器人被移除並重新添加，否則不會更新。

提示

替代關閉隱私模式的方法：將機器人提升為 群組管理員。管理員機器人無論隱私設置如何，都會收到所有消息，從而避免需要切換全局隱私模式。

第四步：查找您的用戶 ID

Hermes Agent 使用數字型 Telegram 用戶 ID 來控制訪問權限。您的用戶 ID 不是您的用戶名——而是一個數字，如 123456789。

方法一（推薦）： 向 @userinfobot 發送消息——它會立即回覆您的用戶 ID。

方法二： 向 @get_id_bot 發送消息——另一個可靠的選項。

請保存該數字，您將在下一步需要它。

第五步：配置 Hermes

選項 A：交互式配置（推薦）

hermes gateway setup

在提示時選擇 Telegram。嚮導將要求您輸入機器人密鑰和允許的用戶 ID，然後為您生成配置文件。

選項 B：手動配置

將以下內容添加到 ~/.hermes/.env 文件中：

TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrSTUvwxYZ
TELEGRAM_ALLOWED_USERS=123456789    # 多個用戶以逗號分隔

啟動網關

hermes gateway

機器人應在幾秒內上線。請在 Telegram 中向其發送一條消息以驗證。

Webhook 模式

默認情況下，Hermes 使用 長輪詢（long polling） 方式連接 Telegram —— 網關主動向 Telegram 服務器發起請求以獲取新消息。這種方式適用於本地部署或始終在線的服務器。

對於 雲部署（Fly.io、Railway、Render 等），Webhook 模式 更具成本效益。這些平臺可以在收到 HTTP 入站流量時自動喚醒休眠的機器，但無法通過出站連接喚醒。由於輪詢是出站的，使用輪詢的機器人永遠無法休眠。Webhook 模式則反轉了方向——Telegram 將更新推送到您機器人的 HTTPS 地址，從而實現“空閒時休眠”的部署。

	輪詢（默認）	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）

將環境變量添加到你的 Fly.io 應用密鑰中：

fly secrets set TELEGRAM_WEBHOOK_URL=https://my-app.fly.dev/telegram
fly secrets set TELEGRAM_WEBHOOK_SECRET=$(openssl rand -hex 32)

在 fly.toml 中暴露 Webhook 端口：

[[services]]
  internal_port = 8443
  protocol = "tcp"

  [[services.ports]]
    handlers = ["tls", "http"]
    port = 443

部署：

fly deploy

網關日誌應顯示：[telegram] Connected to Telegram (webhook mode)。

主頻道

在任意 Telegram 聊天（私聊或群組）中使用 /sethome 命令，將該聊天設為 主頻道。計劃任務（cron 作業）的結果將發送至此頻道。

你也可以在 ~/.hermes/.env 中手動設置：

TELEGRAM_HOME_CHANNEL=-1001234567890
TELEGRAM_HOME_CHANNEL_NAME="My Notes"

提示

群組聊天 ID 為負數（例如：-1001234567890）。你的個人私聊聊天 ID 與你的用戶 ID 相同。

語音消息

入站語音（語音轉文字）

你在 Telegram 中發送的語音消息將由 Hermes 配置的 STT 提供商自動轉錄，並作為文本注入到對話中。

local 使用運行 Hermes 的機器上的 faster-whisper —— 無需 API 密鑰
groq 使用 Groq Whisper，需要 GROQ_API_KEY
openai 使用 OpenAI Whisper，需要 VOICE_TOOLS_OPENAI_KEY

出站語音（文字轉語音）

當 Agent 生成音頻時，將以原生 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 月發佈）引入了 私聊話題——機器人可在一對一私聊中直接創建論壇風格的話題線程，無需超級群組。這使得你可以在與 Hermes 的現有私聊中運行多個隔離的工作空間。

使用場景

如果你同時處理多個長期項目，話題可保持各自上下文獨立：

話題 "Website" —— 處理你的生產 Web 服務
話題 "Research" —— 文獻綜述與論文探索
話題 "General" —— 雜項任務和快速提問

每個話題都有獨立的會話、歷史記錄和上下文——彼此完全隔離。

配置

在 ~/.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              # 在本主題中自動加載 skill

字段：

字段	必填	描述
`name`	是	話題顯示名稱
`icon_color`	否	Telegram 圖標顏色代碼（整數）
`icon_custom_emoji_id`	否	話題圖標的自定義表情 ID
`skill`	否	在此話題的新會話中自動加載的技能
`thread_id`	否	話題創建後自動填充——請勿手動設置

在網關啟動時，Hermes 會為每個尚未擁有 thread_id 的話題調用 createForumTopic
thread_id 會自動保存回 config.yaml —— 後續重啟將跳過 API 調用
每個話題映射到一個獨立的會話密鑰：agent:main:telegram:dm:{chat_id}:{thread_id}
每個話題中的消息擁有獨立的對話歷史、內存清空機制和上下文窗口

技能綁定

帶有 skill 字段的話題在新會話啟動時會自動加載該技能。其行為與在對話開頭輸入 /skill-name 完全相同 —— 技能內容會被注入到第一條消息中，後續消息可在對話歷史中看到該內容。

例如，一個 skill: arxiv 的話題，每當其會話重置時（由於空閒超時、每日重置或手動執行 /reset），都會自動加載 arxiv 技能。

提示

通過手動調用 Telegram API 創建的話題（非配置文件中定義）會在收到 forum_topic_created 服務消息時被自動發現。你也可以在網關運行時向配置文件中添加話題 —— 它們將在下一次緩存未命中時被加載。

群組論壇話題技能綁定

啟用了 話題模式（也稱“論壇話題”）的超級群組已支持按話題進行會話隔離 —— 每個 thread_id 映射到獨立的對話。但你可能希望在特定群組話題中收到消息時 自動加載某個技能，就像私聊話題的技能綁定一樣。

使用場景

一個團隊超級群組，其論壇話題用於不同工作流：

工程話題 → 自動加載 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
          # 無 skill — 通用

字段說明：

字段	必填	描述
`chat_id`	是	超級群組的數字 ID（以 `-100` 開頭的負數）
`name`	否	話題的人類可讀標籤（僅用於信息參考）
`thread_id`	是	Telegram 論壇話題 ID —— 可在 `t.me/c/<group_id>/<thread_id>` 鏈接中查看
`skill`	否	在此話題的新會話中自動加載的技能

工作原理

當消息到達已映射的群組話題時，Hermes 會根據 chat_id 和 thread_id 在 group_topics 配置中查找匹配項
如果匹配項包含 skill 字段，則該技能將被自動加載到會話中 —— 與私聊話題的技能綁定行為完全一致
未設置 skill 鍵的話題僅獲得會話隔離功能（原有行為，保持不變）
未映射的 thread_id 或 chat_id 值將靜默處理 —— 不報錯，也不加載技能

與私聊話題的區別

	私聊話題 (DM Topics)	群組話題 (Group Topics)
配置鍵	`extra.dm_topics`	`extra.group_topics`
話題創建	Hermes 通過 API 自動創建（若 `thread_id` 缺失）	管理員在 Telegram 界面中手動創建
`thread_id`	創建後自動填充	必須手動設置
`icon_color` / `icon_custom_emoji_id`	支持	不適用（由管理員控制外觀）
技能綁定	✓	✓
會話隔離	✓	✓（論壇話題已內置此功能）

提示

要查找話題的 thread_id，請在 Telegram Web 或桌面客戶端中打開該話題，查看 URL：https://t.me/c/1234567890/5 —— 最後一個數字（5）即為 thread_id。超級群組的 chat_id 是群組 ID 前綴加上 -100（例如，群組 1234567890 對應的 chat_id 為 -1001234567890）。

新版 Bot API 功能

Bot API 9.4（2026 年 2 月）： 私聊話題 —— 機器人可通過 createForumTopic 在一對一私聊中創建論壇話題。詳見上方私聊話題（Bot API 9.4）
隱私政策： Telegram 現在要求機器人必須設置隱私政策。可通過 BotFather 使用 /setprivacy_policy 設置，否則 Telegram 可能自動生成佔位符。若你的機器人面向公眾，這一點尤為重要。
消息流式傳輸： Bot API 9.x 增加了對長響應流式傳輸的支持，可顯著改善機器人長回覆的感知延遲。

交互式模型選擇器

當你在 Telegram 聊天中發送 /model 且不帶參數時，Hermes 會顯示一個交互式內聯鍵盤，用於切換模型：

提供方選擇 —— 按鈕顯示每個可用提供方及其模型數量（例如：“OpenAI (15)”、“✓ Anthropic (12)” 表示當前提供方）
模型選擇 —— 分頁模型列表，包含 上一頁/下一頁 導航按鈕，返回按鈕返回提供方列表，以及取消按鈕

當前模型和提供方信息顯示在頂部。所有導航操作均通過原地編輯同一消息完成（不會造成聊天混亂）。

提示

如果你知道確切的模型名稱，可直接輸入 /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

# 可選 — 用於更新驗證的秘密 token（如果未設置，則自動生成）
TELEGRAM_WEBHOOK_SECRET=my-secret-token

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

telegram:
  webhook_mode: true

當設置了 TELEGRAM_WEBHOOK_URL 後，網關將啟動一個監聽在 0.0.0.0:<port> 的 HTTP 服務器，並向 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 地址。

工作原理

如果設置了 TELEGRAM_FALLBACK_IPS，則直接使用這些 IP。
否則，適配器會自動通過 DNS-over-HTTPS（DoH）查詢 Google DNS 和 Cloudflare DNS，以發現 api.telegram.org 的備用 IP。
由 DoH 返回且與系統 DNS 結果不同的 IP 將作為備用 IP 使用。
如果 DoH 也被屏蔽，則使用一個硬編碼的種子 IP（149.154.167.220）作為最後手段。
一旦某個備用 IP 成功連接，它將變為“粘性”IP —— 後續請求將直接使用該 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 環境變量。

Agent 支持

如果你的網絡需要通過 HTTP 代理訪問互聯網（常見於企業環境），Telegram 適配器會自動讀取標準的代理環境變量，並將所有連接通過代理路由。

支持的變量

適配器按順序檢查以下環境變量，使用第一個已設置的：

HTTPS_PROXY
HTTP_PROXY
ALL_PROXY
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

Agent 適用於主傳輸通道以及所有備用 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 流量路由到由 `TELEGRAM_WEBHOOK_PORT` 配置的本地監聽端口（兩者不必相同）。確保 SSL/TLS 已啟用 —— Telegram 僅向 HTTPS URL 發送數據。檢查防火牆規則。

執行審批

當 Agent 嘗試運行可能具有危險性的命令時，它會在聊天中向您請求批准：

⚠️ 此命令可能具有危險性（遞歸刪除）。回覆 "yes" 以批准。

回覆 "yes"/"y" 以批准，或 "no"/"n" 以拒絕。

安全性

注意

請始終設置 TELEGRAM_ALLOWED_USERS 以限制誰可以與您的機器人交互。如果沒有設置，網關將默認拒絕所有用戶，作為一項安全措施。

切勿公開分享您的機器人令牌。如果令牌洩露，請立即通過 BotFather 的 /revoke 命令撤銷。

如需瞭解更多信息，請參閱安全性文檔。您還可以使用私信配對來採用更動態的用戶授權方式。

第一步：通過 BotFather 創建機器人​

第二步：自定義您的機器人（可選）​

第三步：隱私模式（群組使用的關鍵）​

如何關閉隱私模式​

第四步：查找您的用戶 ID​

第五步：配置 Hermes​

選項 A：交互式配置（推薦）​

選項 B：手動配置​

啟動網關​

Webhook 模式​

配置​

雲部署示例（Fly.io）​

主頻道​

語音消息​

入站語音（語音轉文字）​

出站語音（文字轉語音）​

群組聊天使用​

群組觸發配置示例​

關於 mention_patterns 的說明​

私聊話題（Bot API 9.4）​

使用場景​

配置​

技能綁定​

群組論壇話題技能綁定​

使用場景​

配置​

工作原理​

與私聊話題的區別​

新版 Bot API 功能​

交互式模型選擇器​

Webhook 模式​

配置​

DNS-over-HTTPS 備用 IP​

工作原理​

配置​

Agent 支持​

支持的變量​

配置​

消息反應​

故障排除​

執行審批​

安全性​

第一步：通過 BotFather 創建機器人

第二步：自定義您的機器人（可選）

第三步：隱私模式（群組使用的關鍵）

如何關閉隱私模式

第四步：查找您的用戶 ID

第五步：配置 Hermes

選項 A：交互式配置（推薦）

選項 B：手動配置

啟動網關

Webhook 模式

配置

雲部署示例（Fly.io）

主頻道

語音消息

入站語音（語音轉文字）

出站語音（文字轉語音）

群組聊天使用

群組觸發配置示例

關於 `mention_patterns` 的說明

私聊話題（Bot API 9.4）

使用場景

配置

技能綁定

群組論壇話題技能綁定

使用場景

配置

工作原理

與私聊話題的區別

新版 Bot API 功能

交互式模型選擇器

Webhook 模式

配置

DNS-over-HTTPS 備用 IP

工作原理

配置

Agent 支持

支持的變量

配置

消息反應

故障排除

執行審批

安全性