Skip to main content

教程：团队 Telegram 助手

本文将指导你如何创建一个功能强大的 Telegram 机器人，供整个团队使用，支持代码调试、技术研究、系统运维、文档查询等多种场景。我们将结合 Hermes Agent 和 OpenRouter 等工具，实现智能响应与多模型支持。

🛠️ 第一步：准备你的 Telegram Bot​

1. 创建 Bot 并获取 Token​

  • 打开 Telegram。
  • 搜索 @BotFather。
  • 发送 /newbot 命令。
  • 按提示输入机器人名称（如 TeamCodeHelperBot）和用户名（如 teamcodehelper_bot）。
  • 成功后，BotFather 会返回一个 API Token（形如 123456789:ABC-DefghijklmnoPqrstuVwxyZ），请妥善保存。

✅ 提示：建议为团队创建专用账号或频道，避免个人账号被滥用。

🔧 第二步：部署机器人后端服务​

我们推荐使用 Hermes Agent 来构建智能代理，它支持多模型、插件扩展和团队协作。

1. 部署 Hermes Agent（推荐方式）​

方式一：使用 Modal 快速部署（最简单）​

# 安装 Modal CLI
pip install modal

# 克隆 Hermes Agent 示例项目
git clone https://github.com/agentskills-io/hermes-agent.git
cd hermes-agent

# 部署到 Modal
modal deploy app.py

部署完成后，你会获得一个公网 URL（如 https://hermes-agent.modal.run），这是你的机器人 Webhook 地址。

方式二：本地运行（适合测试）​

# 安装依赖
pip install -r requirements.txt

# 启动服务
python app.py

🤖 第三步：配置 Telegram Bot Webhook​

1. 设置 Webhook 到你的服务器​

使用 BotFather 或直接调用 Telegram API：

curl -X POST "https://api.telegram.org/bot<YOUR_TOKEN>/setWebhook" \
     -d "url=https://your-domain.com/webhook"

替换 <YOUR_TOKEN> 为你的 Bot Token，https://your-domain.com/webhook 为你部署的服务路径。

⚠️ 注意：

  • Webhook 必须是 HTTPS。
  • 如果使用本地开发，可借助 ngrok 生成临时公网地址： 
    ngrok http 8000
    然后使用 https://xxxxx.ngrok.io/webhook 设置 webhook。

2. 测试连接​

发送一条消息给你的 Bot，如果收到回复，则说明 Webhook 已成功连接。

🌐 第四步：集成 OpenRouter + 多模型支持​

Hermes Agent 支持通过 OpenRouter 调用多种大模型，包括：

  • Nous Research 系列（如 nous-hermes-2-mixtral-8x7b）
  • OpenAI 模型（如 gpt-4-turbo, gpt-3.5-turbo）
  • Mistral, Llama, Google Gemini 等

1. 获取 OpenRouter API Key​

2. 在 Hermes Agent 中配置模型​

编辑 config.yaml 或环境变量：

openrouter:
  api_key: sk-or-v1-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
  default_model: nous-hermes-2-mixtral-8x7b
  temperature: 0.3
  max_tokens: 2048

💡 推荐使用 nous-hermes-2-mixtral-8x7b，它在代码理解、推理和系统管理方面表现优异。

🎯 第五步：启用团队协作功能​

1. 添加团队成员到 Bot​

  • 让每个成员私聊 Bot 并发送 /start。
  • 可通过 /help 查看可用命令。

2. 支持的功能列表（自动识别上下文）​

功能使用示例
✅ 代码解释“这段 Python 代码是做什么的？”
✅ 代码修复“为什么这个函数报错？帮我改一下。”
✅ 代码生成“写一个用 Flask 实现的 REST API”
✅ 系统命令“检查服务器磁盘空间”
✅ 日志分析“分析这个 Nginx 错误日志”
✅ 技术调研“对比 Redis 和 Memcached 的优缺点”
✅ 文档生成“根据接口文档生成 Swagger YAML”

📌 所有对话均保留上下文，支持连续追问。

📦 第六步：高级功能（可选）​

1. 插件扩展（如数据库查询、CI/CD 查询）​

Hermes Agent 支持自定义插件，例如：

@plugin("db_query")
def query_database(query: str):
    # 连接 PostgreSQL / MySQL
    return execute_sql(query)

2. 多渠道接入（Slack/Discord/WhatsApp）​

通过 MCP (Multi-Channel Protocol) 支持跨平台统一接入。

3. 企业级权限控制​

  • 使用 @role:admin / @role:dev 标记用户角色。
  • 限制敏感操作（如删除文件、重启服务）仅限管理员执行。

📊 第七步：监控与维护​

1. 查看日志​

  • 在 Modal 或本地终端查看输出日志。
  • 使用 logging 模块记录每条请求。

2. 监控用量​

3. 定期更新模型与安全补丁​

🎁 附加资源​

✅ 总结：你已拥有一个团队级 AI 助手！​

现在，你的团队可以通过 Telegram 与一个智能机器人实时互动，解决：

  • ❓ 代码问题
  • 🔍 技术调研
  • 🛠️ 系统运维
  • 📝 文档撰写
  • 🔄 自动化任务

🚀 下一步建议：将 Bot 加入公司群组，设置 @mention 触发，让每个人都能随时提问。

💬 立即开始：
👉 点击这里部署你的团队机器人
👉 加入 Telegram 社区获取支持

本指南基于 Hermes Agent v1.2+ 构建，支持多模态、多语言、多平台。
适用于开发者、运维、产品经理、研究人员等所有角色。"

设置团队 Telegram 助手

本教程将引导你使用 Hermes Agent 部署一个由多个团队成员共同使用的 Telegram 机器人。完成之后，你的团队将拥有一位共享的 AI 助手，可通过私信向其寻求代码、研究、系统管理等各类帮助——所有交互均通过用户级授权保障安全。

我们要构建什么？​

一个 Telegram 机器人具备以下特性：

  • 任何经授权的团队成员均可发送私信求助 —— 代码审查、研究、Shell 命令、调试等
  • 在你的服务器上运行，拥有完整的工具访问权限 —— 终端、文件编辑、网络搜索、代码执行
  • 每位用户的独立会话 —— 每个人都拥有自己的对话上下文
  • 默认安全 —— 仅允许已批准的用户互动，支持两种授权方式
  • 定时任务 —— 每日站会、健康检查和提醒可自动推送到团队频道

先决条件​

开始前，请确保你已准备就绪：

  • 已在服务器或 VPS 上安装 Hermes Agent（不要在笔记本电脑上运行 —— 机器人需要持续在线）。若尚未安装，请参考 安装指南
  • 一个 Telegram 账号（用于机器人管理员）
  • 已配置 LLM 提供商 —— 至少需提供 OpenAI、Anthropic 或其他支持的提供商的 API 密钥，在 ~/.hermes/.env 中配置
tip

每月 $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 返回类似内容：

    使用此令牌访问 HTTP API：
    7123456789:AAH1bGciOiJSUzI1NiIsInR5cCI6Ikp...

    请妥善保存该令牌 —— 下一步将用到。

  4. 设置描述（可选但推荐）：

    /setdescription

    选择你的机器人，然后输入如下内容：

    由 Hermes Agent 驱动的团队 AI 助手。私信我获取代码、研究、调试等方面的支持。

  5. 设置机器人命令（可选 —— 为用户提供命令菜单）：

    /setcommands

    选择你的机器人，然后粘贴以下内容：

    new - 开始新对话
    model - 查看或更改 AI 模型
    status - 显示会话信息
    help - 显示可用命令
    stop - 停止当前任务
warning

请务必保密你的机器人令牌。任何人获得该令牌即可控制你的机器人。若发生泄露，请在 BotFather 中使用 /revoke 生成新令牌。

第二步：配置网关​

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

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

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 中
info

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

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

第四步：设置团队访问权限​

现在让我们为团队成员开通访问权限。有两种方法。

方法 A：静态白名单​

收集每位团队成员的 Telegram 用户 ID（让他们联系 @userinfobot 获取），并将它们以逗号分隔加入列表：

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

修改后重启网关：

hermes gateway stop && hermes gateway start

方法 B：私信配对（推荐用于团队）​

私信配对更灵活 —— 无需提前收集用户 ID。工作流程如下：

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

    🔐 配对码：XKGH5N7P
    请将此代码发送给机器人管理员以获取批准。

  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
tip

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

安全注意事项​

  • 切勿在具有终端访问权限的机器人上设置 GATEWAY_ALLOW_ALL_USERS=true —— 一旦被他人发现，攻击者可在你的服务器上执行任意命令
  • 配对码有效期为 1 小时，且使用加密随机生成
  • 限流机制防止暴力破解：每用户每 10 分钟最多 1 次请求，每平台最多 3 个待处理配对码
  • 连续 5 次失败审批尝试后，该平台将锁定 1 小时
  • 所有配对数据均以 chmod 0600 权限存储

第五步：配置机器人​

设置主频道​

主频道是机器人推送定时任务结果和主动消息的目标位置。若未设置，计划任务将无处发送输出。

选项 1： 在任意 Telegram 群组或聊天中使用 /sethome 命令（前提是机器人已在其中）。

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

TELEGRAM_HOME_CHANNEL=-1001234567890
TELEGRAM_HOME_CHANNEL_NAME="Team Updates"

要查找频道 ID，请将 @userinfobot 加入群组 —— 它会报告该群组的 chat 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
info

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

第六步：设置定时任务​

网关运行后，你可以安排定期任务，将结果推送到团队频道。

每日站会摘要​

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

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

服务器健康检查​

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
warning

定时任务提示在完全独立的新会话中运行，不会保留之前对话的记忆。请确保每个提示都包含全部所需上下文信息——包括文件路径、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 设置 —— 平台特定细节，包括语音消息与文本转语音功能
  • 计划任务 —— 高级 cron 调度，支持多种交付方式与 cron 表达式
  • 上下文文件 —— AGENTS.md、SOUL.md 与 .cursorrules 文件，用于项目知识管理
  • 个性设定 —— 内置个性模板与自定义角色定义
  • 接入更多平台 —— 相同的网关可同时支持 Discord、Slack 和 WhatsApp

有疑问或遇到问题？欢迎在 GitHub 上提交 Issue —— 欢迎贡献！