Cài đặt Telegram

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. 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.
Mở Telegram và tìm kiếm @BotFather hoặc truy cập t.me/BotFather
Gửi
/newbot
Chọn tên hiển thị (ví dụ: "Đặc vụ Hermes") — đây có thể là bất kỳ tên nào
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ệnh	Mục đích
/setdescription ` | Câ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 | |
/setabouttext ` | Văn bản ngắn trên trang hồ sơ của bot | |
/setuserpic ` | Tải lên hình đại diện cho bot của bạn | |
/setcommands ` | Xác định menu lệnh (nút
/ ` trong trò chuyện) | |
/setprivacy ` | Kiể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ư

Tin nhắn @BotFather
Gửi
/mybots
Chọn bot của bạn
Đ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.
Quan sát cuộc trò chuyện nhóm mà không trả lời tự động

Đối với hành vi nhóm kiểu OpenClaw/Yuanbao, hãy định cấu hình Telegram để bot có thể xem tin nhắn nhóm thông thường nhưng chỉ phản hồi khi được kích hoạt trực tiếp:
Telegram:
  allowed_chats:

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

`
``Khi bật chế độ này, các tin nhắn nhóm chưa được đề cập từ các cuộc trò chuyện/chủ đề được đưa vào danh sách cho phép rõ ràng sẽ được thêm vào bản chép lại phiên trò chuyện/chủ đề được chia sẻ dưới dạng bối cảnh được quan sát, nhưng chúng không gửi tổng đài viên. Cổng 
`allowed_chats
` nơi bot phản hồi; 
`group_allowed_chats
` cho phép phiên nhóm chia sẻ được sử dụng cho bối cảnh được quan sát, vì vậy hãy sử dụng cùng ID trò chuyện cho chế độ này. Đề cập, trả lời bot hoặc mẫu đề cập được định cấu hình 

@botname
` sau này trong cùng một cuộc trò chuyện/chủ đề trong danh sách cho phép có thể sử dụng bối cảnh được quan sát đó. Thông báo được kích hoạt cũng được gắn thẻ 

[nickname|user_id]
` và nhận được lời nhắc an toàn mỗi lượt để mô hình xử lý các dòng được quan sát trước đó dưới dạng ngữ cảnh chứ không phải hướng dẫn gửi đến bot.

Biến môi trường tương đương:

``` bash
Telegram_ALLOWED_CHATS=-1001234567890
Telegram_GROUP_ALLOWED_CHATS=-1001234567890
Telegram_OBSERVE_UNMENTIONED_GROUP_MESSAGES=true

`
``Điều này yêu cầu Telegram gửi tin nhắn nhóm thông thường đến cổng, vì vậy hãy tắt chế độ quyền riêng tư của BotFather hoặc thăng cấp bot lên quản trị viên nhóm như mô tả ở trên.

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

Đại lý Hermes 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](https://t.me/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](https://t.me/get_id_bot) — một lựa 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ị)

`bash
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

:

`bash
Telegram_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrSTUvwxYZ
Telegram_ALLOWED_USERS=123456789    # Comma-separated for multiple users

`

### Khởi động cổng

`bash
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.

## Gửi các tệp được tạo từ các terminal được Docker hỗ trợ

Nếu phần phụ trợ terminal của bạn là 
`Docker

, hãy nhớ rằng các tệp đính kèm Telegram là
được gửi bởi **quy trình cổng**, không phải từ bên trong vùng chứa. Điều đó có nghĩa là
đường dẫn 
`MEDIA:/...
` cuối cùng phải có thể đọc được trên máy chủ có cổng
đang chạy.

Cạm bẫy thường gặp:
- tác nhân ghi một tệp bên trong Docker vào 

/workspace/report.txt

`
- mô hình phát ra 
`MEDIA:/workspace/report.txt

- Việc gửi Telegram không thành công vì 

/workspace/report.txt
` chỉ tồn tại bên trong
  container, không phải trên máy chủ

Mẫu đề xuất:

``` yaml
terminal:
  backend: Docker
  Docker_volumes:

    - "/home/user/.Hermes/cache/documents:/output"

`
``Sau đó:
- ghi các tập tin bên trong Docker vào 

/output/...

- phát ra đường dẫn **host-visible** trong 
`MEDIA:

, ví dụ:

MEDIA:/home/user/.Hermes/cache/documents/report.txt
``Nếu bạn đã có phần 
`Docker_volumes:

, hãy thêm giá đỡ mới vào cùng phần đó
danh sách. Các khóa trùng lặp YAML âm thầm ghi đè các khóa trước đó.

### Phần mở rộng tệp 
`MEDIA:
` được hỗ trợ

Cổng trích xuất các thẻ 
`MEDIA:/path/to/file
` từ các phản hồi của tổng đài viên và gửi tệp được tham chiếu dưới dạng tệp đính kèm gốc của nền tảng. Các tiện ích mở rộng được hỗ trợ trên tất cả các nền tảng cổng:

| Danh mục | Tiện ích mở rộng |
|---|---|
| Hình ảnh |

png

, 
`jpg

, 
`jpeg

, 
`gif

, 
`webp

, 
`bmp

, 
`tiff

, 
`svg
` |
| Âm thanh |

mp3

, 
`wav

, 
`ogg

, 
`m4a

, 
`opus

, 
`flac

, 
`aac
` |
| Video |

mp4

, 
`mov

, 
`webm

, 
`mkv

, 
`avi
` |
| **Tài liệu** |

pdf

, 
`txt

, 
`md

, 
`csv

, 
``` json

, 
`xml

, 
`html

, 
`YAML

, 
`yml

, 
`log
` |
| **Văn phòng** |

docx

, 
`xlsx

, 
`pptx

, 
`odt

, 
`ods

, 
`odp
` |
| **Lưu trữ** |

zip

, 
`rar

, 
`7z

, 
`tar

, 
`gz

, 
`bz2
` |
| **Sách / gói** |

epub

, 
`apk

, 
`ipa
` |

Mọi nội dung trong danh sách này được phân phối dưới dạng tệp đính kèm gốc trên các nền tảng hỗ trợ nó (Telegram, Discord, Signal, Slack, WhatsApp, Feishu, Matrix, v.v.); trên các nền tảng không có hỗ trợ riêng, nó sẽ quay trở lại một liên kết hoặc chỉ báo văn bản thuần túy. Các danh mục **đậm** đã được thêm vào trong một số bản phát hành gần đây — thay vào đó, nếu bạn đang dựa vào mô hình có nội dung 
`here is the file: /path/to/report.docx

, hãy chuyển sang 
`MEDIA:/path/to/report.docx
` để phân phối gốc.

## 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 thể 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ướng | Cổng → Telegram (gửi đi) | Telegram → Cổng (vào) |
| Tốt nhất cho | Máy chủ cục bộ, luôn hoạt động | Nền tảng đám mây có tính năng tự động đánh thức |
| Thiết lập | Không có cấu hình bổ sung | Đặt 
`Telegram_WEBHOOK_URL
` |
| Chi phí nhàn rỗi | Máy phải tiếp tục chạy | Máy có thể ngủ giữa các tin nhắn |

### Cấu hình

Thêm phần sau vào 

~/.Hermes/.env

:

`bash
Telegram_WEBHOOK_URL=https://my-app.fly.dev/Telegram
Telegram_WEBHOOK_SECRET="$(openSSL rand -hex 32)"  # required

# Telegram_WEBHOOK_PORT=8443        # optional, default 8443

`

| Biến | Bắt buộc | Mô tả |
|----------|----------|-------------|
| 
`Telegram_WEBHOOK_URL
` | Có | 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_SECRET
` | **Có** (khi 
`Telegram_WEBHOOK_URL
` được đặt) | Mã thông báo bí mật mà Telegram lặp lại trong mọi yêu cầu xác minh webhook. Cổng từ chối khởi động nếu không có nó - xem [GHSA-3vpc-7q5r-276h](https://GitHub.com/NousResearch/Hermes-agent/security/advisories/GHSA-3vpc-7q5r-276h). Tạo bằng 
`openSSL rand -hex 32

. |
| 
`Telegram_WEBHOOK_PORT
` | Không | Cổng cục bộ mà máy chủ webhook lắng nghe (mặc định: 
`8443

). |

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:

``` bash
fly secrets set Telegram_WEBHOOK_URL=https://my-app.fly.dev/Telegram
fly secrets set Telegram_WEBHOOK_SECRET=$(openSSL rand -hex 32)

`

2. Hiển thị cổng webhook trong 
`fly.TOML
` của bạn:

`TOML
[[services]]
  internal_port = 8443
  protocol = "tcp"`[[services.ports]]
    handlers = ["TLS", "http"]
    port = 443

`

3. Triển khai:

`bash
fly deploy

`
``Nhật ký cổng sẽ hiển thị: 

[Telegram] Connected to Telegram (webhook mode)

.

## Hỗ trợ proxy

Nếu API của Telegram bị chặn hoặc bạn cần định tuyến lưu lượng truy cập qua proxy, hãy đặt URL proxy dành riêng cho Telegram. Điều này được ưu tiên hơn so với các biến env 
`HTTPS_PROXY
` / 
`HTTP_PROXY
` chung.

**Tùy chọn 1: config.yaml (được khuyến nghị)**

`YAML
Telegram:
  proxy_url: "socks5://127.0.0.1:1080"

`
``**Tùy chọn 2: biến môi trường**

`bash
Telegram_PROXY=socks5://127.0.0.1:1080

`
``Các chương trình được hỗ trợ: 
`http://

, 
`https://

, 
`socks5://

.

Proxy áp dụng cho cả kết nối Telegram chính và truyền tải IP dự phòng. Nếu không đặt proxy dành riêng cho Telegram, cổng sẽ quay trở lại 
`HTTPS_PROXY
` / 
`HTTP_PROXY
` / 
`ALL_PROXY
` (hoặc tự động phát hiện proxy hệ thống macOS).

## 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

:

`bash
Telegram_HOME_CHANNEL=-1001234567890
Telegram_HOME_CHANNEL_NAME="My Notes"

`

:::tip
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.
:::

### Phân phối định kỳ ở chế độ chủ đề

Nếu bạn đã bật chế độ chủ đề trong bot DM của mình, các tin nhắn cron sẽ được gửi đến vùng trò chuyện gốc trong sảnh chỉ dành cho hệ thống — việc trả lời ở đó sẽ không mở phiên nào và bạn sẽ thấy thông báo "cuộc trò chuyện chính được dành riêng cho các lệnh hệ thống". Tạo một chủ đề diễn đàn dành riêng (ví dụ: 
`Cron

) và đặt:

``` bash
Telegram_CRON_THREAD_ID=&lt;topic_thread_id

`
```Telegram_CRON_THREAD_ID
` ghi đè 
`Telegram_HOME_CHANNEL_THREAD_ID
` chỉ dành cho việc giao hàng định kỳ. Các câu trả lời trong chủ đề đó sẽ tiếp tục phiên hiện tại của chủ đề.

## 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 API key

- 
`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

#### Bỏ qua STT: chuyển file âm thanh raw cho tổng đài viên

Nếu bạn muốn **chính tác nhân** xử lý âm thanh — để ghi nhật ký, công cụ phiên âm tùy chỉnh hoặc chỉ lưu trữ bản ghi — hãy đặt 
`stt.enabled: false
` trong 

~/.Hermes/config.yaml

:

``` yaml
stt:
  enabled: false

`
``Khi STT bị tắt, cổng vẫn tải tệp đính kèm giọng nói/âm thanh xuống bộ nhớ đệm âm thanh của Hermes nhưng **không phiên âm nó**. Tác nhân nhận được tin nhắn có điểm đánh dấu như:

`
[The user sent a voice message: /home/&lt;user/.Hermes/cache/audio/&lt;hash.ogg]

`
``Sau đó, các công cụ hoặc kỹ năng của bạn có thể đọc trực tiếp đường dẫn đó (ví dụ: chuyển nó tới quy trình ghi nhật ký cục bộ, mô hình phiên âm phong phú hơn hoặc tải nó lên bộ lưu trữ dài hạn). Phần mở rộng tệp phản ánh định dạng ban đầu mà Telegram phân phối (

.ogg
` cho ghi chú thoại, 

.mp3

/

.m4a

/v.v. cho tệp đính kèm âm thanh).

Điều này kết hợp một cách tự nhiên với phần [local Bot API server](#large-files-20mb--via-local-bot-API-server) bên dưới, giúp nâng trần getFile 20MB của Telegram lên 2GB — hữu ích khi các bản ghi bạn muốn xử lý dài hơn vài phút.

### 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:

``` bash

# 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

.

## Tệp lớn (>20 MB) qua Máy chủ API Bot cục bộ

API Bot **công khai** của Telegram giới hạn lượt tải xuống 
`getFile
` ở mức **20 MB**, do đó, mọi ghi chú thoại, tệp âm thanh, video hoặc tài liệu lớn hơn mức đó sẽ bị Hermes âm thầm từ chối với câu trả lời "quá lớn". Cách được ghi lại để giải quyết vấn đề này là chạy daemon **cục bộ** [Telegram-bot-API](https://GitHub.com/tdlib/Telegram-bot-API) — cùng một phần mềm máy chủ mà Telegram sử dụng nhưng chạy trên mạng của bạn. Một máy chủ cục bộ tăng mức trần tệp lên **2 GB** và Hermes tự động nâng giới hạn bên trong của chính nó khi thấy 
`base_url
` tùy chỉnh được định cấu hình.

Điều này mở khóa các quy trình công việc như:
- Gửi bản ghi nhớ giọng nói dài (cuộc họp 45 phút, podcast) tới bot
- Tải lên các video lớn để xử lý công cụ thị giác
- Lưu trữ âm thanh thô cho các quy trình ngoại tuyến như dữ liệu nhật ký, căn chỉnh hoặc đào tạo

### Bước 1: Lấy thông tin đăng nhập API Telegram

Máy chủ cục bộ giao tiếp trực tiếp với lớp MTProto của Telegram (không phải API Bot công khai), vì vậy nó cần **thông tin đăng nhập MTProto**:
1. Truy cập [my.Telegram.org/apps](https://my.Telegram.org/apps) và đăng nhập bằng tài khoản Telegram của bạn.
2. Tạo một ứng dụng mới (bất kỳ tên nào và mô tả ngắn gọn đều được).
3. Sao chép 
`API_id
` và 
`API_hash

 - cả hai đều bắt buộc.

### Bước 2: Chạy máy chủ Telegram-bot-API

Hình ảnh Docker [XPROTECTX174XPROTECTX](https://hub.Docker.com/r/aiogram/Telegram-bot-API) do cộng đồng duy trì là đường dẫn dễ dàng nhất. 
`Docker-compose.YAML
` tối thiểu (sử dụng chế độ 

--local
` để kích hoạt các giới hạn cao hơn):

``` yaml
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"   # bind to loopback only; see security note
    environment:
      Telegram_API_ID: "12345"           # your API_id from Step 1
      Telegram_API_HASH: "abcdef..."     # your API_hash from Step 1
      Telegram_LOCAL: "1"                # enable --local mode (raises 20MB → 2GB)
    volumes:
      - ./tg-bot-API-data:/var/lib/Telegram-bot-API

`
``Đưa nó lên:

``` bash
Docker compose up -d tg-bot-API
Docker logs --tail 20 tg-bot-API

`

:::warning[Security]
Máy chủ API Bot cục bộ lấy mã thông báo bot của bạn trong đường dẫn URL (ví dụ: 

/bot&lt;TOKEN/getMe

) mà **không có xác thực bổ sung**. Bất kỳ ai có thể truy cập cổng đều có thể kiểm soát hoàn toàn bot của bạn - đọc mọi tin nhắn mà nó có thể nhìn thấy, gửi tin nhắn như vậy, v.v. Liên kết vùng chứa với 
`127.0.0.1
` và/hoặc đặt trước nó bằng một proxy ngược trên mạng riêng. **Không bao giờ để cổng 8081 tiếp xúc với Internet công cộng.**

:::

### Bước 3: Đăng xuất bot khỏi API công khai (một lần)

Một bot chỉ có thể hoạt động trên **một** máy chủ Bot API tại một thời điểm. Nếu bot của bạn đã chạy chống lại 
`API.Telegram.org
` (gần như chắc chắn là như vậy), bạn phải đăng xuất nó một cách rõ ràng trước khi máy chủ cục bộ chấp nhận nó:

``` bash
curl "https://API.Telegram.org/bot&lt;YOUR_BOT_TOKEN/logOut"

# expected response: \&#123;"ok":true,"result":true&#125;

`
``Đây là bước di chuyển chỉ thực hiện một lần — bạn không lặp lại bước này mỗi lần khởi động lại. Thay vào đó, Telegram sẽ gửi mọi tin nhắn nhận được sau 
`logOut
` thông qua máy chủ mới.

Xác minh máy chủ cục bộ có thể thay mặt bot nói chuyện với Telegram:

``` bash
curl "http://127.0.0.1:8081/bot&lt;YOUR_BOT_TOKEN/getMe"

# expected response: \&#123;"ok":true,"result":\&#123;"id":...,"is_bot":true,...&#125;&#125;

`

### Bước 4: Trỏ Hermes vào máy chủ cục bộ

Thêm các URL dưới 
`platforms.Telegram.extra
` trong 

~/.Hermes/config.yaml

:

``` 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        # see Step 5 below — only set this if the bot's data

                              # directory is readable by the Hermes process

`

:::caution[Use XPROTECTX183XPROTECTX, not XPROTECTX184XPROTECTX]
Hiện tại, chỉ có biểu mẫu 
`platforms.&lt;name.extra
` được tích hợp sâu vào cấu hình nền tảng. Các khóa được đặt ngay dưới khối 
`Telegram.extra
` cấp cao nhất sẽ được loại bỏ một cách âm thầm.
:::

Khi 
`base_url
` được đặt, Hermes:
- Xây dựng ứng dụng khách Python-Telegram-bot dựa trên máy chủ cục bộ
- Tự động nâng giới hạn kích thước tài liệu/âm thanh nội bộ từ 20 MB → 2 GB
- Báo cáo giới hạn hoạt động trong thông báo lỗi "quá lớn" (
`Maximum: 2048 MB.

) để biết rõ bạn đang ở chế độ nào

Khởi động lại cổng và tìm dòng nhật ký xác nhận:

``` bash
Hermes gateway restart
grep -E "Using custom Telegram base_url|Using Telegram local_mode" ~/.Hermes/logs/gateway.log | tail

`

### Bước 5: 
`local_mode
` — truy cập tập tin trên đĩa

Máy chủ cục bộ có **hai cách** để phân phối tệp:
1. **Không có 

`
--local

** (mặc định): các tệp được cung cấp qua HTTP tại 

/file/bot&lt;TOKEN/&lt;path

, giống như API Bot công khai. Mức trần 20 MB vẫn có hiệu lực. Chỉ hữu ích khi sửa lỗi mạng (ví dụ: khi không thể truy cập 
`API.Telegram.org
` nhưng bạn có thể tự lưu trữ); không phải những gì bạn muốn cho việc nâng kích thước.
2. **Với 

--local

** (được đặt qua 
`Telegram_LOCAL=1
` ở trên): các tệp được ghi vào hệ thống tệp của máy chủ và phản hồi 
`getFile
` trả về **đường dẫn tuyệt đối** thay vì URL HTTP. Mức trần 20 MB được dỡ bỏ. Sau đó, Hermes phải đọc các byte **từ đĩa**, không phải qua HTTP.Để làm cho đường dẫn đọc đĩa hoạt động, hãy đặt 
`local_mode: true
` trong cấu hình ở trên **và** đảm bảo quy trình Hermes có thể đọc đường dẫn mà máy chủ trả về. Hai kịch bản:
- **Cùng một máy** — Telegram-bot-API và Hermes chạy trên cùng một máy chủ. Liên kết khối lượng dữ liệu vào một thư mục mà Hermes có thể đọc (ví dụ: 

/var/lib/Telegram-bot-API

) và đảm bảo quyền sở hữu tệp phù hợp. Vùng chứa giảm các đặc quyền cho người dùng 
`Telegram-bot-API
` nội bộ của nó (uid thay đổi tùy theo hình ảnh); cách khắc phục đơn giản nhất là thêm 
`user: "&lt;UID:&lt;GID"
` vào dịch vụ soạn thư để các tệp thuộc sở hữu của uid Hermes đã chạy dưới dạng.
- **Các máy khác nhau** — máy chủ bot chạy trên một máy chủ (ví dụ: NAS, máy ảo riêng) và Hermes chạy trên một máy chủ khác. Thư mục dữ liệu của máy chủ phải được chia sẻ với máy Hermes theo **cùng một đường dẫn tuyệt đối** mà máy chủ báo cáo (thường là 

/var/lib/Telegram-bot-API

). NFS hoạt động tốt cho việc này; CIFS/SMB với ánh xạ lại gắn kết 
`uid=
` sẽ thân thiện hơn nếu bạn không muốn xử lý sự không khớp uid ở cấp hệ thống tệp.

Nếu 
`local_mode: true
` được đặt nhưng Hermes không thể 
`stat
` đường dẫn tệp được trả về (quyền hoặc kết nối sai), Python-Telegram-bot âm thầm quay trở lại HTTP 
`getFile
` đối với máy chủ cục bộ — máy chủ này ở chế độ 

--local
` sẽ phản hồi bằng 
`404 Not Found

. Triệu chứng xuất hiện trong 
`gateway.log
` là:

`
[Telegram] Failed to cache voice: Not Found
Telegram.error.InvalidToken: Not Found

`
``Nếu bạn thấy điều đó thì tính năng nâng giới hạn đang hoạt động nhưng tính năng chia sẻ tệp thì không. Xác minh 
`ls -la /var/lib/Telegram-bot-API/&lt;TOKEN/voice/
` từ máy chủ Hermes với tư cách là người dùng mà cổng chạy với tư cách đó và xác nhận một tệp duy nhất có thể sử dụng 
`cat
` mà không gặp lỗi về quyền.

### Bước 6: Kiểm tra

Gửi cho bot một ghi chú thoại hoặc tệp âm thanh lớn hơn 20 MB. Đuôi nhật ký cổng:

``` bash
tail -f ~/.Hermes/logs/gateway.log | grep -iE "Telegram|cache"

`
``Bạn sẽ thấy dòng 

[Telegram] Cached user voice at /home/&lt;user/.Hermes/cache/audio/...
` và **không** bị từ chối "quá lớn". Kết hợp với 
`stt.enabled: false
` (ở trên), đường dẫn đến tệp âm thanh gốc sẽ chuyển đến thông báo gửi đến của tác nhân để xử lý tiếp theo.

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

Đại lý Hermes 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 [Step 3](#step-3-privacy-mode-critical-for-groups))

- 
`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:
  - trả lời một trong các tin nhắn của bot
  - 

@botusername
` đề cập
  - 

/command@botusername
` (Mẫu lệnh menu bot của Telegram bao gồm tên bot)
  - 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

- Trong các nhóm có nhiều bot Hermes, 
`Telegram.exclusive_bot_mentions
` tiếp tục xác định định tuyến. Khi một thông báo đề cập rõ ràng đến một hoặc nhiều tên người dùng bot Telegram, chỉ các cấu hình bot được đề cập mới xử lý nó; các bot Hermes khác bỏ qua nó trước khi trả lời và chạy dự phòng từ đánh thức. Điều này được kích hoạt theo mặc định.
- Sử dụng 
`Telegram.ignored_threads
` để giữ im lặng cho Hermes trong các chủ đề cụ thể của diễn đàn Telegram, ngay cả khi nhóm cho phép phản hồi miễn phí hoặc phản hồi được kích hoạt đề cập
- 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

### Nhiều bot Hermes trong một nhóm

Nếu bạn chạy nhiều hồ sơ Hermes trong cùng một nhóm Telegram, hãy tạo một mã thông báo bot Telegram cho mỗi hồ sơ và bắt đầu một cổng cho mỗi hồ sơ. Không sử dụng lại cùng một mã thông báo bot trong nhiều cổng đang chạy; Telegram sẽ từ chối bỏ phiếu đồng thời cho cùng một mã thông báo.

Cấu hình nhóm được đề xuất:

``` yaml
Telegram:
  require_mention: true
  exclusive_bot_mentions: true
  mention_patterns: []

`
``Với thiết lập này, tin nhắn nhóm như 

@research_bot @ops_bot summarize this
` chỉ được xử lý bởi 
`research_bot
` và 
`ops_bot

. Các bot Hermes khác trong nhóm giữ im lặng, ngay cả khi tin nhắn là câu trả lời cho một trong những tin nhắn trước đó của chúng hoặc khớp với một từ đánh thức được chia sẻ.

Chỉ đặt 
`exclusive_bot_mentions: false
` cho các nhóm cũ trong đó các đề cập rõ ràng không được ghi đè lên trình kích hoạt phản hồi và từ đánh thức.

Để vận hành nhiều cấu hình, hãy chạy lệnh cổng một lần cho mỗi cấu hình. Ví dụ:

`bash

# default profile
Hermes gateway start
Hermes gateway status
Hermes gateway stop

# named profiles
Hermes -p research gateway start
Hermes -p research gateway status
Hermes -p research gateway stop

`
``Đối với một nhóm cố định nhỏ, hãy sử dụng vòng lặp shell hoặc tập lệnh gọi 
`Hermes gateway &lt;action
` cho cấu hình mặc định và 
`Hermes -p &lt;profile gateway &lt;action
` cho mỗi cấu hình được đặt tên. Điều này đáng tin cậy hơn việc giả sử một lệnh cấp quy trình duy nhất kiểm soát mọi cấu hình được đặt tên trên mọi trình quản lý dịch vụ.

### Khắc phục sự cố: hoạt động trong DM nhưng không hoạt động trong nhómNếu bot phản hồi trong cuộc trò chuyện riêng tư nhưng vẫn im lặng trong nhóm, hãy kiểm tra những điều này
cổng theo thứ tự:
1. **Gửi Telegram:** tắt chế độ riêng tư của BotFather, quảng cáo bot lên
   quản trị viên hoặc đề cập trực tiếp đến bot. Hermes không thể trả lời tin nhắn nhóm
   mà Telegram không bao giờ cung cấp cho bot.
2. **Tham gia lại sau khi thay đổi quyền riêng tư:** xóa bot khỏi nhóm và thêm nó
   một lần nữa sau khi thay đổi cài đặt quyền riêng tư của BotFather. Telegram có thể giữ cái cũ
   hành vi phân phối cho các thành viên hiện có.
3. **Ủy quyền của Hermes:** đảm bảo người gửi có tên trong``Telegram_ALLOWED_USERS
` hoặc 
`Telegram_GROUP_ALLOWED_USERS
` hoặc cho phép
   trò chuyện nhóm với 
`Telegram_GROUP_ALLOWED_CHATS

.
4. **Bộ lọc đề cập:** nếu 
`Telegram.require_mention: true
` được đặt, bình thường
   cuộc trò chuyện nhóm bị bỏ qua trừ khi tin nhắn là lệnh gạch chéo, hãy trả lời
   bot, đề cập đến 

@botusername
` hoặc khớp 
`mention_patterns
` được định cấu hình.
5. **Định tuyến nhiều bot:** nếu một nhóm chứa nhiều bot, hãy đảm bảo mỗi bot
   Hồ sơ Hermes sử dụng mã thông báo bot duy nhất và giữ 
`exclusive_bot_mentions

   được bật trừ khi bạn cố ý muốn hành vi kích hoạt chia sẻ kế thừa.

ID trò chuyện phủ định là điều bình thường đối với các nhóm Telegram và siêu nhóm. Nếu bạn sử dụng
ủy quyền trong phạm vi trò chuyện, hãy đặt các ID đó vào 
`Telegram_GROUP_ALLOWED_CHATS
` chứ không phải
danh sách cho phép người gửi-người dùng.

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

Thêm phần này vào 

~/.Hermes/config.yaml

:

``` yaml
Telegram:
  require_mention: true
  exclusive_bot_mentions: true
  mention_patterns:

    - "^\\s*chompy\\b"
  ignored_threads:
    - 31
    - "42"

`
``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

.
Các tin nhắn trong chủ đề Telegram 
`31
` và 
`42
` luôn bị bỏ qua trước khi chạy kiểm tra đề cập và phản hồi miễn phí.

### Những lưu ý 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 nó 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

:::caution[Prerequisites]
Trước khi thêm chủ đề vào cấu hình của bạn, người dùng phải **bật chế độ Chủ đề** trong cuộc trò chuyện DM với bot:
1. Mở cuộc trò chuyện riêng tư của bạn với bot Hermes trong Telegram
2. Nhấn vào tên bot ở trên cùng để mở thông tin trò chuyện
3. Bật **Chủ đề** (chuyển đổi để chuyển cuộc trò chuyện thành diễn đàn)

Nếu không có điều này, Hermes sẽ đăng nhập 
`The chat is not a forum
` khi khởi động và bỏ qua việc tạo chủ đề. Đây là cài đặt phía máy khách Telegram — bot không thể kích hoạt nó theo chương trình.
:::

Thêm chủ đề thuộc 
`platforms.Telegram.extra.dm_topics
` trong 

~/.Hermes/config.yaml

:

``` 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ực | Bắt buộc | Mô tả |
|-------|----------|-------------|
| 
`name
` | Có | Tên hiển thị chủ đề |
| 
`icon_color
` | Không | Mã màu biểu tượng Telegram (số nguyên) |
| 
`icon_custom_emoji_id
` | Không | ID biểu tượng cảm xúc tùy chỉnh cho biểu tượng chủ đề |
| 
`skill
` | Không | Kỹ năng tự động tải các phiên mới trong chủ đề này |
| 
`thread_id
` | Không | Tự độ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 từng 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:\&#123;chat_id&#125;:\&#123;thread_id&#125;

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

### Xử lý DM gốcTheo mặc định, các tin nhắn gửi đến DM gốc (ngoài chủ đề bất kỳ) đều được xử lý
bình thường. Đặt 
`ignore_root_dm: true
` để biến DM gốc thành sảnh — bình thường
tin nhắn được âm thầm bỏ qua đối với người dùng đã định cấu hình chủ đề DM, trong khi
các lệnh hệ thống (

/start

, 

/help

, 

/status

, v.v.) vẫn hoạt động.

``` yaml
platforms:
  Telegram:
    extra:
      ignore_root_dm: true
      dm_topics:

        - chat_id: 123456789
          topics:
            - name: General

`
``Việc kiểm tra là **mỗi cuộc trò chuyện**: chỉ những người dùng có ít nhất một mục nhập trong 
`dm_topics

sẽ bị ảnh hưởng DM gốc của họ. Người dùng không có chủ đề được định cấu hình sẽ
không bị ảnh hưở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 chính xác giống như 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ó đặt lại (do hết thời gian chờ, đặt lại hàng ngày hoặc 

/reset
` thủ công).

:::tip
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.
:::

## Chế độ DM nhiều phiên (

/topic

)

DM nhiều phiên theo phong cách ChatGPT - một bot, nhiều cuộc trò chuyện song song. Không giống như 
`extra.dm_topics
` do nhà điều hành quản lý ở trên, chế độ này **do người dùng điều khiển**: không có cấu hình, không có tên chủ đề được khai báo trước. Người dùng cuối bật nó bằng 

/topic

, sau đó nhấn vào nút Telegram **+** để tạo bao nhiêu chủ đề tùy thích, mỗi chủ đề là một phiên Hermes hoàn toàn độc lập.

### Lệnh con 

/topic

| Mẫu | Bối cảnh | Hiệu ứng |
|------|----------|--------|
| 

/topic
` | Root DM, chưa được kích hoạt | Kiểm tra khả năng của BotFather, bật chế độ nhiều phiên, tạo chủ đề Hệ thống được ghim |
| 

/topic
` | Root DM, đã được kích hoạt | Hiển thị trạng thái: các phiên đã hủy liên kết có sẵn để khôi phục |
| 

/topic
` | Bên trong một chủ đề | Hiển thị ràng buộc phiên của chủ đề hiện tại |
| 

/topic help
` | Bất kỳ | Sử dụng nội tuyến |
| 

/topic off
` | Gốc DM | Tắt chế độ nhiều phiên và xóa tất cả các ràng buộc chủ đề cho cuộc trò chuyện này |
| 

/topic ``&lt;session-id&gt;
` | Bên trong một chủ đề | Khôi phục phiên Telegram trước đó vào chủ đề hiện tại |

Chỉ những người dùng được ủy quyền (danh sách cho phép qua 
`Telegram_ALLOWED_USERS
` / cấu hình xác thực nền tảng) mới có thể chạy 

/topic

. Người gửi trái phép sẽ bị từ chối thay vì kích hoạt.

### Chủ đề DM so với chế độ DM nhiều phiên

| |

extra.dm_topics
` (điều khiển theo cấu hình) | 

/topic
` (do người dùng điều khiển) |
|---|---|---|
| Ai kích hoạt nó | Nhà điều hành trong 
`config.yaml
` | Người dùng cuối, bằng cách gửi 

/topic
` |
| Danh sách chủ đề | Đã sửa lỗi tập hợp được khai báo trong config | Người dùng tạo/xóa chủ đề một cách tự do |
| Tên chủ đề | Được nhà điều hành lựa chọn | Được người dùng lựa chọn; tự động đổi tên để phù hợp với tiêu đề phiên Hermes |
| Hành vi gốc DM | Trò chuyện bình thường (sảnh nếu 
`ignore_root_dm: true

) | Trở thành sảnh hệ thống (các tin nhắn không có lệnh bị từ chối) |
| Trường hợp sử dụng chính | Không gian làm việc cố định với ràng buộc kỹ năng tùy chọn | Phiên song song đặc biệt |
| Kiên trì |

extra.dm_topics
` trong cấu hình | Bảng SQLite 
`Telegram_dm_topic_mode

 + 
`Telegram_dm_topic_bindings
` |

Cả hai tính năng có thể cùng tồn tại trên cùng một bot — bạn sẽ chạy 

/topic
` từ DM của người dùng và 
`extra.dm_topics
` tiếp tục quản lý các chủ đề do nhà điều hành khai báo cho các cuộc trò chuyện khác.

### Điều kiện tiên quyết

Trong **@BotFather**, mở bot của bạn → **Cài đặt Bot → Cài đặt chủ đề**:
1. Bật **Chế độ theo luồng** (bật 
`has_topics_enabled

)
2. **không** vô hiệu hóa người dùng tạo chủ đề (bật 
`allows_users_to_create_topics

)

Khi người dùng chạy 

/topic
` lần đầu tiên, Hermes gọi 
`getMe
` để xác minh cả hai cờ. Nếu một trong hai tắt, Hermes sẽ gửi ảnh chụp màn hình của trang Cài đặt chủ đề BotFather và giải thích những gì cần chuyển đổi - không kích hoạt nào xảy ra cho đến khi đáp ứng các điều kiện tiên quyết.

### Luồng kích hoạt

Từ DM gốc, gửi:

`
/topic

`
``Hermes sẽ:
1. Kiểm tra 
`getMe().has_topics_enabled
` và 
`allows_users_to_create_topics

2. Nếu cả hai đều đúng, hãy bật chế độ chủ đề nhiều phiên cho DM này
3. Tạo và ghim chủ đề **Hệ thống** cho trạng thái/lệnh (nỗ lực tốt nhất)
4. Trả lời kèm theo danh sách các phiên Telegram chưa được liên kết trước đó mà người dùng có thể khôi phụcSau khi kích hoạt, **root DM là một sảnh**: các lời nhắc thông thường bị từ chối với hướng dẫn trỏ vào **Tất cả tin nhắn**. Các lệnh hệ thống (

/status

, 

/sessions

, 

/usage

, 

/help

, v.v.) vẫn hoạt động trong thư mục gốc.

### Tạo chủ đề mới (luồng người dùng cuối)
1. Mở bot DM trong Telegram
2. Nhấn vào **Tất cả tin nhắn** ở đầu giao diện bot, sau đó gửi bất kỳ tin nhắn nào
3. Telegram tạo chủ đề mới cho tin nhắn đó
4. Hermes phản hồi bên trong chủ đề đó - chủ đề hiện là một phiên độc lập

Mỗi chủ đề đều có lịch sử hội thoại, trạng thái mô hình, thực thi công cụ và ID phiên riêng. Khóa cách ly là 
`agent:main:Telegram:dm:\&#123;chat_id&#125;:\&#123;thread_id&#125;
` — giống với khóa cách ly chủ đề DM theo cấu hình.

### Chủ đề được tự động đổi tên

Khi Hermes tạo tiêu đề phiên cho một chủ đề (thông qua hệ thống tiêu đề tự động, sau lần trao đổi đầu tiên), chính chủ đề Telegram sẽ được đổi tên để khớp - ví dụ: "Chủ đề mới" trở thành "Kế hoạch di chuyển cơ sở dữ liệu". Việc đổi tên là nỗ lực tốt nhất: lỗi được ghi lại nhưng không làm hỏng phiên.

Để tắt tính năng này và giữ nguyên tên chủ đề được chọn thủ công của bạn, hãy đặt:

``` yaml
gateway:
  platforms:
    Telegram:
      extra:
        disable_topic_auto_rename: true

`
``Khi cờ này bật, Hermes vẫn tạo tiêu đề phiên nội bộ (được sử dụng bởi 
`Hermes sessions

, TUI, v.v.) nhưng không bao giờ chỉnh sửa tên chủ đề Telegram. Hữu ích khi bạn sắp xếp các chủ đề theo cách thủ công trong Chế độ phân luồng của BotFather và không muốn mọi câu trả lời đầu tiên đều ghi đè lên tiêu đề.

### 

/new
` trong một chủ đề

Đặt lại phiên của chủ đề hiện tại (ID phiên mới, lịch sử mới) mà không cần chạm vào các chủ đề khác. Hermes trả lời bằng lời nhắc rằng đối với công việc song song, việc tạo một chủ đề khác (thông qua **Tất cả tin nhắn**) thường là điều bạn muốn.

### Khôi phục phiên trước đó

Trong một chủ đề, hãy gửi:

`
/topic ``&lt;session-id&gt;

`
``Điều này liên kết chủ đề hiện tại với phiên Hermes hiện có thay vì bắt đầu mới. Hữu ích khi tiếp tục cuộc trò chuyện đã bắt đầu trước khi bật chế độ chủ đề. Hạn chế:
- Phiên mục tiêu phải thuộc về cùng một người dùng Telegram

- Phiên mục tiêu không được ràng buộc với chủ đề khác

Hermes xác nhận với tiêu đề phiên và phát lại tin nhắn trợ lý cuối cùng cho ngữ cảnh.

Để khám phá ID phiên, hãy gửi 

/topic
` (không có đối số) trong DM gốc - Hermes liệt kê các phiên Telegram chưa được liên kết của người dùng.

### 

/topic
` trong một chủ đề (không có đối số)

Hiển thị ràng buộc của chủ đề hiện tại: tiêu đề phiên, ID phiên và gợi ý cho 

/new
` so với việc tạo chủ đề khác.

### Dưới mui xe
- Kích hoạt vẫn tiếp tục với 
`Telegram_dm_topic_mode(chat_id, user_id, enabled, ...)
` trong 
`state.db

- Mỗi liên kết chủ đề vẫn tồn tại với 
`Telegram_dm_topic_bindings(chat_id, thread_id, session_id, ...)
` với 
`ON DELETE CASCADE
` trên 
`session_id

 - việc cắt bớt một phiên sẽ tự động xóa liên kết chủ đề của nó
- Quá trình di chuyển SQLite ở chế độ chủ đề là **chọn tham gia**: nó chạy trong lệnh gọi 

/topic
` đầu tiên, không bao giờ chạy khi khởi động cổng. Cho đến khi người dùng chạy 

/topic
` trong hồ sơ này, 
`state.db
` không thay đổi
- Mỗi tin nhắn DM gửi đến sẽ tra cứu ràng buộc 

(chat_id, thread_id)
` của nó. Nếu có, quá trình tra cứu sẽ định tuyến thông báo đến phiên bị ràng buộc thông qua 
`SessionStore.switch_session()
` để ánh xạ khóa phiên đến id phiên vẫn nhất quán trên đĩa
- 

/new
` bên trong một chủ đề viết lại hàng liên kết để trỏ đến ID phiên mới, vì vậy tin nhắn tiếp theo vẫn ở phiên mới
- Các chủ đề được khai báo trong 
`extra.dm_topics
` **không bao giờ được tự động đổi tên** — tên do nhà điều hành chọn được giữ nguyên ngay cả khi bật chế độ nhiều phiên
- Đặt 
`extra.disable_topic_auto_rename: true
` để tắt tự động đổi tên cho **tất cả** chủ đề trong cuộc trò chuyện (bao gồm các chủ đề đặc biệt được tạo thông qua Chế độ phân luồng)
- Chủ đề Chung (được ghim trên cùng) trong DM hỗ trợ diễn đàn được coi là chủ đề gốc, bất kể Telegram gửi tin nhắn bằng 
`message_thread_id=1
` hay không có thread_id
- Lời nhắc ở sảnh gốc được giới hạn tỷ lệ ở một tin nhắn mỗi 30 giây cho mỗi cuộc trò chuyện — người dùng quên bật chế độ chủ đề và nhập 10 lời nhắc trong thư mục gốc sẽ không nhận được 10 câu trả lời
- Ảnh chụp màn hình thiết lập BotFather bị giới hạn tốc độ ở một lần gửi mỗi 5 phút cho mỗi cuộc trò chuyện - các lần thử 

/topic
` lặp đi lặp lại trong khi Cài đặt chủ đề vẫn bị tắt sẽ không tải lên lại cùng một hình ảnh
- 

/background &lt;prompt
` bắt đầu bên trong một chủ đề mang lại kết quả cho cùng một chủ đề; phiên nền không kích hoạt tự động đổi tên chủ đề sở hữu
- Bản thân 

/topic
` bị kiểm soát bởi quá trình kiểm tra ủy quyền người dùng của bot - DM trái phép sẽ bị từ chối thay vì kích hoạt

### Tắt chế độ nhiều phiênGửi 

/topic off
` trong DM gốc. Hermes lật hàng này ra, xóa các ràng buộc 

(thread_id → session_id)
` của cuộc trò chuyện và DM gốc trở lại cuộc trò chuyện Hermes bình thường. Các chủ đề hiện có trong Telegram không bị xóa — chúng chỉ ngừng được coi là các phiên độc lập. Chạy lại 

/topic
` sau để bật lại.

Nếu bạn cần dọn dẹp bằng tay (ví dụ: đặt lại hàng loạt trên nhiều cuộc trò chuyện), hãy trực tiếp xóa các hàng:

``` bash
SQLite3 ~/.Hermes/state.db \
  "UPDATE Telegram_dm_topic_mode SET enabled = 0 WHERE chat_id = '&lt;your_chat_id'; \
   DELETE FROM Telegram_dm_topic_bindings WHERE chat_id = '&lt;your_chat_id';"

`

### Hạ cấp Hermes

Nếu bạn hạ cấp xuống phiên bản Hermes có trước 

/topic

, tính năng này sẽ ngừng hoạt động - các bảng 
`Telegram_dm_topic_mode
` và 
`Telegram_dm_topic_bindings
` vẫn ở 
`state.db
` nhưng bị mã cũ bỏ qua. DM hoàn nguyên về chế độ cách ly riêng trên mỗi luồng (mỗi 
`message_thread_id
` vẫn có phiên riêng thông qua 
`build_session_key

), vì vậy các chủ đề Telegram hiện tại của bạn sẽ tiếp tục hoạt động như các phiên song song. DM gốc không còn là nơi vận động hành lang nữa - các tin nhắn ở đó sẽ được gửi đến tác nhân như trước đây. Việc nâng cấp lại sẽ kích hoạt lại chế độ nhiều phiên chính xác như cũ.

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

Các siêu nhóm đã bật **Chế độ chủ đề** (còn được gọi là "chủ đề diễn đàn") đã có chế độ tách phiên cho mỗi chủ đề — mỗi 
`thread_id
` ánh xạ tới cuộc trò chuyện của riêng nó. 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ủ đề theo 
`platforms.Telegram.extra.group_topics
` trong 

~/.Hermes/config.yaml

:

``` 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ực | Bắt buộc | Mô tả |
|-------|----------|-------------|
| 
`chat_id
` | Có | ID số của siêu nhóm (số âm bắt đầu bằng 

-100

) |
| 
`name
` | Không | Nhãn mà con người có thể đọc được cho chủ đề (chỉ mang tính thông tin) |
| 
`thread_id
` | Có | ID chủ đề diễn đàn Telegram - hiển thị trong các liên kết 
`t.me/c/&lt;group_id/&lt;thread_id
` |
| 
`skill
` | Không | Kỹ năng tự động tải các phiên mới trong chủ đề này |

### Cách thức hoạt động
1. 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

2. Nếu một mục phù hợp có trường 
`skill

, kỹ năng đó sẽ được tải tự động cho phiên - giống hệt với ràng buộc kỹ năng chủ đề DM
3. Các chủ đề không có khóa 
`skill
` chỉ được cách ly phiên (hành vi hiện có, không thay đổi)
4. Các giá trị 
`thread_id
` chưa được ánh xạ hoặc các giá trị 
`chat_id
` không được ánh xạ - không có lỗi, không có kỹ năng

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

| | Chủ đề DM | Chủ đề nhóm |
|---|---|---|
| Phím cấu hình |

extra.dm_topics
` | 
`extra.group_topics
` |
| Tạo chủ đề | Hermes tạo chủ đề qua API nếu thiếu 
`thread_id
` | Quản trị viên tạo chủ đề trong giao diện người dùng Telegram |
| 
`thread_id
` | Tự động điền sau khi tạo | Phả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) |

:::tip
Để 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
` dành 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 qua 
`createForumTopic

. Hermes sử dụng điều này cho hai tính năng riêng biệt: [Private Chat Topics](#private-chat-topics-bot-API-94) do nhà điều hành quản lý (danh sách chủ đề cố định, định hướng theo cấu hình) và [Multi-session DM mode](#multi-session-dm-mode-topic) do người dùng điều khiển (được kích hoạt bởi 

/topic

, không giới hạn các chủ đề do người dùng tạo).
- **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.
- **Bot API 9.5 (Tháng 3 năm 2026): Phát trực tuyến gốc qua 
`sendMessageDraft

.** Hermes hỗ trợ API phát trực tuyến gốc của Telegram dưới dạng phương tiện chọn tham gia cho các cuộc trò chuyện riêng tư. Mặc định vẫn là đường dẫn 
`editMessageText
` cũ vì các bản xem trước nháp có thể thu gọn và hiển thị lại một cách rõ ràng trên một số ứng dụng khách Telegram.

### Truyền tải trực tuyến (
`gateway.streaming.transport

)

Khi bật tính năng phát trực tuyến (
`gateway.streaming.enabled: true

), Hermes chọn một trong bốn phương thức vận chuyển:

| Giá trị | Hành vi |
|---|---|
| 
`auto
` | Phát trực tuyến bản nháp gốc trên các cuộc trò chuyện được hỗ trợ (hiện tại là Telegram DM); đường dẫn dựa trên chỉnh sửa kế thừa nếu không. Quay trở lại một cách duyên dáng nếu khung nháp bị lỗi. |
| 
`draft
` | Buộc có bản nháp gốc. Ghi nhật ký hạ cấp và quay lại chỉnh sửa nếu cuộc trò chuyện không hỗ trợ bản nháp (ví dụ: nhóm/chủ đề). |
| 
`edit
` (mặc định) | Bỏ phiếu 
`editMessageText
` lũy tiến kế thừa cho mọi loại trò chuyện. |
| 
`off
` | Tắt hoàn toàn tính năng phát trực tuyến (chỉ trả lời cuối cùng, không có cập nhật lũy tiến). |

Trong 

~/.Hermes/config.yaml

:

``` yaml
gateway:
  streaming:
    enabled: true
    transport: edit    # edit | auto | draft | off

`
``**Những gì bạn sẽ thấy trong DM có 
`edit
` (mặc định)** — cổng gửi một thông báo xem trước bình thường và cập nhật dần dần thông báo đó qua 
`editMessageText

, tránh hiệu ứng thu gọn/khôi phục bản xem trước nháp của Telegram.

**Những gì bạn sẽ thấy trong DM có 
`auto
` hoặc 
`draft

`
** — Telegram hiển thị bản xem trước nháp hoạt hình cập nhật từng mã thông báo. Khi trả lời xong, nó sẽ được gửi dưới dạng tin nhắn thông thường và bản xem trước nháp sẽ hiển thị một cách tự nhiên trên máy khách. Thư nháp không có id tin nhắn nên câu trả lời cuối cùng là nội dung còn lại trong lịch sử trò chuyện của bạn.

**Còn các nhóm, siêu nhóm, chủ đề diễn đàn thì sao?** Telegram hạn chế 
`sendMessageDraft
` ở các cuộc trò chuyện riêng tư (DM). Cổng sẽ quay trở lại đường dẫn dựa trên chỉnh sửa cho mọi thứ khác một cách rõ ràng - trải nghiệm người dùng giống như trước đây.

**Điều gì sẽ xảy ra nếu khung nháp không thành công?** Bất kỳ lỗi nào (lỗi mạng tạm thời, từ chối phía máy chủ, cài đặt Python-Telegram-bot cũ hơn) sẽ chuyển phản hồi đó trở lại đường dẫn dựa trên chỉnh sửa cho phần còn lại của luồng. Phản hồi tiếp theo nhận được một nỗ lực mới.

## Hiển thị: Xem trước bảng và liên kết

MarkdownV2 của Telegram không có cú pháp bảng gốc — các bảng ống hiển thị dưới dạng nhiễu thoát dấu gạch chéo ngược nếu được truyền qua dạng thô. Hermes tự động bình thường hóa các bảng đánh dấu:
- **Các bảng nhỏ** được làm phẳng thành **dấu đầu dòng nhóm hàng** — mỗi hàng trở thành một danh sách có dấu đầu dòng có thể đọc được bên dưới tiêu đề cột. Tốt cho 2–4 cột và ô ngắn.
- **Các bảng lớn hơn hoặc rộng hơn** chuyển về **khối mã có hàng rào** với các cột được căn chỉnh để không có gì bị thu gọn. Gợi ý nhắc nhở một dòng được thêm vào để nhân viên biết nên theo dõi văn xuôi hơn nhiều bảng trên Telegram.

Không cần phải đặt cấu hình gì — bộ chuyển đổi sẽ chọn dự phòng phù hợp cho mỗi tin nhắn. Nếu bạn muốn hành vi "luôn chặn mã" cũ, hãy tắt tính năng chuẩn hóa bảng bằng cách đặt 
`Telegram.pretty_tables: false
` trong 
`config.yaml
` (mặc định: 
`true

).

**Xem trước liên kết.** Telegram tự động tạo bản xem trước liên kết cho các URL trong tin nhắn bot. Nếu bạn muốn loại bỏ những thứ đó (đầu ra 

/tools
` dài, phản hồi của nhân viên đề cập đến mười liên kết, v.v.):

``` yaml
gateway:
  platforms:
    Telegram:
      extra:
        disable_link_previews: true

`
``Khi được bật, Hermes sẽ đính kèm 
`LinkPreviewOptions(is_disabled=True)
` của Telegram vào mọi tin nhắn gửi đi và quay lại tham số 
`disable_web_page_preview
` cũ trên các phiên bản 
`Python-Telegram-bot
` cũ hơn.

## Danh sách cho phép của nhóm

Nhóm Telegram và cuộc trò chuyện trên diễn đàn có hai cổng trực giao mà bạn có thể định cấu hình:- **ID người dùng người gửi** (
`group_allow_from
` / 
`Telegram_GROUP_ALLOWED_USERS

) — danh sách cho phép trong phạm vi người gửi chỉ áp dụng cho tin nhắn nhóm/diễn đàn. Sử dụng tùy chọn này khi bạn muốn những người dùng cụ thể có thể gọi bot theo nhóm mà không cần thêm họ vào 
`Telegram_ALLOWED_USERS
` (điều này cũng sẽ cấp cho họ quyền truy cập DM).

- **ID trò chuyện** (
`group_allowed_chats
` / 
`Telegram_GROUP_ALLOWED_CHATS

) — danh sách cho phép trong phạm vi trò chuyện. Bất kỳ thành viên nào của các nhóm/diễn đàn này đều có thể tương tác với bot. Hữu ích cho các bot nhóm/hỗ trợ trong đó chính tư cách thành viên nhóm là tín hiệu truy cập.

``` yaml
gateway:
  platforms:
    Telegram:
      extra:

        # Global access (DMs + groups). Users here can always invoke the bot.
        allow_from:
          - "123456789"
        # Sender IDs allowed in groups/forums only. Does NOT grant DM access.
        group_allow_from:
          - "987654321"
        # Entire groups/forums — any member is authoriZed.
        group_allowed_chats:
          - "-1001234567890"

`
``Các loại env tương đương:

``` bash
Telegram_ALLOWED_USERS="123456789"
Telegram_GROUP_ALLOWED_USERS="987654321"
Telegram_GROUP_ALLOWED_CHATS="-1001234567890"

`
``Hành vi:
- 
`Telegram_ALLOWED_USERS
` bao gồm tất cả các loại trò chuyện (DM, nhóm, diễn đàn).

- 
`Telegram_GROUP_ALLOWED_USERS
` chỉ ủy quyền cho những người gửi được liệt kê trong nhóm/diễn đàn. Họ vẫn không thể DM bot trừ khi được liệt kê trong 
`Telegram_ALLOWED_USERS

.
- Một cuộc trò chuyện trong 
`Telegram_GROUP_ALLOWED_CHATS
` ủy quyền cho mọi thành viên của cuộc trò chuyện đó, bất kể người gửi.
- Sử dụng 

*
` trong bất kỳ mục nào trong số này để cho phép mọi người gửi/trò chuyện.
- Lớp này nằm trên các trình kích hoạt đề cập/mẫu hiện có và trên 
`group_topics

 + 
`ignored_threads

.

### Di chuyển từ trước PR #17686

Trước phần chia tách này, 
`Telegram_GROUP_ALLOWED_USERS
` là núm duy nhất và người dùng đặt **ID trò chuyện** vào đó. Để tương thích ngược, các giá trị có hình ID trò chuyện (bắt đầu bằng 

-

) trong 
`Telegram_GROUP_ALLOWED_USERS
` vẫn được coi là ID trò chuyện và cảnh báo không dùng nữa được ghi lại một lần. Di chuyển:

``` bash

# Old (still works, but deprecated)
Telegram_GROUP_ALLOWED_USERS="-1001234567890"

# New
Telegram_GROUP_ALLOWED_CHATS="-1001234567890"

`

### Bỏ qua @mention của khách (
`guest_mode

)

Trong thiết lập thông thường, 
`group_allowed_chats
` là một cổng cứng: tin nhắn từ các nhóm bên ngoài danh sách sẽ bị loại bỏ một cách âm thầm, ngay cả khi một thành viên @đề cập đến bot một cách rõ ràng. Đó là mặc định phù hợp cho các bot hỗ trợ/nhóm.

Đối với các thiết lập thông thường hơn — cuộc trò chuyện nhóm bạn bè nơi bạn muốn bot **hầu hết im lặng** nhưng **thỉnh thoảng khả dụng khi ping rõ ràng** — bật 
`guest_mode

:

``` yaml
gateway:
  platforms:
    Telegram:
      extra:
        group_allowed_chats:

          - "-1001234567890"   # your main allowlisted group
        guest_mode: true       # non-allowlisted groups: allow on @mention only

`
``Env tương đương:

``` bash
Telegram_GUEST_MODE=true

`
``Mặc định: 
`false

.

Với 
`guest_mode: true

, tin nhắn từ một nhóm không nằm trong danh sách cho phép sẽ **chỉ** được xử lý nếu nó @đề cập đến bot một cách rõ ràng. Việc đề cập là bắt buộc mỗi lượt — không có sự cố định phiên nào đối với các tương tác của khách, vì vậy bot không bao giờ tự động tham gia vào chuỗi nhóm bạn mà nó không được ping vào.

DM và nhóm trong danh sách cho phép hoạt động giống như trước đây.

## Kiểm soát truy cập lệnh gạch chéo

Theo mặc định, mọi người dùng được phép đều có thể chạy mọi lệnh gạch chéo. Để chia danh sách cho phép của bạn thành **quản trị viên** (quyền truy cập lệnh gạch chéo đầy đủ) và **người dùng thông thường** (chỉ những lệnh bạn bật rõ ràng), hãy thêm 
`allow_admin_from
` và 
`user_allowed_commands
` vào khối 
`extra
` của nền tảng:

`YAML
gateway:
  platforms:
    Telegram:
      extra:

        # Existing allowlists (unchanged)
        allow_from:
          - "123456789"     # admin
          - "555555555"     # regular user
          - "777777777"     # regular user

# NEW — admins get all slash commands (built-in + plugin)
        allow_admin_from:
          - "123456789"

# NEW — non-admin allowed users can only run these slash commands.
        # /help and /whoami are always allowed so users can see their access.
        user_allowed_commands:
          - status
          - model
          - history

# Optional: separate admin/command lists for groups
        group_allow_admin_from:
          - "123456789"
        group_user_allowed_commands:
          - status

`
``**Hành vi:**
- Người dùng được liệt kê trong 
`allow_admin_from
` cho một phạm vi (DM hoặc nhóm) có thể chạy **mọi** lệnh gạch chéo đã đăng ký — các lệnh tích hợp VÀ lệnh đã đăng ký plugin — thông qua sổ đăng ký trực tiếp.
- Người dùng trong 
`allow_from
` nhưng **không** trong 
`allow_admin_from
` chỉ có thể chạy các lệnh được liệt kê trong 
`user_allowed_commands

, cộng với tầng luôn được phép: 

/help
` và 

/whoami

.
- Trò chuyện đơn giản (tin nhắn không gạch chéo) không bị ảnh hưởng. Người dùng không phải quản trị viên vẫn có thể nói chuyện với tổng đài viên một cách bình thường, họ chỉ không thể kích hoạt các lệnh tùy ý.
- **Tương thích ngược:** nếu 
`allow_admin_from
` không được đặt cho một phạm vi, việc đặt lệnh gạch chéo sẽ bị tắt cho phạm vi đó. Các cài đặt hiện tại tiếp tục hoạt động mà không có thay đổi nào.
- Trạng thái quản trị viên DM không bao hàm trạng thái quản trị viên nhóm. Mỗi phạm vi có danh sách quản trị viên riêng.
- Nếu chỉ đặt 
`group_allow_admin_from

, phạm vi DM vẫn ở chế độ không hạn chế (tương thích ngược).

Sử dụng 

/whoami
` để xem phạm vi hoạt động, cấp độ của bạn (quản trị viên / người dùng / không bị hạn chế) và lệnh gạch chéo nào bạn có thể chạy.

## 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).:::tip
Nếu bạn biết tên mẫu chính xác, hãy nhập trực tiếp 

/model &lt;name
` để bỏ qua bộ chọn. Bạn cũng có thể nhập 

/model &lt;name --global
` để duy trì thay đổi qua các phiên.
:::

## 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

``` bash

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

`
``Hoặc trong 

~/.Hermes/config.yaml

:

``` yaml
platforms:
  Telegram:
    extra:
      fallback_ips:

        - "149.154.167.220"

`

:::tip
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:

``` bash
 export HTTPS_PROXY=http://proxy.example.com:8080
Hermes gateway

`
``Hoặc thêm nó vào 

~/.Hermes/.env

:

`bash
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.

:::note
Đ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ắn

Bot 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

:

``` yaml
Telegram:
  reactions: true

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

`bash
Telegram_REACTIONS=true

`

:::note
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.

:::

:::tip
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.
:::

## Lời nhắc trên mỗi kênh

Chỉ định lời nhắc hệ thống tạm thời cho các nhóm Telegram hoặc chủ đề diễn đàn cụ thể. Lời nhắc được đưa vào mỗi lượt trong thời gian chạy — không bao giờ tồn tại trong lịch sử bản ghi — vì vậy các thay đổi sẽ có hiệu lực ngay lập tức.

``` yaml
Telegram:
  channel_prompts:
    "-1001234567890": |
      You are a research assistant. Focus on academic sources,
      citations, and concise synthesis.
    "42":  |
      This topic is for creative writing feedback. Be warm and
      constructive.

`
``Khóa là ID trò chuyện (nhóm/siêu nhóm) hoặc ID chủ đề diễn đàn. Đối với các nhóm diễn đàn, lời nhắc cấp chủ đề sẽ ghi đè lời nhắc cấp nhóm:
- Tin nhắn trong chủ đề 
`42
` trong nhóm 

`
-1001234567890
` → sử dụng lời nhắc của chủ đề 
`42

- Tin nhắn trong chủ đề 
`99
` (không có mục rõ ràng) → quay lại lời nhắc của nhóm 

-1001234567890

- Tin nhắn trong một nhóm không có mục nhập → không áp dụng lời nhắc kênh

Các khóa YAML dạng số được tự động chuẩn hóa thành chuỗi.

## 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óm | Chế độ 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 âm | Xác minh STT có sẵn: cài đặt 
`faster-whisper
` để sao chép 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óng | Cài đặt 
`ffmpeg
` (cần thiết cho 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 thông qua 

/revoke
` sau đó là 

/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ật | Xác minh 
`Telegram_WEBHOOK_URL
` có thể truy cập công khai (thử nghiệm 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.

## Lời nhắc tương tác (làm rõ)

Khi nhân viên gọi đến công cụ 
`clarify
` — để hỏi xem bạn thích phương pháp nào hơn, nhận phản hồi sau nhiệm vụ hoặc kiểm tra trước khi đưa ra một quyết định không hề đơn giản — Telegram sẽ hiển thị câu hỏi bằng **các nút bàn phím nội tuyến**:`> ❓ Tôi nên sử dụng framework nào cho bảng điều khiển?
>
> [1. Next.js] [2. Phối lại] [3. Astro]
> [✏️ Khác (nhập câu trả lời)]

Nhấn vào một nút để trả lời hoặc nhấn **Khác** để nhập câu trả lời dạng tự do (tin nhắn tiếp theo bạn gửi sẽ trở thành câu trả lời). Cuộc gọi 
`clarify
` kết thúc mở (không có lựa chọn đặt trước) bỏ qua các nút và chỉ ghi tin nhắn tiếp theo của bạn.

Định cấu hình thời gian chờ phản hồi qua 
`agent.clarify_timeout
` trong 

~/.Hermes/config.yaml
` (giây 
`600
` mặc định). Nếu bạn không phản hồi trong thời gian chờ, nhân viên sẽ bỏ chặn bằng một tin nhắn trọng điểm và điều chỉnh thay vì treo máy.

## Âm lượng thông báo đẩy

Telegram kích hoạt thông báo đẩy trên mỗi tin nhắn mà bot gửi. Đối với các lượt tác nhân dài phát ra bong bóng tiến trình công cụ, cập nhật trực tuyến và gọi lại trạng thái, thao tác này sẽ nhanh chóng bị nhiễu. Bộ điều hợp Telegram có hai chế độ thông báo:

| Chế độ | Hành vi |
|------|----------|
| 
`important
` (mặc định) | Chỉ **phản hồi cuối cùng**, **lời nhắc phê duyệt** và **xác nhận lệnh gạch chéo** đổ chuông. Tiến trình công cụ, các đoạn phát trực tuyến và thông báo trạng thái được gửi bằng 
`disable_notification=true

. |
| 
`all
` | Mỗi tin nhắn gửi đi sẽ kích hoạt một thông báo đẩy. Hành vi kế thừa; hãy chọn tham gia nếu bạn thực sự muốn nghe về mọi cuộc gọi công cụ. |

Cấu hình trong 

~/.Hermes/config.yaml

:

``` yaml
display:
  platforms:
    Telegram:
      notifications: important   # or "all"

`
``Ghi đè Env (tiện dụng để thử nghiệm A/B nhanh chóng):

`bash
Hermes_Telegram_NOTIFICATIONS=all

`
``Các giá trị không xác định sẽ ghi lại cảnh báo và quay lại 
`important

.

## Bảo mật

:::warning
Luôn đặt 
`Telegram_ALLOWED_USERS
` để hạn chế những 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 [Security documentation](/user-guide/security). Bạn cũng có thể sử dụng [DM pairing](/user-guide/messaging#dm-pairing-alternative-to-allowlists) để có cách tiếp cận năng động hơn đối với việc ủy ​​quyền người dùng.
Bước 1: Tạo Bot thông qua BotFather​

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

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

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

Quan sát cuộc trò chuyện nhóm mà không trả lời tự động​

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

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

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

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

Quan sát cuộc trò chuyện nhóm mà không trả lời tự động
