H繁中版
文件Flows社群 Repos開始使用
文件教學與最佳實踐team telegram assistant
<!-- Source: https://hermesbible.com/docs/guides/team-telegram-assistant -->

設定團隊 Telegram 助手

本教學將引導你設定一個由 Hermes Agent 驅動的 Telegram 機器人，供多位團隊成員使用。完成後，你的團隊將擁有一個共享的 AI 助手，可以訊息它尋求程式碼、研究、系統管理等方面的幫助——並透過每用戶授權確保安全。

我們正在建構什麼

一個 Telegram 機器人：

  • 任何已授權的團隊成員都可以私訊它尋求幫助——程式碼審查、研究、Shell 命令、除錯
  • 在你的伺服器上運行，具有完整的工具存取權限——終端、檔案編輯、網路搜尋、程式碼執行
  • 每用戶會話——每個人都有自己的對話上下文
  • 預設安全——只有經過核准的用戶才能互動，提供兩種授權方式
  • 排程任務——每日站會、健康檢查和提醒發送到團隊頻道

前置條件

開始之前，請確保你已具備：

  • Hermes Agent 已安裝在伺服器或 VPS 上（不是你的筆記型電腦——機器人需要持續運行）。如果你尚未安裝，請遵循安裝指南。
  • 一個 Telegram 帳號用於你自己（機器人擁有者）
  • 已設定一個 LLM 供應商——至少在 ~/.hermes/.env 中配置了 OpenAI、Anthropic 或其他支援的供應商的 API 金鑰

提示

每月 $5 的 VPS 就足以運行閘道。Hermes 本身很輕量——LLM API 呼叫才是花錢的部分，而這些是遠端發生的。

步驟 1：建立 Telegram 機器人

每個 Telegram 機器人都從 @BotFather 開始——Telegram 用於建立機器人的官方機器人。

  1. 開啟 Telegram 並搜尋 @BotFather，或前往 t.me/BotFather

  2. 傳送 /newbot — BotFather 會問你兩件事：

    • 顯示名稱 — 用戶看到的名稱（例如 Team Hermes Assistant）
    • 使用者名稱 — 必須以 bot 結尾（例如 myteam_hermes_bot）

  3. 複製機器人 token — BotFather 會回覆類似這樣的內容：

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

    儲存此 token——你將在下一步中使用它。

  4. 設定描述（可選但建議）：

    /setdescription

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

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

  5. 設定機器人命令（可選——為用戶提供命令選單）：

    /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

警告

保持你的機器人 token 機密。任何擁有 token 的人都可以控制機器人。如果它洩露了，請在 BotFather 中使用 /revoke 來產生一個新的。

步驟 2：設定閘道

你有兩個選擇：互動式設定精靈（推薦）或手動設定。

選項 A：互動式設定（推薦）

hermes gateway setup

這會透過方向鍵選擇引導你完成所有設定。選擇 Telegram，貼上你的機器人 token，並在提示時輸入你的用戶 ID。

選項 B：手動設定

在 ~/.hermes/.env 中新增以下行：

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

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

尋找你的用戶 ID

你的 Telegram 用戶 ID 是一個數值（不是你的使用者名稱）。要找到它：

  1. 在 Telegram 上訊息 @userinfobot
  2. 它會立即回覆你的數字用戶 ID
  3. 複製該數字到 TELEGRAM_ALLOWED_USERS

資訊

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

步驟 3：啟動閘道

快速測試

先在前台運行閘道以確保一切正常：

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 上向你的機器人傳送測試訊息。你應該在幾秒鐘內收到回應。

步驟 4：設定團隊存取

現在讓你的團隊成員獲得存取權限。有兩種方法。

方法 A：靜態白名單

收集每位團隊成員的 Telegram 用戶 ID（讓他們訊息 @userinfobot）並以逗號分隔的列表新增他們：

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

變更後重啟閘道：

hermes gateway stop && hermes gateway start

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

DM 配對更靈活——你不需要事先收集用戶 ID。以下是它的工作原理：

  1. 團隊成員私訊機器人 — 由於他們不在白名單中，機器人會回覆一個一次性配對碼：

    🔐 Pairing code: XKGH5N7P
Send this code to the bot owner for approval.

  2. 團隊成員將代碼傳送給你（透過任何管道——Slack、Email、面對面）

  3. 你在伺服器上核准它：

    hermes pairing approve telegram XKGH5N7P

  4. 他們就加入了 — 機器人立即開始回應他們的訊息

管理已配對的用戶：

# 查看所有待核准和已核准的用戶
hermes pairing list

# 撤銷某人的存取權限
hermes pairing revoke telegram 987654321

# 清除過期的待配對碼
hermes pairing clear-pending

提示

DM 配對非常適合團隊，因為你不需要在新增用戶時重啟閘道。核准會立即生效。

安全考量

  • 永遠不要在具有終端存取權限的機器人上設定 GATEWAY_ALLOW_ALL_USERS=true — 任何找到你機器人的人都可以在你的伺服器上執行命令
  • 配對碼在 1 小時後過期，並使用加密隨機性
  • 速率限制防止暴力攻擊：每用戶每 10 分鐘 1 個請求，每個平台最多 3 個待配對碼
  • 5 次核准嘗試失敗後，平台會進入 1 小時鎖定
  • 所有配對資料以 chmod 0600 權限儲存

步驟 5：設定機器人

設定主頻道

主頻道是機器人投遞 cron 任務結果和主動訊息的地方。沒有主頻道，排程任務就沒有地方發送輸出。

選項 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
模式你看到的內容
off僅乾淨的回應——無工具活動
new每個新工具呼叫的簡短狀態（推薦用於訊息傳遞）
all每個工具呼叫及其詳細資訊
verbose完整的工具輸出，包括命令結果

用戶也可以在聊天中使用 /verbose 命令在每個會話中更改此設定。

使用 SOUL.md 設定個性

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

完整指南請參閱在 Hermes 中使用 SOUL.md。

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

新增專案上下文

如果你的團隊在特定專案上工作，請建立上下文檔案以便機器人了解你的技術棧：

<!-- ~/.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

資訊

上下文檔案會注入到每個會話的系統提示中。保持它們簡潔——每個字元都會影響你的 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.

代理會自動建立一個 cron 任務，並將結果投遞到你提問的聊天（或主頻道）。

伺服器健康檢查

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>     # 移除任務

警告

Cron 任務提示在完全新鮮的會話中運行，沒有先前對話的記憶。確保每個提示包含代理所需的所有上下文——檔案路徑、URL、伺服器位址和明確的指示。

生產環境提示

使用 Docker 確保安全

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

# 在 ~/.hermes/.env 中
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

這樣，即使有人要求機器人執行某些破壞性操作，你的主機系統也能受到保護。

監控閘道

# 檢查閘道是否正在運行
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）
Cron 任務輸出~/.hermes/cron/output/{job_id}/{timestamp}.md
Cron 任務定義~/.hermes/cron/jobs.json
配對資料~/.hermes/pairing/
會話歷史~/.hermes/sessions/

進一步了解

你已經擁有了一個可以運作的團隊 Telegram 助手。以下是一些下一步：

  • 安全指南 — 深入了解授權、容器隔離和命令核准
  • 訊息閘道 — 閘道架構、會話管理和聊天命令的完整參考
  • Telegram 設定 — 平台特定的細節，包括語音訊息和 TTS
  • 排程任務 — 進階的 cron 排程、投遞選項和 cron 表達式
  • 上下文檔案 — AGENTS.md、SOUL.md 和 .cursorrules 用於專案知識
  • 個性 — 內建個性預設和自訂角色定義
  • 新增更多平台 — 同一個閘道可以同時運行 Discord、Slack 和 WhatsApp

有問題或錯誤？請在 GitHub 上開一個 issue——歡迎貢獻。

將 Hermes 作為 Python 函式庫使用

run nemotron 3 ultra freetips