跳到主要内容

教程：团队 Telegram 助手

本教程会带你搭建一个由 Hermes Agent 驱动、可供多位团队成员共同使用的 Telegram 机器人。完成后，你的团队将拥有一个共享的 AI 助手，可以通过私信向它求助，处理代码、研究、系统管理等任务，并通过按用户授权的方式保证安全。

我们要构建什么​

一个 Telegram 机器人，具备这些能力：

  • 任何已授权团队成员 都可以通过私信向它求助，例如代码审查、研究、shell 命令和调试
  • 运行在你的服务器上，拥有完整工具访问能力，包括终端、文件编辑、Web 搜索和代码执行
  • 按用户隔离会话，每个人都有自己的对话上下文
  • 默认安全，只有已批准用户才能交互，并支持两种授权方式
  • 支持定时任务，可以把每日站会摘要、健康检查和提醒发送到团队频道

前置条件​

开始前请确认你已经具备：

  • 已在服务器或 VPS 上安装 Hermes Agent（不要装在你的笔记本上，因为机器人需要持续运行）。如果还没装，请先阅读 installation guide
  • 一个 Telegram 账号（作为 bot 所有者）
  • 已配置好一个 LLM 大模型提供商（provider），至少要在 ~/.hermes/.env 中配置 OpenAI、Anthropic 或其它受支持 provider 的 API key
提示

每月 5 美元左右的 VPS 就足够运行网关。Hermes 本身很轻量，真正产生费用的是远端 LLM API 调用。

第 1 步：创建 Telegram 机器人​

每个 Telegram 机器人都从 @BotFather 开始，它是 Telegram 官方提供的 bot 创建机器人。

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

  2. 发送 /newbot。BotFather 会询问两项内容：

    • Display name：用户看到的名称（例如 Team Hermes Assistant）
    • Username：必须以 bot 结尾（例如 myteam_hermes_bot）

  3. 复制 bot 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. 设置 bot commands（可选，可让用户看到命令菜单）：

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

请务必保管好 bot token。任何拿到这个 token 的人都可以控制你的机器人。如果泄露了，请立即在 BotFather 中使用 /revoke 重新生成。

第 2 步：配置网关​

你有两种方式：使用交互式安装向导（推荐），或者手动配置。

方式 A：交互式安装（推荐）​

hermes gateway setup

它会通过方向键选择的方式引导你完成全部配置。选择 Telegram，粘贴 bot token，并在提示时输入你的用户 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 不是一回事。做 allowlist 时一定要使用数字 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 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 中给 bot 发送一条测试消息。通常几秒内就能收到回复。

第 4 步：给团队开通访问​

接下来给团队成员开放访问。有两种方式。

方式 A：静态 allowlist​

收集团队成员的 Telegram 用户 ID（让他们都去私信 @userinfobot），然后把它们以逗号分隔形式加入：

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

修改后重启网关：

hermes gateway stop && hermes gateway start

方式 B：DM Pairing（团队更推荐）​

DM pairing 更灵活，不需要你提前收集团队成员 ID。流程如下：

  1. 队友先私信 bot。由于他还不在 allowlist 中，bot 会返回一个一次性 pairing code：

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

  2. 队友把这个 code 发给你（通过任何方式都行，比如 Slack、邮件或当面）

  3. 你在服务器上批准它：

    hermes pairing approve telegram XKGH5N7P

  4. 批准立即生效，之后 bot 就会开始回复这个队友的消息

管理已配对用户：

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

DM pairing 很适合团队场景，因为新增用户时不需要重启网关，批准后立即生效。

安全注意事项​

  • 不要在带终端访问能力的 bot 上设置 GATEWAY_ALLOW_ALL_USERS=true。任何发现 bot 的人都可能在你的服务器上执行命令
  • Pairing code 会在 1 小时后过期，并使用加密随机数生成
  • 有速率限制防止暴力破解：每个用户每 10 分钟最多 1 次请求，每个平台最多 3 个待处理 code
  • 连续 5 次批准失败后，该平台会进入 1 小时锁定期
  • 所有 pairing 数据都以 chmod 0600 权限存储

第 5 步：配置机器人​

设置 Home Channel​

home channel 是 bot 投递 cron 任务结果和主动消息的地方。如果没有它，定时任务就没有输出目的地。

方式 1： 在 bot 所在的任意 Telegram 群组或聊天中使用 /sethome

方式 2： 手动写入 ~/.hermes/.env：

TELEGRAM_HOME_CHANNEL=-1001234567890
TELEGRAM_HOME_CHANNEL_NAME="Team Updates"

如果你不知道频道 ID，可以把 @userinfobot 拉进群，它会返回该群的 chat ID。

配置工具进度显示​

你可以控制 bot 在使用工具时展示多少细节。在 ~/.hermes/config.yaml 中设置：

display:
  tool_progress: new    # off | new | all | verbose
ModeWhat You See
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.

加入项目上下文​

如果你的团队长期在几个固定项目上工作，可以创建 context files，让 bot 了解你们的技术栈：

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

Context files 会注入到每次会话的 system prompt 中。请尽量保持简洁，因为每个字符都会占用 token 预算。

第 6 步：设置定时任务​

当网关运行起来后，你就可以创建周期性任务，并把结果发送到团队频道。

每日站会摘要​

在 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 任务，并把结果投递到你发起请求的聊天（或 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.

管理定时任务​

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

Cron 任务的 prompt 总是在一个全新的会话中运行，不会继承你之前对话中的任何记忆。因此每个 prompt 都必须包含 全部 所需上下文，例如文件路径、URL、服务器地址和清晰的执行说明。

生产环境建议​

用 Docker 提升安全性​

如果这是一个团队共用的 bot，建议把 Docker 设成终端后端，这样 agent 的命令都在容器里执行，而不是直接跑在宿主机上：

# 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

这样即便有人要求 bot 执行破坏性命令，你的宿主系统也会受到保护。

监控网关​

# 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，它会拉取最新版本并重启。也可以直接在服务器上执行：

hermes update
hermes gateway stop && hermes gateway start

日志位置​

WhatLocation
Gateway logsjournalctl --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 —— 完整的网关架构、会话管理和聊天命令参考
  • Telegram Setup —— Telegram 平台专属细节，包括语音消息和 TTS
  • Scheduled Tasks —— 更高级的 cron 调度、投递选项和 cron 表达式
  • Context Files —— AGENTS.md、SOUL.md 和 .cursorrules 的项目知识管理
  • Personality —— 内置人格预设和自定义 persona 定义
  • 扩展更多平台 —— 同一个网关还可以同时运行 Discord、Slack 和 WhatsApp

有问题或遇到异常？欢迎在 GitHub 上提 issue，社区贡献也非常欢迎。