设置团队 Telegram 助手

本教程带你完成设置由 Hermes Agent 驱动的 Telegram 机器人的过程，多个团队成员都可以使用。最后，你的团队将拥有一个共享 AI 助手，他们可以消息联系它寻求代码、研究、系统管理等方面的帮助 — 通过每用户授权保护。

我们要构建的内容

一个 Telegram 机器人：

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

前置要求

开始之前，确保你拥有：

在服务器或 VPS 上安装的 Hermes Agent（不是你的笔记本电脑 — 机器人需要保持运行）。如果还没有，请遵循安装指南。
你自己的 Telegram 账户（机器人所有者）
配置好的 LLM 提供商 — 至少在 ~/.hermes/.env 中设置 OpenAI、Anthropic 或其他支持提供商的 API 密钥

提示

5 美元/月的 VPS 足以运行 gateway。Hermes 本身是轻量级的 — LLM API 调用才是花钱的地方，而这些是远程发生的。

步骤 1：创建 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

注意

保持你的机器人令牌秘密。拥有令牌的任何人都可以控制机器人。如果泄露了，用 /revoke 在 BotFather 中生成新的。

步骤 2：配置 Gateway

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

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

hermes gateway setup

这会带你用方向键选择完成所有配置。选择 Telegram，粘贴你的机器人令牌，并在提示时输入你的用户 ID。

选项 B：手动配置

将这些行添加到 ~/.hermes/.env：

# Telegram 机器人令牌（来自 BotFather）
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。

步骤 3：启动 Gateway

快速测试

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

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，以便 gateway 子进程可以找到 Node.js 和 ffmpeg 等工具。如果之后安装了新工具，重新运行 hermes gateway install 以更新 plist。

验证它正在运行

hermes gateway status

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

步骤 4：设置团队访问

现在让我们给你的队友访问权限。有两种方法。

方法 A：静态白名单

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

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

更改后重启 gateway：

hermes gateway stop && hermes gateway start

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

DM 配对更灵活 — 你不需要预先收集用户 ID。以下是它的工作原理：

队友 DM 机器人 — 由于他们不在白名单上，机器人回复一个一次性配对码：
```
🔐 Pairing code: XKGH5N7P
Send this code to the bot owner for approval.
```
队友通过任何渠道向你发送代码（Slack、email、当面）

你在服务器上批准它：

hermes pairing approve telegram XKGH5N7P

他们进来了 — 机器人立即开始回复他们的消息

管理配对用户：

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

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

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

提示

DM 配对是团队的理想选择，因为添加新用户时不需要重启 gateway。批准立即生效。

安全注意事项

永远不要在有终端访问的机器人上设置 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

信息

上下文文件被注入每个会话的系统提示词。保持简洁 — 每个字符都计入你的令牌预算。

步骤 6：设置定时任务

在 gateway 运行的情况下，你可以调度定期任务，将结果投递到你的团队频道。

每日站会摘要

在 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 自动创建 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 任务提示词在完全新鲜的会话中运行，没有先前对话的记忆。确保每个提示词包含 agent 需要的所有上下文 — 文件路径、URL、服务器地址和清晰指令。

生产技巧

使用 Docker 确保安全

在共享团队机器人上，使用 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

这样，即使有人要求机器人运行破坏性操作，你的主机系统也受到保护。

监控 Gateway

# 检查 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

日志位置

| 内容 | 位置 | | |------|----------| | | 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 — 欢迎贡献。

我们要构建的内容​

前置要求​

步骤 1：创建 Telegram 机器人​

步骤 2：配置 Gateway​

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

选项 B：手动配置​

查找你的用户 ID​

步骤 3：启动 Gateway​

快速测试​

生产环境：安装为服务​

验证它正在运行​

步骤 4：设置团队访问​

方法 A：静态白名单​

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

安全注意事项​

步骤 5：配置机器人​

设置家庭频道​

配置工具进度显示​

用 SOUL.md 设置人格​

添加项目上下文​

步骤 6：设置定时任务​

每日站会摘要​

服务器健康检查​

管理定时任务​

生产技巧​

使用 Docker 确保安全​

监控 Gateway​

保持 Hermes 更新​

日志位置​

进一步探索​