跳到主要内容

设置团队 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 官方的机器人创建工具。

  1. 打开 Telegram，搜索 @BotFather，或访问 t.me/BotFather

  2. 发送 /newbot —— BotFather 会询问你两个问题：

    • 显示名称 —— 用户看到的名称（例如：Team Hermes Assistant）
    • 用户名 —— 必须以 bot 结尾（例如：myteam_hermes_bot）

  3. 复制机器人令牌 —— BotFather 会回复类似内容：

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

    请保存此令牌——你将在下一步中用到。

  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
注意

请务必保密你的机器人令牌。任何持有令牌的人都能控制该机器人。如果令牌泄露，请在 BotFather 中使用 /revoke 生成新令牌。

第二步：配置网关​

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

hermes gateway setup

该向导将引导你完成所有步骤，使用方向键进行选择。选择 Telegram，粘贴你的机器人令牌，并在提示时输入你的用户 ID。

选项 B：手动配置​

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

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

# Your Telegram user ID (numeric)
TELEGRAM_ALLOWED_USERS=123456789

查找你的用户 ID​

你的 Telegram 用户 ID 是一个数字（不是你的用户名）。如何查找：

  1. 在 Telegram 中向 @userinfobot 发送消息
  2. 它会立即回复你的数字用户 ID
  3. 将该数字复制到 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 only: boot-time system service

这将创建一个后台服务：默认在 Linux 上为用户级 systemd 服务，在 macOS 上为 launchd 服务，或在你传递 --system 参数时为开机启动的 Linux 系统服务。

# Linux — manage the default user service
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 — explicit system-service commands
sudo hermes gateway start --system
sudo hermes gateway status --system
journalctl -u hermes-gateway -f
# macOS — manage the service
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 发送消息），然后以逗号分隔的形式添加到配置中：

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

修改后重启网关：

hermes gateway stop && hermes gateway start

DM 配对更加灵活——你无需提前收集用户 ID。其工作原理如下：

  1. 团队成员向机器人发送私信 —— 由于他们不在白名单中，机器人会回复一个一次性配对码：

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

  2. 同事将代码发送给你（通过任意渠道——Slack、邮件、当面）

  3. 你在服务器上批准该代码：

    hermes pairing approve telegram XKGH5N7P

  4. 他们即可接入——机器人会立即开始响应他们的消息

管理配对用户：

# 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
提示

私聊配对非常适合团队使用，因为添加新用户时无需重启网关。批准立即生效。

安全注意事项​

  • 切勿在具有终端访问权限的机器人上设置 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
模式你看到的内容
off仅显示简洁响应——无工具活动信息
new每次新工具调用显示简要状态（推荐用于消息交互）
all显示每次工具调用的详细信息
verbose显示完整工具输出，包括命令执行结果

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

使用 SOUL.md 设置个性​

通过编辑 ~/.hermes/SOUL.md 来自定义机器人的沟通方式：

完整指南请参见 使用 SOUL.md 与 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.

添加项目上下文​

如果你的团队专注于特定项目，请创建上下文文件，让机器人了解你的技术栈：

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

该代理会自动创建一个定时任务，并将结果发送到你提问的聊天（或主频道）。

服务器健康检查​

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.

管理定时任务​

# 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
注意

定时任务提示在完全独立的新会话中运行，不保留之前对话的记忆。请确保每个提示中包含所有代理所需的上下文——包括文件路径、URL、服务器地址和清晰的指令。

生产环境建议​

使用 Docker 提升安全性​

在共享团队机器人中，使用 Docker 作为终端后端，使代理命令在容器中运行，而非在主机上：

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

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

监控网关​

# 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 向机器人发送 /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 上打开一个议题 —— 欢迎贡献。