Hermes Agent Team Telegram Assistant：构建团队 Telegram 助手

本教程介绍如何使用 Hermes Agent 构建一个团队共享的 Telegram 助手，让团队成员可以通过 Telegram Bot 获取代码审查、研究辅助、系统管理等服务，并支持按用户授权和定时任务。

我们要构建什么

一个 Telegram Bot，具备以下能力：

授权团队成员均可私聊获取帮助——代码审查、研究辅助、Shell 命令、调试
运行在你的服务器上，拥有完整的工具访问权限——终端、文件编辑、Web 搜索、代码执行
按用户隔离会话——每位成员拥有独立的对话上下文
默认安全——仅批准的用户可以交互，提供两种授权方式
定时任务——每日站会、健康检查和提醒会推送到团队频道

前置条件

开始之前，确保你已具备：

Hermes Agent 已安装在服务器或 VPS 上（不要装在笔记本上——Bot 需要持续运行）。如果尚未安装，请参阅 installation guide。
一个 Telegram 账号（作为 Bot 所有者）
已配置 LLM 提供商——至少需要一个 OpenAI、Anthropic 或其他支持的提供商的 API Key，配置在 ~/.hermes/.env 中

:::tip 每月 5 美元的 VPS 就足够运行 Gateway 了。Hermes 本身很轻量——LLM API 调用才是主要开销，而这些调用发生在远程。 :::

第一步：创建 Telegram Bot

每个 Telegram Bot 都始于 @BotFather——Telegram 官方的 Bot 创建工具。

打开 Telegram，搜索 @BotFather，或访问 t.me/BotFather
发送 /newbot——BotFather 会要求你提供两项信息：
- 显示名称——用户看到的名称（例如 Team Hermes Assistant）
- 用户名——必须以 bot 结尾（例如 myteam_hermes_bot）
复制 Bot Token——BotFather 会返回类似以下内容：
text
```
Use this token to access the HTTP API:
7123456789:AAH1bGciOiJSUzI1NiIsInR5cCI6Ikp...
```
保存此 Token——下一步需要使用。
设置描述（可选但推荐）：
/setdescription
选择你的 Bot，然后输入类似内容：
Team AI assistant powered by Hermes Agent. DM me for help with code, research, debugging, and more.

设置 Bot 命令（可选——为用户提供命令菜单）：

/setcommands

选择你的 Bot，然后粘贴：

text

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

:::warning 保管好你的 Bot Token。任何拥有 Token 的人都可以控制该 Bot。如果 Token 泄露，在 BotFather 中使用 /revoke 生成新 Token。 :::

第二步：配置 Gateway

你有两种选择：交互式设置向导（推荐）或手动配置。

选项 A：交互式设置（推荐）

bash

hermes gateway setup

此命令会通过方向键选择引导你完成所有配置。选择 Telegram，粘贴你的 Bot Token，然后在提示时输入你的用户 ID。

选项 B：手动配置

将以下内容添加到 ~/.hermes/.env：

bash

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

# Your Telegram user ID (numeric)
TELEGRAM_ALLOWED_USERS=123456789

查找你的 User ID

你的 Telegram User ID 是一个数字（不是用户名）。查找方法：

在 Telegram 中发送消息给 @userinfobot
它会立即回复你的数字 User ID
将该数字复制到 TELEGRAM_ALLOWED_USERS 中

:::info Telegram User ID 是永久数字，如 123456789。它们与 @username 不同，用户名可以更改。白名单中始终使用数字 ID。 :::

第三步：启动 Gateway

快速测试

先在前台运行 Gateway，确保一切正常：

bash

hermes gateway

你应该看到类似输出：

text

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

打开 Telegram，找到你的 Bot，发送一条消息。如果收到回复，说明一切正常。按 Ctrl+C 停止。

生产环境：安装为服务

部署持久化服务，确保重启后自动恢复：

bash

hermes gateway install
sudo hermes gateway install --system   # Linux only: boot-time system service

此命令会创建后台服务：Linux 上默认创建用户级 systemd 服务，macOS 上创建 launchd 服务，如果传入 --system 参数则创建 Linux 启动级系统服务。

bash

# Linux — 管理默认用户服务
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 — 显式系统服务命令
sudo hermes gateway start --system
sudo hermes gateway status --system
journalctl -u hermes-gateway -f

bash

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

:::tip macOS PATH launchd plist 会在安装时捕获你的 shell PATH，使 Gateway 子进程能够找到 Node.js 和 ffmpeg 等工具。如果后续安装了新工具，需要重新运行 hermes gateway install 来更新 plist。 :::

验证运行状态

bash

hermes gateway status

然后在 Telegram 上向你的 Bot 发送测试消息。你应该在几秒内收到回复。

第四步：设置团队访问

现在让我们为团队成员授权。有两种方式。

方式 A：静态白名单

收集每位团队成员的 Telegram User ID（让他们发送消息给 @userinfobot），以逗号分隔添加：

bash

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

修改后重启 Gateway：

bash

hermes gateway stop && hermes gateway start

方式 B：DM 配对（推荐团队使用）

DM 配对更灵活——你不需要提前收集用户 ID。工作流程如下：

团队成员私聊 Bot——由于不在白名单中，Bot 会回复一个一次性配对码：
text
```
🔐 Pairing code: XKGH5N7P
Send this code to the bot owner for approval.
```
团队成员将配对码发给你（通过任何渠道——Slack、邮件、当面）

你在服务器上批准：

bash

hermes pairing approve telegram XKGH5N7P

完成——Bot 立即开始响应该成员的消息

管理已配对用户：

bash

# 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

:::tip DM 配对非常适合团队使用，因为添加新用户时无需重启 Gateway。批准即时生效。 :::

安全注意事项

切勿在拥有终端访问权限的 Bot 上设置 GATEWAY_ALLOW_ALL_USERS=true——任何发现你 Bot 的人都可以在你的服务器上执行命令
配对码在 1 小时后过期，使用加密随机性生成
速率限制防止暴力攻击：每用户每 10 分钟 1 次请求，每平台最多 3 个待处理配对码
5 次批准失败后，该平台进入 1 小时锁定
所有配对数据以 chmod 0600 权限存储

第五步：配置 Bot

设置 Home Channel

Home Channel 是 Bot 投递 Cron 任务结果和主动消息的地方。没有设置 Home Channel，定时任务将无处发送输出。

方式 1： 在 Bot 所在的任何 Telegram 群组或聊天中使用 /sethome 命令。

方式 2： 在 ~/.hermes/.env 中手动设置：

bash

TELEGRAM_HOME_CHANNEL=-1001234567890
TELEGRAM_HOME_CHANNEL_NAME="Team Updates"

要查找 Channel ID，将 @userinfobot 添加到群组——它会报告群组的 Chat ID。

配置工具进度显示

控制 Bot 使用工具时显示的详细程度。在 ~/.hermes/config.yaml 中：

yaml

display:
  tool_progress: new    # off | new | all | verbose

模式	显示内容
`off`	仅显示响应——无工具活动
`new`	每个新工具调用的简要状态（消息场景推荐）
`all`	每个工具调用及详细信息
`verbose`	完整工具输出，包括命令结果

用户也可以在聊天中使用 /verbose 命令按会话更改此设置。

使用 SOUL.md 设置个性

通过编辑 ~/.hermes/SOUL.md 自定义 Bot 的沟通方式：

完整指南请参阅 Use SOUL.md with Hermes。

markdown

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

添加项目上下文

如果你的团队在特定项目上工作，创建上下文文件让 Bot 了解你的技术栈：

markdown

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

:::info 上下文文件会注入到每个会话的系统提示中。保持简洁——每个字符都计入你的 Token 预算。 :::

第六步：设置定时任务

Gateway 运行后，你可以调度周期性任务，将结果推送到团队频道。

每日站会摘要

在 Telegram 上向 Bot 发送消息：

text

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 会自动创建 Cron 任务，并将结果投递到你提问的聊天（或 Home Channel）。

服务器健康检查

text

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.

管理定时任务

bash

# 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

:::warning Cron 任务提示词在全新的会话中运行，没有先前对话的记忆。确保每个提示词包含 Agent 需要的所有上下文——文件路径、URL、服务器地址和清晰的指令。 :::

生产环境建议

使用 Docker 确保安全

在共享团队 Bot 上，使用 Docker 作为终端后端，让 Agent 命令在容器中运行而非宿主机：

bash

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

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

yaml

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

这样，即使有人让 Bot 运行破坏性命令，你的宿主系统也受到保护。

监控 Gateway

bash

# 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

保持 Hermes 更新

在 Telegram 上向 Bot 发送 /update——它会拉取最新版本并重启。或在服务器上：

bash

hermes update
hermes gateway stop && hermes gateway start

日志位置

内容	位置
Gateway 日志	`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 助手。以下是一些后续步骤：

安全指南——深入了解授权、容器隔离和命令审批
消息网关——Gateway 架构、会话管理和聊天命令的完整参考
Telegram 设置——平台特定详情，包括语音消息和 TTS
定时任务——高级 Cron 调度，包含投递选项和 Cron 表达式
上下文文件——AGENTS.md、SOUL.md 和 .cursorrules 用于项目知识
个性设置——内置个性预设和自定义人格定义
添加更多平台——同一 Gateway 可以同时运行 Discord、Slack 和 WhatsApp

有问题或反馈？在 GitHub 上提交 Issue——欢迎贡献。

字节笔记本

Hermes Agent Team Telegram Assistant：构建团队 Telegram 助手

我们要构建什么

前置条件

第一步：创建 Telegram Bot

第二步：配置 Gateway

选项 A：交互式设置（推荐）

选项 B：手动配置

查找你的 User ID

第三步：启动 Gateway

快速测试

生产环境：安装为服务

验证运行状态

第四步：设置团队访问

方式 A：静态白名单

方式 B：DM 配对（推荐团队使用）

安全注意事项

第五步：配置 Bot

设置 Home Channel

配置工具进度显示

使用 SOUL.md 设置个性

添加项目上下文

第六步：设置定时任务

每日站会摘要

服务器健康检查

管理定时任务

生产环境建议

使用 Docker 确保安全

监控 Gateway

保持 Hermes 更新

日志位置

进阶探索