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

Thiết lập Trợ lý Telegram của nhóm

Hướng dẫn này hướng dẫn bạn cách thiết lập bot Telegram do Hermes Agent cung cấp mà nhiều thành viên trong nhóm có thể sử dụng. Cuối cùng, nhóm của bạn sẽ có một trợ lý AI chung mà họ có thể nhắn tin để yêu cầu trợ giúp về mã, nghiên cứu, quản trị hệ thống và bất kỳ điều gì khác - được bảo mật bằng ủy quyền của mỗi người dùng.

Những gì chúng tôi đang xây dựng

Một bot Telegram:

  • Bất kỳ thành viên nhóm được ủy quyền nào đều có thể gửi tin nhắn trực tiếp để được trợ giúp - đánh giá mã, nghiên cứu, lệnh shell, gỡ lỗi
  • Chạy trên máy chủ của bạn với toàn quyền truy cập công cụ — terminal, chỉnh sửa tệp, tìm kiếm trên web, thực thi mã
  • Phiên của mỗi người dùng — mỗi người có bối cảnh trò chuyện của riêng mình
  • Bảo mật theo mặc định — chỉ những người dùng được phê duyệt mới có thể tương tác, với hai phương thức ủy quyền
  • Nhiệm vụ đã lên lịch — thông tin dự phòng hàng ngày, kiểm tra tình trạng và lời nhắc được gửi đến kênh nhóm

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

Trước khi bắt đầu, hãy đảm bảo bạn có:

  • Đã cài đặt Hermes Agent trên máy chủ hoặc VPS (không phải máy tính xách tay của bạn — bot cần tiếp tục chạy). Hãy làm theo hướng dẫn cài đặt nếu bạn chưa làm theo.
  • Một tài khoản Telegram cho chính bạn (chủ sở hữu bot)
  • Nhà cung cấp LLM đã được định cấu hình — tối thiểu là khóa API cho OpenAI, Anthropic hoặc nhà cung cấp được hỗ trợ khác trong ~/.hermes/.env
mẹo

VPS $5/tháng là đủ để chạy cổng. Bản thân Hermes rất nhẹ - các lệnh gọi API LLM đều tốn tiền và những lệnh gọi đó diễn ra từ xa.

Bước 1: Tạo Bot Telegram

Mọi bot Telegram đều bắt đầu bằng @BotFather — bot chính thức của Telegram để tạo bot.

  1. Mở Telegram và tìm kiếm @BotFather hoặc truy cập t.me/BotFather

  2. **Gửi /newbot ** — BotFather sẽ hỏi bạn hai điều:

    • Tên hiển thị — những gì người dùng nhìn thấy (ví dụ: Team Hermes Assistant )
    • Tên người dùng — phải kết thúc bằng bot (ví dụ: myteam_hermes_bot )

  3. Sao chép mã thông báo bot — BotFather trả lời bằng nội dung như:

   Use this token to access the HTTP API:
   7123456789:AAH1bGciOiJSUzI1NiIsInR5cCI6Ikp...

Lưu mã thông báo này — bạn sẽ cần nó trong bước tiếp theo.

  1. Đặt mô tả (tùy chọn nhưng được khuyến nghị):
   /setdescription

Chọn bot của bạn, sau đó nhập nội dung như:

   Team AI assistant powered by Hermes Agent. DM me for help with code, research, debugging, and more.

  1. Đặt lệnh bot (tùy chọn — cung cấp cho người dùng menu lệnh):
   /setcommands

Chọn bot của bạn, sau đó dán:

   new - Start a fresh conversation
   model - Show or change the AI model
   status - Show session info
   help - Show available commands
   stop - Stop the current task

cảnh báo

Giữ bí mật mã thông báo bot của bạn. Bất cứ ai có mã thông báo đều có thể điều khiển bot. Nếu nó bị rò rỉ, hãy sử dụng /revoke trong BotFather để tạo một cái mới.

Bước 2: Cấu hình Gateway

Bạn có hai tùy chọn: trình hướng dẫn thiết lập tương tác (được khuyến nghị) hoặc cấu hình thủ công.

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

hermes gateway setup

Điều này sẽ hướng dẫn bạn mọi thứ bằng cách chọn phím mũi tên. Chọn Telegram, dán mã thông báo bot của bạn và nhập ID người dùng của bạn khi được nhắc.

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

Thêm những dòng này vào ~/.hermes/.env :

# Telegram bot token from BotFather
TELEGRAM_BOT_TOKEN=7123456789:AAH1bGciOiJSUzI1NiIsInR5cCI6Ikp...

# Your Telegram user ID (numeric)
TELEGRAM_ALLOWED_USERS=123456789

Tìm ID người dùng của bạn​

ID người dùng Telegram của bạn là một giá trị số (không phải tên người dùng của bạn). Để tìm thấy nó:1. Tin nhắn @userinfobot trên Telegram 2. Nó trả lời ngay lập tức bằng ID người dùng số của bạn 3. Sao chép số đó vào TELEGRAM_ALLOWED_USERS

thông tin

ID người dùng Telegram là các số cố định như 123456789 . Chúng khác với @username của bạn và có thể thay đổi. Luôn sử dụng ID dạng số cho danh sách cho phép.

Bước 3: Khởi động Gateway

Kiểm tra nhanh​

Trước tiên hãy chạy cổng ở nền trước để đảm bảo mọi thứ hoạt động:

hermes gateway

Bạn sẽ thấy đầu ra như:

[Gateway] Starting Hermes Gateway...
[Gateway] Telegram adapter connected
[Gateway] Cron scheduler started (tick every 60s)

Mở Telegram, tìm bot của bạn và gửi tin nhắn cho nó. Nếu nó trả lời, bạn đang kinh doanh. Nhấn Ctrl+C để dừng.

Sản xuất: Cài đặt dưới dạng Dịch vụ​

Để triển khai liên tục có thể tồn tại sau khi khởi động lại:

hermes gateway install
sudo hermes gateway install --system   

# Linux only: boot-time system service

Điều này tạo ra một dịch vụ nền: dịch vụ systemd cấp người dùng trên Linux theo mặc định, dịch vụ launchd trên macOS hoặc dịch vụ hệ thống Linux tại thời điểm khởi động nếu bạn vượt qua --system .

# Linux — manage the default user service
hermes gateway start
hermes gateway stop
hermes gateway status

# View live logs
journalctl --user -u hermes-gateway -f

# Keep running after SSH logout
sudo loginctl enable-linger $USER

# Linux servers — explicit system-service commands
sudo hermes gateway start --system
sudo hermes gateway status --system
journalctl -u hermes-gateway -f

# macOS — manage the service
hermes gateway start
hermes gateway stop
tail -f ~/.hermes/logs/gateway.log

macOS PATH

Bản khởi chạy sẽ ghi lại PATH shell của bạn khi cài đặt để các quy trình con cổng có thể tìm thấy các công cụ như Node.js và ffmpeg. Nếu sau này bạn cài đặt các công cụ mới, hãy chạy lại hermes gateway install để cập nhật bản gốc.

Xác minh nó đang chạy​

hermes gateway status

Sau đó gửi tin nhắn kiểm tra tới bot của bạn trên Telegram. Bạn sẽ nhận được phản hồi trong vòng vài giây.

Bước 4: Thiết lập quyền truy cập nhóm

Bây giờ hãy cấp quyền truy cập cho đồng đội của bạn. Có hai cách tiếp cận.

Cách tiếp cận A: Danh sách cho phép tĩnh​

Thu thập ID người dùng Telegram của từng thành viên trong nhóm (nhắn tin cho họ @userinfobot) và thêm họ dưới dạng danh sách được phân tách bằng dấu phẩy:

# In ~/.hermes/.env
TELEGRAM_ALLOWED_USERS=123456789,987654321,555555555

Khởi động lại cổng sau khi thay đổi:

hermes gateway stop && hermes gateway start

Cách tiếp cận B: Ghép đôi DM (Khuyến nghị cho các đội)​

Ghép nối DM linh hoạt hơn — bạn không cần phải thu thập trước ID người dùng. Đây là cách nó hoạt động:

  1. Đồng đội gửi tin nhắn trực tiếp cho bot — vì họ không có tên trong danh sách cho phép nên bot sẽ trả lời bằng mã ghép nối một lần:
   🔐 Pairing code: XKGH5N7P
   Send this code to the bot owner for approval.

  1. Đồng đội gửi mã cho bạn (thông qua bất kỳ kênh nào - Slack, email, trực tiếp)

  2. Bạn phê duyệt trên máy chủ:

   hermes pairing approve telegram XKGH5N7P

  1. Họ đang tham gia — bot ngay lập tức bắt đầu trả lời tin nhắn của họ

Quản lý người dùng được ghép nối:

# See all pending and approved users
hermes pairing list

# Revoke someone's access
hermes pairing revoke telegram 987654321

# Clear expired pending codes
hermes pairing clear-pending

mẹo

Ghép nối DM lý tưởng cho các nhóm vì bạn không cần khởi động lại cổng khi thêm người dùng mới. Phê duyệt có hiệu lực ngay lập tức.

Cân nhắc về bảo mật​

  • **Không bao giờ đặt GATEWAY_ALLOW_ALL_USERS=true ** trên bot có quyền truy cập terminal — bất kỳ ai tìm thấy bot của bạn đều có thể chạy lệnh trên máy chủ của bạn
  • Mã ghép nối hết hạn sau 1 giờ và sử dụng tính ngẫu nhiên của mật mã
  • Giới hạn tốc độ ngăn chặn các cuộc tấn công vũ phu: 1 yêu cầu cho mỗi người dùng trong 10 phút, tối đa 3 mã đang chờ xử lý trên mỗi nền tảng
  • Sau 5 lần phê duyệt không thành công, nền tảng sẽ bị khóa trong 1 giờ
  • Tất cả dữ liệu ghép nối được lưu trữ với quyền chmod 0600

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

Đặt kênh chính​

Kênh chính là nơi bot cung cấp kết quả công việc định kỳ và thông báo chủ động. Nếu không có nó, các tác vụ đã lên lịch sẽ không có nơi nào để gửi đầu ra.Tùy chọn 1: Sử dụng lệnh /sethome trong bất kỳ nhóm Telegram hoặc cuộc trò chuyện nào mà bot là thành viên.

Tùy chọn 2: Đặt thủ công trong ~/.hermes/.env :

TELEGRAM_HOME_CHANNEL=-1001234567890
TELEGRAM_HOME_CHANNEL_NAME="Team Updates"

Để tìm ID kênh, hãy thêm @userinfobot vào nhóm — nó sẽ báo cáo ID trò chuyện của nhóm.

Định cấu hình Hiển thị tiến trình công cụ​

Kiểm soát mức độ chi tiết mà bot hiển thị khi sử dụng các công cụ. Trong ~/.hermes/config.yaml :

display:
  tool_progress: new    

# off 

| new  | all  | verbose

Chế độNhững gì bạn thấy
offChỉ phản hồi rõ ràng - không có hoạt động công cụ
newTrạng thái ngắn gọn cho mỗi cuộc gọi công cụ mới (được khuyến nghị để nhắn tin)
allMọi cuộc gọi công cụ đều có thông tin chi tiết
verboseĐầu ra công cụ đầy đủ bao gồm kết quả lệnh

Người dùng cũng có thể thay đổi điều này mỗi phiên bằng lệnh /verbose trong trò chuyện.

Thiết lập tính cách với SOUL.md​

Tùy chỉnh cách bot giao tiếp bằng cách chỉnh sửa ~/.hermes/SOUL.md :

Để có hướng dẫn đầy đủ, hãy xem Sử dụng SOUL.md với Hermes.

# Soul
You are a helpful team assistant. Be concise and technical.
Use code blocks for any code. Skip pleasantries — the team
values directness. When debugging, always ask for error logs
before guessing at solutions.

Thêm bối cảnh dự án​

Nếu nhóm của bạn làm việc trên các dự án cụ thể, hãy tạo tệp ngữ cảnh để bot biết ngăn xếp của bạn:

<!-- ~/.hermes/AGENTS.md -->
# Team Context
- We use Python 3.12 with FastAPI and SQLAlchemy
- Frontend is React with TypeScript
- CI/CD runs on GitHub Actions
- Production deploys to AWS ECS
- Always suggest writing tests for new code

thông tin

Các tệp ngữ cảnh được đưa vào lời nhắc hệ thống của mỗi phiên. Giữ chúng ngắn gọn — mỗi ký tự đều được tính vào ngân sách mã thông báo của bạn.

Bước 6: Thiết lập tác vụ theo lịch trình

Khi cổng đang chạy, bạn có thể lên lịch các tác vụ định kỳ nhằm mang lại kết quả cho kênh nhóm của mình.

Tóm tắt dự phòng hàng ngày​

Nhắn tin cho bot trên Telegram:

Every weekday at 9am, check the GitHub repository at
github.com/myorg/myproject for:
1. Pull requests opened/merged in the last 24 hours
2. Issues created or closed
3. Any CI/CD failures on the main branch
Format as a brief standup-style summary.

Nhân viên hỗ trợ tự động tạo một công việc định kỳ và gửi kết quả đến cuộc trò chuyện nơi bạn yêu cầu (hoặc kênh chính).

Kiểm tra sức khỏe máy chủ​

Every 6 hours, check disk usage with 'df -h', memory with 'free -h',
and Docker container status with 'docker ps'. Report anything unusual —
partitions above 80%, containers that have restarted, or high memory usage.

Quản lý các tác vụ đã lên lịch​

# From the CLI
hermes cron list          

# View all scheduled jobs
hermes cron status        

# Check if scheduler is running

# From Telegram chat
/cron list                

# View jobs
/cron remove <job_id>     

# Remove a job

cảnh báo

Lời nhắc công việc định kỳ chạy trong các phiên hoàn toàn mới mà không có bộ nhớ về các cuộc hội thoại trước đó. Đảm bảo mỗi lời nhắc đều chứa tất cả ngữ cảnh mà tổng đài viên cần — đường dẫn tệp, URL, địa chỉ máy chủ và hướng dẫn rõ ràng.

Mẹo sản xuất

Sử dụng Docker để đảm bảo an toàn​

Trên bot nhóm dùng chung, hãy sử dụng Docker làm chương trình phụ trợ đầu cuối để các lệnh tác nhân chạy trong vùng chứa thay vì trên máy chủ của bạn:

# In ~/.hermes/.env
TERMINAL_BACKEND=docker
TERMINAL_DOCKER_IMAGE=nikolaik/python-nodejs:python3.11-nodejs20

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

terminal:
  backend: docker
  container_cpu: 1
  container_memory: 5120
  container_persistent: true

Bằng cách này, ngay cả khi ai đó yêu cầu bot chạy thứ gì đó có tính chất phá hoại, hệ thống máy chủ của bạn vẫn được bảo vệ.

Giám sát Cổng​

# Check if the gateway is running
hermes gateway status

# Watch live logs (Linux)
journalctl --user -u hermes-gateway -f

# Watch live logs (macOS)
tail -f ~/.hermes/logs/gateway.log

Luôn cập nhật Hermes​

Từ Telegram, gửi /update tới bot — nó sẽ lấy phiên bản mới nhất và khởi động lại. Hoặc từ máy chủ:

hermes update
hermes gateway stop && hermes gateway start

Đăng nhập vị trí​

Cái gìVị trí
Nhật ký cổngjournalctl --user -u hermes-gateway (Linux) hoặc ~/.hermes/logs/gateway.log (macOS)
Đầu ra công việc định kỳ~/.hermes/cron/output/{job_id}/{timestamp}.md
Định nghĩa công việc định kỳ~/.hermes/cron/jobs.json
Ghép nối dữ liệu~/.hermes/pairing/
Lịch sử phiên~/.hermes/sessions/

Tiến xa hơn

Bạn đã có một nhóm làm việc trợ lý Telegram. Dưới đây là một số bước tiếp theo:- Hướng dẫn bảo mật — đi sâu vào ủy quyền, cách ly vùng chứa và phê duyệt lệnh

  • Cổng nhắn tin — tham chiếu đầy đủ về kiến trúc cổng, quản lý phiên và lệnh trò chuyện
  • Telegram Setup — chi tiết dành riêng cho nền tảng bao gồm tin nhắn thoại và TTS
  • Nhiệm vụ đã lên lịch — lập lịch cron nâng cao với các tùy chọn phân phối và biểu thức cron
  • Tệp ngữ cảnh — AGENTS.md, SOUL.md và .cursorrules để biết kiến thức về dự án
  • Personality — cài đặt trước tính cách tích hợp và định nghĩa tính cách tùy chỉnh
  • Thêm nhiều nền tảng hơn — cùng một cổng có thể chạy đồng thời Discord, Slack và WhatsApp
  • Câu hỏi hoặc vấn đề? Mở một vấn đề trên GitHub — hoan nghênh đóng góp.*