Chuyển tới nội dung chính

Cài đặt điện tín

Hermes Agent tích hợp với Telegram dưới dạng bot đàm thoại đầy đủ tính năng. Sau khi kết nối, bạn có thể trò chuyện với nhân viên hỗ trợ của mình từ bất kỳ thiết bị nào, gửi bản ghi nhớ giọng nói được chép lời tự động, nhận kết quả nhiệm vụ theo lịch trình và sử dụng nhân viên hỗ trợ trong các cuộc trò chuyện nhóm. Việc tích hợp được xây dựng trên python-telegram-bot và hỗ trợ văn bản, giọng nói, hình ảnh và tệp đính kèm.

Bước 1: Tạo Bot thông qua BotFather

Mọi bot Telegram đều yêu cầu mã thông báo API do @BotFather, công cụ quản lý bot chính thức của Telegram cấp.

  1. Mở Telegram và tìm kiếm @BotFather hoặc truy cập t.me/BotFather
  2. Gửi /newbot
  3. Chọn tên hiển thị (ví dụ: "Đặc vụ Hermes") — đây có thể là bất kỳ tên nào
  4. Chọn tên người dùng — tên này phải là duy nhất và kết thúc bằng bot (ví dụ: my_hermes_bot )
  5. BotFather trả lời bằng mã thông báo API của bạn. Nó trông như thế này:
123456789:ABCdefGHIjklMNOpqrSTUvwxYZ

cảnh báo

Giữ bí mật mã thông báo bot của bạn. Bất kỳ ai có mã thông báo này đều có thể điều khiển bot của bạn. Nếu nó bị rò rỉ, hãy thu hồi nó ngay lập tức thông qua /revoke trong BotFather.

Bước 2: Tùy chỉnh Bot của bạn (Tùy chọn)

Các lệnh BotFather này cải thiện trải nghiệm người dùng. Nhắn tin @BotFather và sử dụng:

LệnhMục đích
/setdescriptionCâu hỏi "Bot này có thể làm gì?" văn bản hiển thị trước khi người dùng bắt đầu trò chuyện
/setabouttextVăn bản ngắn trên trang hồ sơ của bot
/setuserpicTải lên hình đại diện cho bot của bạn
/setcommandsXác định menu lệnh (nút / trong trò chuyện)
/setprivacyKiểm soát xem bot có nhìn thấy tất cả tin nhắn nhóm hay không (xem Bước 3)
mẹo

Đối với /setcommands , bộ khởi đầu hữu ích:

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

Bước 3: Chế độ riêng tư (Quan trọng đối với nhóm)

Các bot Telegram có chế độ riêng tư được bật theo mặc định. Đây là nguyên nhân gây nhầm lẫn phổ biến nhất khi sử dụng bot theo nhóm.

Khi BẬT chế độ quyền riêng tư, bot của bạn chỉ có thể thấy:

  • Tin nhắn bắt đầu bằng lệnh /
  • Trả lời trực tiếp tin nhắn của bot
  • Tin nhắn dịch vụ (thành viên tham gia/rời đi, tin nhắn được ghim, v.v.)
  • Tin nhắn trong các kênh mà bot là quản trị viên

Khi TẮT chế độ riêng tư, bot sẽ nhận được mọi tin nhắn trong nhóm.

Cách tắt chế độ riêng tư​

  1. Tin nhắn @BotFather
  2. Gửi /mybots
  3. Chọn bot của bạn
  4. Đi tới Cài đặt Bot → Quyền riêng tư của nhóm → Tắt
cảnh báo

Bạn phải xóa và thêm lại bot vào bất kỳ nhóm nào sau khi thay đổi cài đặt quyền riêng tư. Telegram lưu trữ trạng thái quyền riêng tư khi bot tham gia một nhóm và nó sẽ không cập nhật cho đến khi bot bị xóa và thêm lại.

mẹo

Một giải pháp thay thế cho việc tắt chế độ quyền riêng tư: thăng cấp bot lên quản trị viên nhóm. Các bot quản trị luôn nhận được tất cả tin nhắn bất kể cài đặt quyền riêng tư và điều này tránh việc phải chuyển đổi chế độ quyền riêng tư chung.

Bước 4: Tìm ID người dùng của bạn

Hermes Agent sử dụng ID người dùng Telegram bằng số để kiểm soát quyền truy cập. ID người dùng không phải tên người dùng của bạn — đó là một số như 123456789 .Phương pháp 1 (được khuyến nghị): Tin nhắn @userinfobot — nó sẽ trả lời ngay lập tức bằng ID người dùng của bạn.

Phương pháp 2: Tin nhắn @get_id_bot — một tùy chọn đáng tin cậy khác.

Lưu số này; bạn sẽ cần nó cho bước tiếp theo.

Bước 5: Cấu hình Hermes

Tùy chọn A: Thiết lập tương tác (Được khuyến nghị)​

hermes gateway setup

Chọn Telegram khi được nhắc. Trình hướng dẫn sẽ yêu cầu mã thông báo bot và ID người dùng được phép của bạn, sau đó viết cấu hình cho bạn.

Tùy chọn B: Cấu hình thủ công​

Thêm phần sau vào ~/.hermes/.env :

TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrSTUvwxYZ
TELEGRAM_ALLOWED_USERS=123456789    

# Comma-separated for multiple users

Khởi động cổng​

hermes gateway

Bot sẽ trực tuyến trong vòng vài giây. Gửi tin nhắn trên Telegram để xác minh.

Chế độ Webhook

Theo mặc định, Hermes kết nối với Telegram bằng cách bỏ phiếu dài — cổng gửi yêu cầu gửi đi tới máy chủ của Telegram để tìm nạp các bản cập nhật mới. Điều này hoạt động tốt cho việc triển khai cục bộ và luôn luôn.

Đối với triển khai trên đám mây (Fly.io, Railway, Render, v.v.), chế độ webhook sẽ tiết kiệm chi phí hơn. Các nền tảng này có thể tự động đánh thức các máy bị treo trên lưu lượng HTTP gửi đến, nhưng không tự động đánh thức các kết nối gửi đi. Vì cuộc bỏ phiếu được gửi đi nên bot bỏ phiếu không bao giờ có thể ngủ. Chế độ Webhook thay đổi hướng — Telegram đẩy các bản cập nhật lên URL HTTPS của bot của bạn, cho phép triển khai ở chế độ ngủ khi không hoạt động.

Bỏ phiếu (mặc định)Webhook
HướngCổng → Telegram (gửi đi)Telegram → Cổng (vào)
Tốt nhất choMáy chủ cục bộ, luôn hoạt độngNền tảng đám mây có tính năng tự động đánh thức
Thiết lậpKhông có cấu hình bổ sungĐặt TELEGRAM_WEBHOOK_URL
Chi phí nhàn rỗiMáy phải tiếp tục chạyMáy có thể ngủ giữa các tin nhắn

Cấu hình​

Thêm phần sau vào ~/.hermes/.env :

TELEGRAM_WEBHOOK_URL=https://my-app.fly.dev/telegram
# TELEGRAM_WEBHOOK_PORT=8443        

# optional, default 8443
# TELEGRAM_WEBHOOK_SECRET=mysecret  

# optional, recommended

BiếnBắt buộcMô tả
TELEGRAM_WEBHOOK_URLCóURL HTTPS công khai nơi Telegram sẽ gửi thông tin cập nhật. Đường dẫn URL được trích xuất tự động (ví dụ: /telegram từ ví dụ trên).
TELEGRAM_WEBHOOK_PORTKhôngCổng cục bộ mà máy chủ webhook lắng nghe (mặc định: 8443 ).
TELEGRAM_WEBHOOK_SECRETKhôngMã thông báo bí mật để xác minh rằng các bản cập nhật thực sự đến từ Telegram. Rất khuyến khích cho việc triển khai sản xuất.

Khi TELEGRAM_WEBHOOK_URL được đặt, cổng sẽ khởi động máy chủ webhook HTTP thay vì bỏ phiếu. Khi không được đặt, chế độ thăm dò ý kiến ​​sẽ được sử dụng — không có thay đổi nào về hành vi so với các phiên bản trước.

Ví dụ triển khai đám mây (Fly.io)​

  1. Thêm các biến env vào bí mật ứng dụng Fly.io của bạn:
fly secrets set TELEGRAM_WEBHOOK_URL=https://my-app.fly.dev/telegram
fly secrets set TELEGRAM_WEBHOOK_SECRET=$(openssl rand -hex 32)

  1. Hiển thị cổng webhook trong fly.toml :
[[services]]
  internal_port = 8443
  protocol = "tcp"

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

  1. Triển khai:
fly deploy

Nhật ký cổng sẽ hiển thị: [telegram] Connected to Telegram (webhook mode) .

Kênh chủ

Sử dụng lệnh /sethome trong bất kỳ cuộc trò chuyện Telegram (DM hoặc nhóm) nào để chỉ định kênh đó làm kênh chính. Các tác vụ đã lên lịch (cron jobs) phân phối kết quả của chúng tới kênh này.

Bạn cũng có thể đặt thủ công trong ~/.hermes/.env :

TELEGRAM_HOME_CHANNEL=-1001234567890
TELEGRAM_HOME_CHANNEL_NAME="My Notes"

mẹo

ID trò chuyện nhóm là số âm (ví dụ: -1001234567890 ). ID trò chuyện DM cá nhân của bạn giống với ID người dùng của bạn.

Tin nhắn thoại

Giọng nói đến (Chuyển giọng nói thành văn bản)Tin nhắn thoại bạn gửi trên Telegram được nhà cung cấp STT đã định cấu hình của Hermes tự động phiên âm và đưa dưới dạng văn bản vào cuộc trò chuyện.​

  • local sử dụng faster-whisper trên máy chạy Hermes — không cần khóa API
  • groq sử dụng Groq Whisper và yêu cầu GROQ_API_KEY
  • openai sử dụng OpenAI Whisper và yêu cầu VOICE_TOOLS_OPENAI_KEY

Giọng nói đi (Chuyển văn bản thành giọng nói)​

Khi tác nhân tạo âm thanh qua TTS, âm thanh đó sẽ được phân phối dưới dạng Telegram gốc bong bóng thoại — loại tròn, có thể phát nội tuyến.

  • OpenAI và ElevenLabs sản xuất Opus nguyên bản — không cần thiết lập thêm
  • Edge TTS (nhà cung cấp miễn phí mặc định) xuất MP3 và yêu cầu ffmpeg để chuyển đổi sang Opus:
# Ubuntu/Debian
sudo apt install ffmpeg

# macOS
brew install ffmpeg

Nếu không có ffmpeg, âm thanh Edge TTS sẽ được gửi dưới dạng tệp âm thanh thông thường (vẫn có thể phát nhưng sử dụng trình phát hình chữ nhật thay vì bong bóng thoại).

Định cấu hình nhà cung cấp TTS trong config.yaml của bạn dưới khóa tts.provider.

Cách sử dụng trò chuyện nhóm

Hermes Agent hoạt động trong cuộc trò chuyện nhóm Telegram với một số điều cần cân nhắc:

  • Chế độ bảo mật xác định những thông báo mà bot có thể nhìn thấy (xem Bước 3)
  • TELEGRAM_ALLOWED_USERS vẫn được áp dụng — chỉ những người dùng được ủy quyền mới có thể kích hoạt bot, ngay cả trong nhóm
  • Bạn có thể ngăn bot phản hồi cuộc trò chuyện nhóm thông thường bằng telegram.require_mention: true
  • Với telegram.require_mention: true , tin nhắn nhóm được chấp nhận khi chúng:
    • lệnh gạch chéo
    • trả lời một trong các tin nhắn của bot
    • @botusername đề cập
    • khớp với một trong các từ đánh thức biểu thức chính quy được định cấu hình của bạn trong telegram.mention_patterns
  • Nếu telegram.require_mention không được đặt hoặc sai, Hermes sẽ giữ nguyên hành vi nhóm mở trước đó và phản hồi các tin nhắn nhóm bình thường mà nó có thể thấy

Ví dụ về cấu hình kích hoạt nhóm​

Thêm phần này vào ~/.hermes/config.yaml :

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

Ví dụ này cho phép tất cả các trình kích hoạt trực tiếp thông thường cộng với các tin nhắn bắt đầu bằng chompy , ngay cả khi chúng không sử dụng @mention .

Ghi chú về mention_patterns​

  • Các mẫu sử dụng biểu thức chính quy Python
  • So khớp không phân biệt chữ hoa chữ thường
  • Các mẫu được kiểm tra đối với cả tin nhắn văn bản và chú thích phương tiện
  • Các mẫu biểu thức chính quy không hợp lệ sẽ bị bỏ qua kèm theo cảnh báo trong nhật ký cổng thay vì làm hỏng bot
  • Nếu bạn muốn một mẫu chỉ khớp ở đầu tin nhắn, hãy neo mẫu đó bằng ^

Chủ đề trò chuyện riêng tư (Bot API 9.4)

Telegram Bot API 9.4 (tháng 2 năm 2026) đã giới thiệu Chủ đề trò chuyện riêng tư - bot có thể tạo chủ đề theo kiểu diễn đàn trực tiếp trong cuộc trò chuyện DM 1-1, không cần siêu nhóm. Điều này cho phép bạn chạy nhiều không gian làm việc biệt lập trong DM hiện có của mình với Hermes.

Trường hợp sử dụng​

Nếu bạn làm việc trên một số dự án dài hạn, các chủ đề sẽ tách biệt bối cảnh của chúng:

  • Chủ đề "Trang web" — làm việc trên dịch vụ web sản xuất của bạn
  • Chủ đề "Nghiên cứu" — xem xét tài liệu và khám phá tài liệu
  • Chủ đề "Chung" — các nhiệm vụ linh tinh và câu hỏi nhanh

Mỗi chủ đề có phiên trò chuyện, lịch sử và bối cảnh riêng - hoàn toàn tách biệt với các chủ đề khác.

Cấu hình​

Thêm chủ đề dưới platforms.telegram.extra.dm_topics trong ~/.hermes/config.yaml :

platforms:
  telegram:
    extra:
      dm_topics:
      - chat_id: 123456789        

# Your Telegram user ID
        topics:
        - name: General
          icon_color: 7322096
        - name: Website
          icon_color: 9367192
        - name: Research
          icon_color: 16766590
          skill: arxiv              

# Auto-load a skill in this topic

Các trường:

Lĩnh vựcBắt buộcMô tả
nameCóTên hiển thị chủ đề
icon_colorKhôngMã màu biểu tượng Telegram (số nguyên)
icon_custom_emoji_idKhôngID biểu tượng cảm xúc tùy chỉnh cho biểu tượng chủ đề
skillKhôngKỹ năng tự động tải các phiên mới trong chủ đề này
thread_idKhôngTự động điền sau khi tạo chủ đề - không đặt thủ công

Cách thức hoạt động​

  1. Khi khởi động cổng, Hermes gọi createForumTopic cho mỗi chủ đề chưa có thread_id
  2. thread_id được tự động lưu trở lại config.yaml — những lần khởi động lại tiếp theo sẽ bỏ qua lệnh gọi API
  3. Mỗi chủ đề ánh xạ tới một khóa phiên riêng biệt: agent:main:telegram:dm:{chat_id}:{thread_id}
  4. Tin nhắn trong mỗi chủ đề có lịch sử hội thoại, bộ nhớ xóa và cửa sổ ngữ cảnh riêng

Ràng buộc kỹ năng​

Các chủ đề có trường skill sẽ tự động tải kỹ năng đó khi phiên mới bắt đầu trong chủ đề. Điều này hoạt động giống hệt như việc nhập /skill-name khi bắt đầu cuộc trò chuyện — nội dung kỹ năng được đưa vào tin nhắn đầu tiên và các tin nhắn tiếp theo sẽ thấy nội dung đó trong lịch sử cuộc trò chuyện.

Ví dụ: một chủ đề có skill: arxiv sẽ được tải sẵn kỹ năng arxiv bất cứ khi nào phiên của nó được đặt lại (do hết thời gian chờ, đặt lại hàng ngày hoặc thủ công /reset ).

mẹo

Các chủ đề được tạo bên ngoài cấu hình (ví dụ: bằng cách gọi API Telegram theo cách thủ công) sẽ tự động được phát hiện khi có thông báo dịch vụ forum_topic_created đến. Bạn cũng có thể thêm chủ đề vào cấu hình trong khi cổng đang chạy — chúng sẽ được chọn trong lần bỏ lỡ bộ nhớ đệm tiếp theo.

Liên kết kỹ năng chủ đề diễn đàn nhóm

Siêu nhóm đã bật Chế độ chủ đề (còn gọi là "chủ đề diễn đàn") đã có phiên cách ly cho mỗi chủ đề — mỗi thread_id ánh xạ tới cuộc trò chuyện riêng của mình. Nhưng bạn có thể muốn tự động tải một kỹ năng khi tin nhắn đến một chủ đề nhóm cụ thể, giống như cách hoạt động của tính năng liên kết kỹ năng chủ đề DM.

Trường hợp sử dụng​

Một nhóm siêu nhóm với các chủ đề diễn đàn dành cho các luồng công việc khác nhau:

  • Chủ đề Kỹ thuật → tự động tải kỹ năng software-development
  • Chủ đề Nghiên cứu → tự động tải kỹ năng arxiv
  • Chủ đề chung → không có kỹ năng, trợ lý đa năng

Cấu hình​

Thêm các ràng buộc chủ đề dưới platforms.telegram.extra.group_topics trong ~/.hermes/config.yaml :

platforms:
  telegram:
    extra:
      group_topics:
      - chat_id: -1001234567890       

# Supergroup ID
        topics:
        - name: Engineering
          thread_id: 5
          skill: software-development
        - name: Research
          thread_id: 12
          skill: arxiv
        - name: General
          thread_id: 1
          

# No skill — general purpose

Các trường:

Lĩnh vựcBắt buộcMô tả
chat_idCóID số của siêu nhóm (số âm bắt đầu bằng -100 )
nameKhôngNhãn mà con người có thể đọc được cho chủ đề (chỉ mang tính thông tin)
thread_idCóID chủ đề diễn đàn Telegram — hiển thị trong liên kết t.me/c/<group_id>/<thread_id>
skillKhôngKỹ năng tự động tải các phiên mới trong chủ đề này

Cách thức hoạt động1. Khi có tin nhắn đến trong chủ đề nhóm được ánh xạ, Hermes tra cứu chat_id và thread_id trong cấu hình group_topics​

  1. Nếu mục nhập phù hợp có trường skill, thì kỹ năng đó sẽ được tải tự động cho phiên — giống với ràng buộc kỹ năng chủ đề DM
  2. Các chủ đề không có khóa skill chỉ bị cô lập phiên (hành vi hiện tại, không thay đổi)
  3. Giá trị thread_id chưa được ánh xạ hoặc giá trị chat_id rơi vào âm thầm — không có lỗi, không có kỹ năng

Sự khác biệt so với chủ đề DM​

Chủ đề DMChủ đề nhóm
Phím cấu hìnhextra.dm_topicsextra.group_topics
Tạo chủ đềHermes tạo chủ đề qua API nếu thiếu thread_idQuản trị viên tạo chủ đề trong giao diện người dùng Telegram
thread_idTự động điền sau khi tạoPhải được đặt thủ công
icon_color / icon_custom_emoji_idĐược hỗ trợKhông áp dụng (quản trị viên kiểm soát giao diện)
Ràng buộc kỹ năng✓✓
Cách ly phiên✓✓ (đã được tích hợp sẵn cho các chủ đề diễn đàn)
mẹo

Để tìm thread_id của một chủ đề, hãy mở chủ đề đó trên Telegram Web hoặc Desktop và xem URL: https://t.me/c/1234567890/5 — số cuối cùng ( 5 ) là thread_id . chat_id cho siêu nhóm là ID nhóm có tiền tố -100 (ví dụ: nhóm 1234567890 trở thành -1001234567890 ).

Tính năng API Bot gần đây

  • Bot API 9.4 (Tháng 2 năm 2026): Chủ đề trò chuyện riêng tư — bot có thể tạo chủ đề diễn đàn trong cuộc trò chuyện trực tiếp 1-1 thông qua createForumTopic . Xem Chủ đề trò chuyện riêng tư ở trên.
  • Chính sách quyền riêng tư: Telegram hiện yêu cầu bot phải có chính sách quyền riêng tư. Đặt một cái qua BotFather với /setprivacy_policy hoặc Telegram có thể tự động tạo trình giữ chỗ. Điều này đặc biệt quan trọng nếu bot của bạn được công khai.
  • Truyền phát tin nhắn: Bot API 9.x đã bổ sung tính năng hỗ trợ truyền phát các phản hồi dài, có thể cải thiện độ trễ nhận thấy đối với các phản hồi dài của tổng đài viên.

Bộ chọn mô hình tương tác

Khi bạn gửi /model mà không có đối số trong cuộc trò chuyện Telegram, Hermes sẽ hiển thị bàn phím nội tuyến tương tác để chuyển đổi mô hình:

  1. Lựa chọn nhà cung cấp — các nút hiển thị từng nhà cung cấp có sẵn cùng với số lượng mô hình (ví dụ: "OpenAI (15)", " ✓ Anthropic (12)" cho nhà cung cấp hiện tại).
  2. Lựa chọn mô hình — danh sách mô hình được phân trang với điều hướng Trước/Tiếp theo, nút Quay lại để quay lại nhà cung cấp và Hủy.

Mô hình và nhà cung cấp hiện tại được hiển thị ở trên cùng. Tất cả điều hướng diễn ra bằng cách chỉnh sửa cùng một tin nhắn tại chỗ (không có sự lộn xộn trong cuộc trò chuyện).

mẹo

Nếu bạn biết tên mẫu chính xác, hãy nhập trực tiếp /model <name> để bỏ qua bộ chọn. Bạn cũng có thể nhập /model <name> --global để duy trì thay đổi qua các phiên.

Chế độ Webhook

Theo mặc định, bộ điều hợp Telegram kết nối thông qua bỏ phiếu dài — cổng tạo các kết nối gửi đi tới máy chủ của Telegram. Điều này hoạt động ở mọi nơi nhưng vẫn giữ kết nối liên tục mở.Chế độ Webhook là một giải pháp thay thế trong đó Telegram đẩy các bản cập nhật lên máy chủ của bạn qua HTTPS. Điều này lý tưởng cho triển khai trên nền tảng đám mây và không có máy chủ (Fly.io, Railway, v.v.), trong đó HTTP gửi đến có thể đánh thức một máy bị treo.

Cấu hình​

Đặt biến môi trường TELEGRAM_WEBHOOK_URL để bật chế độ webhook:

# Required — your public HTTPS endpoint
TELEGRAM_WEBHOOK_URL=https://app.fly.dev/telegram

# Optional — local listen port (default: 8443)
TELEGRAM_WEBHOOK_PORT=8443

# Optional — secret token for update verification (auto-generated if not set)
TELEGRAM_WEBHOOK_SECRET=my-secret-token

Hoặc trong ~/.hermes/config.yaml :

telegram:
  webhook_mode: true

Khi TELEGRAM_WEBHOOK_URL được đặt, cổng sẽ khởi động máy chủ HTTP đang lắng nghe 0.0.0.0:<port> và đăng ký URL webhook với Telegram. Đường dẫn URL được trích xuất từ ​​URL webhook (mặc định là /telegram ).

cảnh báo

Telegram yêu cầu chứng chỉ TLS hợp lệ trên điểm cuối webhook. Chứng chỉ tự ký sẽ bị từ chối. Sử dụng proxy ngược (nginx, Caddy) hoặc nền tảng cung cấp tính năng chấm dứt TLS (Fly.io, Railway, Cloudflare Tunnel).

IP dự phòng DNS qua HTTPS

Trong một số mạng bị hạn chế, api.telegram.org có thể phân giải thành IP không thể truy cập được. Bộ điều hợp Telegram bao gồm cơ chế IP dự phòng giúp thử lại các kết nối một cách minh bạch với các IP thay thế trong khi vẫn giữ nguyên tên máy chủ TLS và SNI chính xác.

Cách thức hoạt động​

  1. Nếu TELEGRAM_FALLBACK_IPS được đặt, các IP đó sẽ được sử dụng trực tiếp.
  2. Nếu không, bộ điều hợp sẽ tự động truy vấn Google DNS và Cloudflare DNS thông qua DNS-over-HTTPS (DoH) để khám phá các IP thay thế cho api.telegram.org .
  3. IP do DoH trả về khác với kết quả DNS của hệ thống sẽ được sử dụng làm dự phòng.
  4. Nếu DoH cũng bị chặn, IP hạt giống được mã hóa cứng ( 149.154.167.220 ) sẽ được sử dụng như là phương sách cuối cùng.
  5. Sau khi IP dự phòng thành công, nó sẽ trở nên "dính" — các yêu cầu tiếp theo sẽ sử dụng trực tiếp IP đó mà không cần thử lại đường dẫn chính trước.

Cấu hình​

# Explicit fallback IPs (comma-separated)
TELEGRAM_FALLBACK_IPS=149.154.167.220,149.154.167.221

Hoặc trong ~/.hermes/config.yaml :

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

mẹo

Bạn thường không cần phải cấu hình thủ công. Tính năng tự động phát hiện thông qua DoH xử lý hầu hết các tình huống mạng bị hạn chế. TELEGRAM_FALLBACK_IPS env var chỉ cần thiết nếu DoH cũng bị chặn trên mạng của bạn.

Hỗ trợ proxy

Nếu mạng của bạn yêu cầu proxy HTTP để truy cập internet (phổ biến trong môi trường công ty), bộ điều hợp Telegram sẽ tự động đọc các biến môi trường proxy tiêu chuẩn và định tuyến tất cả các kết nối thông qua proxy.

Các biến được hỗ trợ​

Bộ điều hợp sẽ kiểm tra các biến môi trường này theo thứ tự, sử dụng biến môi trường đầu tiên được đặt:

  1. HTTPS_PROXY
  2. HTTP_PROXY
  3. ALL_PROXY
  4. https_proxy / http_proxy / all_proxy (các biến thể chữ thường)

Cấu hình​

Đặt proxy trong môi trường của bạn trước khi khởi động cổng:

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

Hoặc thêm nó vào ~/.hermes/.env :

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

Proxy áp dụng cho cả truyền tải chính và tất cả các truyền tải IP dự phòng. Không cần cấu hình Hermes bổ sung — nếu biến môi trường được đặt, biến đó sẽ tự động được sử dụng.

ghi chú

Điều này bao gồm lớp truyền tải dự phòng tùy chỉnh mà Hermes sử dụng cho các kết nối Telegram. Ứng dụng khách httpx tiêu chuẩn được sử dụng ở nơi khác vốn đã tôn trọng các biến env proxy.

Phản hồi về tin nhắnBot có thể thêm phản ứng biểu tượng cảm xúc vào tin nhắn dưới dạng phản hồi xử lý hình ảnh:

  • 👀 khi bot bắt đầu xử lý tin nhắn của bạn
  • ✅ khi phản hồi được gửi thành công
  • ❌ nếu xảy ra lỗi trong quá trình xử lý

Phản ứng được tắt theo mặc định. Kích hoạt chúng trong config.yaml :

telegram:
  reactions: true

Hoặc thông qua biến môi trường:

TELEGRAM_REACTIONS=true

ghi chú

Không giống như Discord (trong đó các phản ứng được bổ sung), API Bot của Telegram thay thế tất cả các phản ứng của bot trong một cuộc gọi duy nhất. Quá trình chuyển đổi từ 👀 sang ✅/❌ xảy ra một cách nguyên tử — bạn sẽ không nhìn thấy cả hai cùng một lúc.

mẹo

Nếu bot không có quyền thêm phản ứng vào nhóm thì cuộc gọi phản ứng sẽ không thành công và quá trình xử lý tin nhắn vẫn tiếp tục bình thường.

Khắc phục sự cố

Vấn đềGiải pháp
Bot không phản hồi gì cảXác minh TELEGRAM_BOT_TOKEN là chính xác. Kiểm tra nhật ký hermes gateway để tìm lỗi.
Bot phản hồi bằng "trái phép"ID người dùng của bạn không có trong TELEGRAM_ALLOWED_USERS . Kiểm tra kỹ với @userinfobot.
Bot bỏ qua tin nhắn nhómChế độ bảo mật có thể đang bật. Tắt nó (Bước 3) hoặc đặt bot làm quản trị viên nhóm. Hãy nhớ xóa và thêm lại bot sau khi thay đổi quyền riêng tư.
Tin nhắn thoại không được phiên âmXác minh STT có sẵn: cài đặt faster-whisper để phiên âm cục bộ hoặc đặt GROQ_API_KEY / VOICE_TOOLS_OPENAI_KEY trong ~/.hermes/.env .
Trả lời bằng giọng nói là tập tin, không phải bong bóngCài đặt ffmpeg (cần thiết để chuyển đổi Edge TTS Opus).
Mã thông báo bot bị thu hồi/không hợp lệTạo mã thông báo mới qua /revoke sau đó /newbot hoặc /token trong BotFather. Cập nhật tệp .env của bạn.
Webhook không nhận được cập nhậtXác minh TELEGRAM_WEBHOOK_URL có thể truy cập công khai (kiểm tra với curl ). Đảm bảo nền tảng/proxy ngược của bạn định tuyến lưu lượng HTTPS gửi đến từ cổng của URL đến cổng nghe cục bộ được định cấu hình bởi TELEGRAM_WEBHOOK_PORT (chúng không cần phải có cùng số). Đảm bảo SSL/TLS đang hoạt động — Telegram chỉ gửi tới URL HTTPS. Kiểm tra các quy tắc tường lửa.

Phê duyệt của người điều hành

Khi tác nhân cố gắng chạy một lệnh tiềm ẩn nguy hiểm, nó sẽ yêu cầu bạn phê duyệt trong cuộc trò chuyện:

⚠️ Lệnh này có khả năng nguy hiểm (xóa đệ quy). Trả lời "có" để phê duyệt.

Trả lời “có”/”y” để đồng ý hoặc “không”/”n” để từ chối.

Bảo mật

cảnh báo

Luôn đặt TELEGRAM_ALLOWED_USERS để hạn chế người có thể tương tác với bot của bạn. Nếu không có nó, cổng mặc định sẽ từ chối tất cả người dùng như một biện pháp an toàn.

Không bao giờ chia sẻ mã thông báo bot của bạn một cách công khai. Nếu bị xâm phạm, hãy thu hồi nó ngay lập tức thông qua lệnh /revoke của BotFather.

Để biết thêm chi tiết, hãy xem Tài liệu bảo mật. Bạn cũng có thể sử dụng ghép nối DM để có cách tiếp cận năng động hơn trong việc ủy ​​quyền người dùng.