设置团队 Telegram 助手

hermes agent 设置团队 Telegram 助手

本教程将带你设置一个由 Hermes Agent 驱动的 Telegram 机器人，供多个团队成员使用。完成后，你的团队将拥有一个共享的 AI 助手，大家可以向它发送消息，以获得代码、研究、系统管理以及其他任何方面的帮助 —— 并通过按用户授权来确保安全。

我们正在构建什么

一个 Telegram 机器人，它可以：

任何已授权的团队成员都可以私信它寻求帮助 —— 代码审查、研究、shell 命令、调试
运行在你的服务器上，并拥有完整工具访问权限 —— 终端、文件编辑、Web 搜索、代码执行
按用户隔离会话 —— 每个人都有自己的对话上下文
默认安全 —— 只有已批准的用户可以交互，并支持两种授权方式
计划任务 —— 每日站会、健康检查和提醒会投递到团队频道。

前置条件

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

在服务器或 VPS 上安装了 Hermes Agent（不要安装在你的笔记本上 —— bot 需要持续运行）。如果还没有安装，请按照安装指南操作。
你自己的 Telegram 账号（bot 所有者）
已配置 LLM 提供商 —— 至少在 ~/.hermes/.env 中配置 OpenAI、Anthropic 或其他受支持提供商的 API key

步骤 1：创建 Telegram Bot

每个 Telegram bot 都从 @BotFather 开始 —— 这是 Telegram 官方用于创建 bot 的机器人。

打开 Telegram 并搜索 @BotFather，或访问 t.me/BotFather
发送 /newbot —— BotFather 会询问你两件事：
- 显示名称 —— 用户看到的名称（例如 Team Hermes Assistant）
- 用户名 —— 必须以 bot 结尾（例如 myteam_hermes_bot）
复制 bot token —— BotFather 会回复类似这样的内容：

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，然后粘贴：

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

警告

请保密你的 bot token。任何拥有该 token 的人都可以控制这个 bot。如果它泄露了，请在 BotFather 中使用 /revoke 生成新的 token。

步骤 2：配置 Gateway

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

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

hermes gateway setup

这会通过方向键选择引导你完成所有设置。选择 Telegram，粘贴你的 bot token，并在提示时输入你的用户 ID。

选项 B：手动配置

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

# 来自 BotFather 的 Telegram bot token
TELEGRAM_BOT_TOKEN=7123456789:AAH1bGciOiJSUzI1NiIsInR5cCI6Ikp...

# 你的 Telegram 用户 ID（数字）
TELEGRAM_ALLOWED_USERS=123456789

查找你的用户 ID

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

在 Telegram 上给 @userinfobot 发送消息

它会立即回复你的数字用户 ID

将该数字复制到 TELEGRAM_ALLOWED_USERS

步骤 3：启动 Gateway

快速测试

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

hermes gateway

你应该会看到类似这样的输出：

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

打开 Telegram，找到你的 bot，并给它发送一条消息。如果它回复了，说明已经成功。按 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，这样 gateway 子进程就能找到 Node.js 和 ffmpeg 等工具。如果你之后安装了新工具，请重新运行 hermes gateway install 来更新 plist。

验证它正在运行

hermes gateway status

然后在 Telegram 上给你的 bot 发送一条测试消息。你应该会在几秒内收到回复。

步骤 4：设置团队访问

现在让你的队友获得访问权限。有两种方法。

方法 A：静态允许列表

收集每个团队成员的 Telegram 用户 ID（让他们给 @userinfobot 发消息），并将它们添加为逗号分隔的列表：

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

更改后重启 gateway：

hermes gateway stop && hermes gateway start

方法 B：DM 配对（推荐用于团队）

DM 配对更加灵活 —— 你不需要提前收集用户 ID。它的工作方式如下：

队友私信 bot —— 由于他们不在允许列表中，bot 会回复一个一次性配对码：

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

队友将代码发送给你（通过任何渠道 —— Slack、邮箱、当面都可以）

你在服务器上批准它：

hermes pairing approve telegram XKGH5N7P

他们就加入了 —— bot 会立即开始响应他们的消息

管理已配对用户：

# 查看所有待处理和已批准用户
hermes pairing list

# 撤销某人的访问权限
hermes pairing revoke telegram 987654321

# 清除已过期的待处理代码
hermes pairing clear-pending

安全注意事项

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

步骤 5：配置 Bot

设置 Home Channel

Home channel 是 bot 投递 cron job 结果和主动消息的地方。如果没有设置，计划任务就没有地方发送输出。

选项 1：在 bot 已加入的任意 Telegram 群组或聊天中使用 /sethome 命令。

选项 2：在 ~/.hermes/.env 中手动设置：

TELEGRAM_HOME_CHANNEL=-1001234567890
TELEGRAM_HOME_CHANNEL_NAME="Team Updates"

要查找 channel ID，请将 @userinfobot 添加到群组中 —— 它会报告该群组的 chat ID。

配置工具进度显示

控制 bot 在使用工具时显示多少细节。在 ~/.hermes/config.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。

# 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 了解你的技术栈：

# 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

步骤 6：设置计划任务

Gateway 运行后，你可以安排定期任务，并将结果投递到团队频道。

每日站会摘要

在 Telegram 上给 bot 发送消息：

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 job，并将结果投递到你发起请求的聊天中（或 home channel）。

服务器健康检查

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                # 查看 jobs
/cron remove <job_id>     # 移除一个 job

警告

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

生产环境技巧

使用 Docker 提高安全性

在共享团队 bot 上，使用 Docker 作为终端后端，这样 Agent 命令会在容器中运行，而不是在宿主机上运行：

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

这样，即使有人要求 bot 运行破坏性内容，你的宿主系统也会受到保护。

监控 Gateway

# 检查 gateway 是否正在运行
hermes gateway status

# 查看实时日志（Linux）
journalctl --user -u hermes-gateway -f

# 查看实时日志（macOS）
tail -f ~/.hermes/logs/gateway.log

保持 Hermes 更新

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

hermes update
hermes gateway stop && hermes gateway start

日志位置

内容	位置
Gateway logs	`journalctl --user -u hermes-gateway`（Linux）或 `~/.hermes/logs/gateway.log`（macOS）
Cron job output	`~/.hermes/cron/output/{job_id}/{timestamp}.md`
Cron job definitions	`~/.hermes/cron/jobs.json`
Pairing data	`~/.hermes/pairing/`
Session history	`~/.hermes/sessions/`

进一步探索

你已经拥有了一个可用的团队 Telegram 助手。下面是一些后续方向：

Security Guide —— 深入了解授权、容器隔离和命令审批
Messaging Gateway —— gateway 架构、会话管理和聊天命令的完整参考
Telegram Setup —— 平台特定细节，包括语音消息和 TTS
Scheduled Tasks —— 带有投递选项和 cron 表达式的高级 cron 调度
Context Files —— 用于项目知识的 AGENTS.md、SOUL.md 和 .cursorrules
Personality —— 内置个性预设和自定义 persona 定义
添加更多平台 —— 同一个 gateway 可以同时运行 Discord、Slack 和 WhatsApp。