設置團隊 Telegram 助手

本教程將指導你如何設置一個由 Hermes Agent 驅動的 Telegram 機器人，供團隊成員多人使用。完成之後，你的團隊將擁有一位共享的 AI 助手，可以通過消息向其尋求代碼、研究、系統管理及其他任務的幫助——並配有基於用戶的授權機制，確保安全。

我們要構建什麼

一個 Telegram 機器人，具備以下功能：

任何已授權的團隊成員 都可以通過私信（DM）向其求助——代碼審查、研究、Shell 命令、調試等
在你的服務器上運行，擁有完整的工具訪問權限——終端、文件編輯、網絡搜索、代碼執行
基於用戶的獨立會話 —— 每位用戶都擁有自己的對話上下文
默認安全 —— 僅允許經過批准的用戶交互，支持兩種授權方式
定時任務 —— 每日站會、健康檢查和提醒將自動發送至團隊頻道

先決條件

開始之前，請確保你已具備以下條件：

已在服務器或 VPS 上安裝 Hermes Agent（不要在你的筆記本電腦上運行——機器人需要持續運行）。如果尚未安裝，請參考安裝指南。
一個 Telegram 賬號（用於你自己，即機器人所有者）
已配置 LLM 提供商 —— 至少需要一個 OpenAI、Anthropic 或其他支持的提供商的 API 密鑰，存放在 ~/.hermes/.env 中

提示

每月 5 美元的 VPS 足夠運行網關。Hermes 本身非常輕量——費用主要來自遠程的 LLM API 調用。

第一步：創建 Telegram 機器人

每個 Telegram 機器人都始於 @BotFather —— Telegram 官方的機器人創建工具。

打開 Telegram，搜索 @BotFather，或訪問 t.me/BotFather
發送 /newbot —— BotFather 會詢問你兩個問題：
- 顯示名稱 —— 用戶看到的名稱（例如：Team Hermes Assistant）
- 用戶名 —— 必須以 bot 結尾（例如：myteam_hermes_bot）
複製機器人令牌 —— BotFather 會回覆類似內容：
```
Use this token to access the HTTP API:
7123456789:AAH1bGciOiJSUzI1NiIsInR5cCI6Ikp...
```
請保存此令牌——你將在下一步中用到。

設置描述（可選但推薦）：

/setdescription

選擇你的機器人，然後輸入類似內容：

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

設置機器人命令（可選——為用戶提供命令菜單）：

/setcommands

選擇你的機器人，然後粘貼：

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

注意

請務必保密你的機器人令牌。任何持有令牌的人都能控制該機器人。如果令牌洩露，請在 BotFather 中使用 /revoke 生成新令牌。

第二步：配置網關

你有兩種選擇：交互式設置嚮導（推薦）或手動配置。

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

hermes gateway setup

該向導將引導你完成所有步驟，使用方向鍵進行選擇。選擇 Telegram，粘貼你的機器人令牌，並在提示時輸入你的用戶 ID。

選項 B：手動配置

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

# 來自 BotFather 的 Telegram 機器人 token
TELEGRAM_BOT_TOKEN=7123456789:AAH1bGciOiJSUzI1NiIsInR5cCI6Ikp...

# 您的 Telegram 用戶 ID（數字）
TELEGRAM_ALLOWED_USERS=123456789

查找你的用戶 ID

你的 Telegram 用戶 ID 是一個數字（不是你的用戶名）。如何查找：

在 Telegram 中向 @userinfobot 發送消息
它會立即回覆你的數字用戶 ID
將該數字複製到 TELEGRAM_ALLOWED_USERS 中

信息

Telegram 用戶 ID 是永久性的數字，如 123456789。它們與你的 @username 不同，後者可能更改。始終使用數字 ID 作為白名單。

第三步：啟動網關

快速測試

首先在前臺運行網關，以確保一切正常：

hermes gateway

你應該看到類似輸出：

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

打開 Telegram，找到你的機器人併發送一條消息。如果它回覆了，說明一切正常。按 Ctrl+C 停止運行。

生產環境：作為服務安裝

為了實現持久化部署，確保重啟後仍能運行：

hermes gateway install
sudo hermes gateway install --system   # 僅限 Linux：啟動時系統服務

這將創建一個後臺服務：默認在 Linux 上為用戶級 systemd 服務，在 macOS 上為 launchd 服務，或在你傳遞 --system 參數時為開機啟動的 Linux 系統服務。

# Linux — 管理默認用戶服務
hermes gateway start
hermes gateway stop
hermes gateway status

# 查看實時日誌
journalctl --user -u hermes-gateway -f

# SSH 註銷後繼續運行
sudo loginctl enable-linger $USER

# Linux 服務器 — 顯式系統服務命令
sudo hermes gateway start --system
sudo hermes gateway status --system
journalctl -u hermes-gateway -f

# macOS — 管理服務
hermes gateway start
hermes gateway stop
tail -f ~/.hermes/logs/gateway.log

macOS PATH

launchd plist 在安裝時捕獲了你的 shell PATH，因此網關的子進程可以找到 Node.js、ffmpeg 等工具。如果你之後安裝了新工具，請重新運行 hermes gateway install 以更新 plist。

驗證是否正在運行

hermes gateway status

然後向你的 Telegram 機器人發送一條測試消息。你應該在幾秒內收到回覆。

第四步：設置團隊訪問權限

現在讓我們為團隊成員設置訪問權限。有兩種方法。

方法 A：靜態白名單

收集每位團隊成員的 Telegram 用戶 ID（讓他們向 @userinfobot 發送消息），然後以逗號分隔的形式添加到配置中：

# 在“0”中
TELEGRAM_ALLOWED_USERS=123456789,987654321,555555555

修改後重啟網關：

hermes gateway stop && hermes gateway start

方法 B：私信配對（推薦用於團隊）

DM 配對更加靈活——你無需提前收集用戶 ID。其工作原理如下：

團隊成員向機器人發送私信 —— 由於他們不在白名單中，機器人會回覆一個一次性配對碼：
```
🔐 Pairing code: XKGH5N7P
Send this code to the bot owner for approval.
```
同事將代碼發送給你（通過任意渠道——Slack、郵件、當面）

你在服務器上批准該代碼：

hermes pairing approve telegram XKGH5N7P

他們即可接入——機器人會立即開始響應他們的消息

管理配對用戶：

# 查看所有待處理和已批准的用戶
hermes pairing list

# 撤銷某人的訪問權限
hermes pairing revoke telegram 987654321

# 清除過期的待處理代碼
hermes pairing clear-pending

提示

私聊配對非常適合團隊使用，因為添加新用戶時無需重啟網關。批准立即生效。

安全注意事項

切勿在具有終端訪問權限的機器人上設置 GATEWAY_ALLOW_ALL_USERS=true ——任何找到你機器人的人都可能在你的服務器上運行命令
配對碼在 1 小時後過期，並使用加密隨機性生成
速率限制可防止暴力破解攻擊：每用戶每 10 分鐘最多 1 次請求，每個平臺最多 3 個待處理的配對碼
連續 5 次批准失敗後，平臺將進入 1 小時鎖定狀態
所有配對數據均以 chmod 0600 權限存儲

第 5 步：配置機器人

設置主頻道

主頻道是機器人發送定時任務結果和主動消息的頻道。如果沒有設置主頻道，計劃任務將無處發送輸出。

選項 1： 在機器人是成員的任意 Telegram 群組或聊天中使用 /sethome 命令。

選項 2： 手動在 ~/.hermes/.env 中設置：

TELEGRAM_HOME_CHANNEL=-1001234567890
TELEGRAM_HOME_CHANNEL_NAME="Team Updates"

要查找頻道 ID，請將 @userinfobot 添加到群組中——它會報告該群組的聊天 ID。

配置工具執行狀態顯示

控制機器人在使用工具時顯示的詳細程度。在 ~/.hermes/config.yaml 中：

display:
  tool_progress: new    # 關閉 |新 |全部 |冗長的

模式	你看到的內容
`off`	僅顯示簡潔響應——無工具活動信息
`new`	每次新工具調用顯示簡要狀態（推薦用於消息交互）
`all`	顯示每次工具調用的詳細信息
`verbose`	顯示完整工具輸出，包括命令執行結果

用戶也可以通過在聊天中使用 /verbose 命令來按會話更改此設置。

使用 SOUL.md 設置個性

通過編輯 ~/.hermes/SOUL.md 來自定義機器人的溝通方式：

完整指南請參見使用 SOUL.md 與 Hermes。

# 靈魂
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.

添加項目上下文

如果你的團隊專注於特定項目，請創建上下文文件，讓機器人瞭解你的技術棧：

<!-- ~/.hermes/AGENTS.md -->
# 團隊 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

信息

上下文文件會被注入到每個會話的系統提示中。請保持簡潔——每個字符都會計入你的 token 預算。

第 6 步：設置定時任務

在網關運行後，你可以安排重複執行的任務，並將結果發送到團隊頻道。

每日站會摘要

在 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.

該 Agent 會自動創建一個定時任務，並將結果發送到你提問的聊天（或主頻道）。

服務器健康檢查

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.

管理定時任務

# 來自CLI
hermes cron list          # 查看所有預定的作業
hermes cron status        # 檢查調度程序是否正在運行

# 來自 Telegram 聊天
/cron list                # 查看職位
/cron remove <job_id>     # 刪除職位

注意

定時任務提示在完全獨立的新會話中運行，不保留之前對話的記憶。請確保每個提示中包含所有Agent 所需的上下文——包括文件路徑、URL、服務器地址和清晰的指令。

生產環境建議

使用 Docker 提升安全性

在共享團隊機器人中，使用 Docker 作為終端後端，使 Agent 命令在容器中運行，而非在主機上：

# 在“0”中
TERMINAL_BACKEND=docker
TERMINAL_DOCKER_IMAGE=nikolaik/python-nodejs:python3.11-nodejs20

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

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

這樣即使有人要求機器人運行破壞性命令，你的主機系統也受到保護。

監控網關

# 檢查 Gateway 是否正在運行
hermes gateway status

# 觀看實時日誌（Linux）
journalctl --user -u hermes-gateway -f

# 觀看實時日誌（macOS）
tail -f ~/.hermes/logs/gateway.log

保持 Hermes 更新

從 Telegram 向機器人發送 /update 命令——它將拉取最新版本並重啟。或從服務器執行：

hermes update
hermes gateway stop && hermes gateway start

日誌位置

內容	位置
網關日誌	`journalctl --user -u hermes-gateway`（Linux）或 `~/.hermes/logs/gateway.log`（macOS）
定時任務輸出	`~/.hermes/cron/output/{job_id}/{timestamp}.md`
定時任務定義	`~/.hermes/cron/jobs.json`
配對數據	`~/.hermes/pairing/`
會話歷史	`~/.hermes/sessions/`

進階使用

你已經成功搭建了一個團隊用的 Telegram 助手。以下是一些後續步驟：

安全指南 —— 深入瞭解授權、容器隔離和命令審批
消息網關 —— 網關架構、會話管理及聊天命令的完整參考
Telegram 設置 —— 包括語音消息和文本轉語音（TTS）的平臺特定細節
定時任務 —— 高級定時調度，支持交付選項和 cron 表達式
上下文文件 —— AGENTS.md、SOUL.md 和 .cursorrules 用於項目知識管理
個性設置 —— 內置個性預設和自定義人格定義
添加更多平臺——同一網關可同時運行 Discord、Slack 和 WhatsApp

有疑問或問題？在 GitHub 上打開一個議題 —— 歡迎貢獻。

我們要構建什麼​

先決條件​

第一步：創建 Telegram 機器人​

第二步：配置網關​

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

選項 B：手動配置​

查找你的用戶 ID​

第三步：啟動網關​

快速測試​

生產環境：作為服務安裝​

驗證是否正在運行​

第四步：設置團隊訪問權限​

方法 A：靜態白名單​

方法 B：私信配對（推薦用於團隊）​

安全注意事項​

第 5 步：配置機器人​

設置主頻道​

配置工具執行狀態顯示​

使用 SOUL.md 設置個性​

添加項目上下文​

第 6 步：設置定時任務​

每日站會摘要​

服務器健康檢查​

管理定時任務​

生產環境建議​

使用 Docker 提升安全性​

監控網關​

保持 Hermes 更新​

日誌位置​

進階使用​