Hermes Agent Telegram: tạo bot, chặn người lạ và dùng trong nhóm

Để nhắn với Hermes qua Telegram, bạn cần đúng ba thứ: một bot do chính bạn tạo bằng BotFather, user ID dạng số của mình, và một dòng cấu hình trong file ~/.hermes/.env. Điểm nhiều người lo nhất — chặn người lạ — thì hermes agent telegram đã xử lý sẵn: theo tài liệu chính thức, gateway mặc định từ chối mọi người không nằm trong allowlist hoặc chưa được ghép đôi qua tin nhắn riêng.

Bài này tôi đi lần lượt từ lúc tạo bot, cấu hình, phân quyền, cho tới lúc đưa bot vào nhóm làm việc mà nó không "nói leo", và nhận báo cáo tự động mỗi sáng. Nếu bạn chưa cài Hermes thì đọc trước bài cài Hermes Agent trên Windows, Ubuntu và macOS rồi quay lại đây.

Vì sao Telegram là kênh dễ nhất để bắt đầu với Hermes?

Vì Telegram được Hermes hỗ trợ sẵn và là nền tảng có nhiều tính năng nhất trong tài liệu: nhóm, topic, tin nhắn thoại, file dung lượng lớn. Quan trọng hơn với người không rành kỹ thuật: bạn không cần một webhook công khai hay tên miền để bot chạy — máy của bạn chủ động kết nối ra, nên chỉ cần máy bật là bot sống.

Một điểm hay nữa: mỗi nhóm hay kênh là một phiên làm việc riêng. Nhóm bán hàng hỏi gì thì ngữ cảnh nằm ở nhóm bán hàng, không lẫn sang chat riêng của bạn.

Nhưng có hai giới hạn nên biết trước. Thứ nhất, menu lệnh của bot bị giới hạn số lượng: tài liệu ghi "Telegram allows up to 100 BotCommands, but large command payloads can fail. Hermes defaults to 60 for reliability" — tức Hermes mặc định chỉ hiện 60 lệnh. Thứ hai, mỗi bot token chỉ dùng được cho một gateway; muốn chạy nhiều profile thì mỗi profile phải có bot riêng.

Hermes agent telegram setup: tạo bot với BotFather

Bước đầu tiên của hermes agent telegram setup là tạo bot bằng BotFather — tài khoản chính thức của Telegram chuyên để cấp bot. Làm như sau:

1. Mở Telegram, tìm @BotFather và bắt đầu chat.
2. Gửi lệnh /newbot.
3. Đặt tên hiển thị (tiếng Việt có dấu cũng được, ví dụ "Trợ lý kho Minh Phát").
4. Đặt username: tài liệu ghi rõ username "must be unique and end in bot" — phải là duy nhất và kết thúc bằng "bot", ví dụ tro_ly_kho_mp_bot.
5. BotFather trả về một chuỗi dài — đó là bot token. Giữ nó như mật khẩu két sắt.

Token này chính là chìa khoá điều khiển bot. Nếu lỡ dán nhầm vào nhóm chat hay ảnh chụp màn hình, tài liệu khuyên "revoke it immediately via /revoke in BotFather" — thu hồi ngay bằng lệnh /revoke, BotFather sẽ cấp token mới và token cũ chết lập tức.

Ngoài cách thủ công, bản dashboard/ứng dụng Desktop của Hermes có nút tạo bot bằng mã QR, tự sinh bot và ghi cấu hình giúp bạn. Giao diện này đổi khá nhanh, nên bạn kiểm tra tài liệu chính thức tại thời điểm cài và ghi rõ thời điểm mình làm theo.

Lấy user ID và cấu hình Hermes

Đây là chỗ 10 người thì 8 người vấp. Tài liệu nói thẳng: "Your user ID is not your username — it's a number". User ID của bạn không phải cái @ten_cua_ban, mà là một dãy số. Cách lấy: nhắn cho @userinfobot, nó trả về con số đó.

Có user ID rồi, cấu hình theo một trong hai cách:

• Cách có hướng dẫn: chạy hermes gateway setup và làm theo từng câu hỏi.
• Cách ghi tay: mở file ~/.hermes/.env và thêm hai dòng:
  • TELEGRAM_BOT_TOKEN=<token>
  • TELEGRAM_ALLOWED_USERS=<user_id>

Nhiều người cùng dùng thì các user ID ngăn nhau bằng dấu phẩy. Sau đó chạy hermes gateway để thử: nhắn cho bot một câu, nếu nó trả lời là xong phần nền móng. Khi muốn gateway chạy nền lâu dài, Hermes có cơ chế cài gateway thành dịch vụ của hệ điều hành — tên lệnh chính xác bạn tra lại trong tài liệu chính thức ở thời điểm cài, vì CLI của Hermes thay đổi rất nhanh.

Hermes-agent telegram allowed_users: chặn người lạ nhắn vào bot

Câu trả lời ngắn: bạn không cần làm gì thêm, vì chặn người lạ là hành vi mặc định. Tài liệu ghi: "By default, the gateway denies all users who are not in an allowlist or paired via DM." Username bot của bạn có bị ai dò ra cũng vô ích — người lạ nhắn vào thì gateway từ chối.

Cơ chế hermes-agent telegram allowed_users cho bạn ba cách cấp quyền:

1. Allowlist theo user ID — cách chặt nhất. Ai có ID trong TELEGRAM_ALLOWED_USERS thì được nói chuyện, không thì thôi. Dùng cho bot cá nhân và bot có quyền chạy lệnh.
2. Ghép đôi qua tin nhắn riêng (pairing) — người mới nhắn vào sẽ nhận một mã, bạn duyệt bằng hermes pairing approve telegram <MÃ>, xem danh sách bằng hermes pairing list, gỡ quyền bằng hermes pairing revoke telegram <user_id>. Lưu ý: "Pairing codes expire after 1 hour" — mã hết hạn sau 1 giờ, duyệt muộn thì bảo họ nhắn lại.
3. Mở cho tất cả bằng GATEWAY_ALLOW_ALL_USERS=true. Tài liệu ghi rõ đây là lựa chọn "NOT recommended for bots with terminal access" — không nên dùng với bot có quyền terminal. Tôi khuyên bỏ qua hẳn lựa chọn này trừ khi bot của bạn đã bị cắt sạch công cụ nguy hiểm.

Trên nữa còn một tầng phân quyền: trong config.yaml, nhánh gateway.platforms.telegram.extra có allow_from, allow_admin_from và user_allowed_commands. Hiểu đơn giản: người trong allow_admin_from là admin, chạy được mọi lệnh slash; người thường chỉ chạy được những lệnh bạn liệt kê trong user_allowed_commands. Riêng /help và /whoami thì luôn được phép — ai nghi ngờ mình đang ở mức quyền nào, gõ /whoami là biết.

Dùng hermes agent telegram bot trong nhóm làm việc

Đưa hermes agent telegram bot vào nhóm thì phải xử lý hai chuyện: làm sao bot nghe thấy tin nhắn, và làm sao nó đừng trả lời tất cả mọi thứ.

Chuyện thứ nhất — privacy mode. Telegram bật chế độ riêng tư cho bot theo mặc định ("enabled by default"), nghĩa là bot chỉ thấy tin nhắn bắt đầu bằng dấu / và tin trả lời chính nó. Muốn bot thấy cả cuộc trò chuyện, bạn vào BotFather theo đường /mybots → Bot Settings → Group Privacy → Turn off, hoặc cho bot làm admin của nhóm. Rất quan trọng: tài liệu nhấn mạnh "You must remove and re-add the bot to any group" — đổi xong phải xoá bot khỏi nhóm rồi thêm lại, nếu không thiết lập cũ vẫn giữ nguyên.

Chuyện thứ hai — đừng nói leo. Trong config.yaml, đặt telegram.require_mention: true để bot chỉ trả lời khi được gọi tên hoặc được reply; telegram.mention_patterns cho phép bạn khai báo thêm cách gọi (ví dụ gọi bằng biệt danh thay vì @username). Nếu muốn bot vẫn "nghe" cả nhóm để hiểu ngữ cảnh nhưng chỉ lên tiếng khi được gọi, bật telegram.observe_unmentioned_group_messages: true.

Về quyền trong nhóm, có ba lớp tách bạch — bảng dưới là cách tôi hay giải thích cho khách:

Biến cấu hình	Cho phép ai	Dùng khi nào
TELEGRAM_ALLOWED_USERS	Người được nói chuyện với bot ở mọi nơi, kể cả chat riêng	Chủ doanh nghiệp, quản trị hệ thống
TELEGRAM_GROUP_ALLOWED_USERS	"only authorizes the listed senders in groups/forums" — chỉ được gọi bot trong nhóm, không nhắn riêng được	Nhân viên dùng bot khi làm việc chung
TELEGRAM_GROUP_ALLOWED_CHATS	"authorizes every member of that chat" — cả nhóm được dùng	Nhóm kín, thành viên đã sàng lọc kỹ

Lưu ý nhỏ nhưng hay làm người ta rối: ID của nhóm là số âm (có dấu trừ ở đầu), đừng tưởng gõ nhầm mà sửa lại thành số dương.

Tôi đang chạy một profile kiểu "trợ lý sản phẩm nội bộ" trong nhóm chat của đội bán hàng và marketing: ai cần tra thông số, giá, chương trình bán đang chạy thì gọi bot ngay trong nhóm, lấy câu trả lời rồi trả lời khách luôn, không phải chạy đi hỏi người khác. Một chi tiết tôi phải chỉnh đi chỉnh lại nhiều vòng là file SOUL.md — phần mô tả tính cách và cách trả lời của agent — chủ yếu để ép nó trả lời ngắn, vì anh em đọc trên điện thoại giữa lúc đang tiếp khách, một đoạn dài là không ai đọc.

Giới hạn công cụ cho bot ở nhóm đông người

Đây là bài học tôi muốn nhấn mạnh nhất. Bộ công cụ mặc định của Telegram trong Hermes là hermes-telegram, được mô tả là "Full tools including terminal" — tức có cả quyền chạy lệnh trên máy. Bot đó nằm trong nhóm mười mấy người thì rủi ro không nằm ở kẻ xấu, mà ở một câu đùa vô tình.

Cách xử lý: dùng hermes tools để tắt bớt công cụ theo từng nền tảng, hoặc tách hẳn một profile riêng cho nhóm với bộ công cụ tối thiểu. Nguyên tắc tôi áp dụng cho mọi khách: chỉ kênh riêng của chủ mới bật đủ quyền chạy lệnh, nhóm đông người thì agent chỉ được đọc và trả lời. Nếu bạn muốn hiểu sâu hơn phần rủi ro này, tôi có viết riêng một bài về chạy AI agent an toàn trong doanh nghiệp.

Nhận báo cáo tự động: home channel và cron

Home channel là nơi Hermes gửi kết quả về khi bạn không chủ động hỏi. Cách đặt: gõ /sethome ngay trong chat hoặc nhóm bạn muốn nhận kết quả; hoặc khai báo TELEGRAM_HOME_CHANNEL trong file .env. Tài liệu ghi: "Scheduled tasks (cron jobs) deliver their results to this channel" — các tác vụ hẹn giờ sẽ đổ kết quả về đúng kênh này.

Ví dụ sát với doanh nghiệp Việt: một cửa hàng xuất dữ liệu bán hàng ra file don-hang.csv mỗi tối. Bạn đặt một cron chạy 7 giờ sáng với nội dung yêu cầu kiểu:

Tóm tắt đơn hàng hôm qua từ file don-hang.csv (cột ma_don, khach_hang, tong_tien, trang_thai): tổng số đơn, tổng tiền, đơn còn chờ giao.

7 giờ sáng mở Telegram là có bản tóm tắt, không phải mở máy tính. Và để tránh bị làm phiền bởi những ngày không có gì mới, bạn dùng mẫu [SILENT]: theo tài liệu, "When a cron job's response contains [SILENT], delivery is suppressed" — chỉ cần hướng dẫn agent trả về [SILENT] khi không có đơn nào, nó sẽ im lặng thay vì gửi một tin rỗng.

Nếu bạn muốn những việc kiểu này chạy cả khi máy cá nhân tắt, hãy đọc thêm bài về cấu hình Hermes Agent trên VPS để bật 24/7.

Lỗi hay gặp: bot im lặng trong nhóm, trả lời cả nhóm, lộ token

Khi bot im lặng trong nhóm, hãy đi theo đúng thứ tự checklist trong tài liệu, đừng nhảy cóc:

1. Telegram có giao tin cho bot không? Nếu privacy mode còn bật, bot chỉ thấy lệnh / và tin reply — mọi thứ khác nó không hề nhận được.
2. Đã xoá và thêm lại bot sau khi đổi privacy chưa? Đây là bước bị bỏ sót nhiều nhất.
3. Người gửi hoặc nhóm có trong allowlist không? Kiểm tra lại TELEGRAM_GROUP_ALLOWED_USERS và TELEGRAM_GROUP_ALLOWED_CHATS, nhớ ID nhóm là số âm.
4. Đang bật require_mention à? Nếu có thì phải gọi tên bot hoặc reply vào tin của nó; thêm cách gọi khác thì khai trong mention_patterns.
5. Mỗi profile một bot token riêng chưa? Dùng chung token cho hai profile là hai gateway giành nhau tin nhắn, kết quả rất khó đoán.

Trường hợp ngược lại — bot trả lời quá nhiều, chen vào mọi câu chuyện trong nhóm — thì nguyên nhân gần như luôn là chưa bật telegram.require_mention: true. Còn nếu bot im luôn cả với tin nhắn riêng của bạn, vấn đề nằm ở gateway chứ không phải cấu hình nhóm: kiểm tra gateway còn chạy không và đọc log của nó (tên lệnh xem trạng thái bạn tra trong tài liệu chính thức tại thời điểm dùng).

Cuối cùng là token. Lỡ lộ thì /revoke trong BotFather ngay, lấy token mới, cập nhật lại TELEGRAM_BOT_TOKEN trong ~/.hermes/.env rồi khởi động lại gateway. Đừng dán token vào nhóm chat để "nhờ xem giúp", và đừng để nó trong ảnh chụp màn hình gửi cho người khác.

Tóm lại và bước tiếp theo

Bốn ý cần nhớ: (1) bot do bạn tự tạo bằng /newbot, token giữ như mật khẩu; (2) user ID là số, lấy từ @userinfobot; (3) gateway mặc định đã chặn người lạ, bạn chỉ cần quyết định ai vào allowlist và ai được pairing; (4) vào nhóm thì nhớ tắt privacy mode, thêm lại bot, bật require_mention và cắt bớt công cụ.

Việc nên làm ngay hôm nay: tạo một bot thử, thêm mỗi mình bạn vào TELEGRAM_ALLOWED_USERS, chạy hermes gateway và nhắn vài câu. Chạy ổn rồi mới nghĩ đến nhóm. Khi đưa vào nhóm, bắt đầu bằng nhóm nhỏ 3–5 người và bộ công cụ tối thiểu, chứ đừng thả bot full quyền vào nhóm chung của công ty.

Mọi lệnh và khoá cấu hình trong bài tôi lấy từ tài liệu chính thức của Nous Research (kiểm tra ngày 04/10/2026) — bạn xem trang hướng dẫn Telegram của Hermes, phần tổng quan messaging và phân quyền và automation blueprints. Hermes đổi rất nhanh, nên trước khi làm theo hãy đối chiếu lại với bản tài liệu tại thời điểm bạn đọc.

Đọc thêm: Hermes Agent là gì? Agent AI tự học của Nous Research cho người mới nếu bạn muốn hiểu tổng thể trước khi đi sâu vào từng kênh nhắn tin.