Hermes Agent HelperHermes Agent Helper

Telegram 配置完全指南：Hermes Agent 接入 Telegram Bot 教程

Hermes Agent Helperon a month ago

概述

Telegram 是一款全球流行的即时通讯应用，以其安全性和开放的 Bot API 著称。Hermes Agent 支持通过 Telegram Bot 与用户进行对话交互。本教程将指导你完成从创建 Bot 到配置 Hermes Gateway 的完整流程。

预计配置时间：5-10 分钟

所需信息：

  • Bot Token（通过 BotFather 获取）
  • 你的 Telegram User ID（用于授权访问）

第一步：创建 Telegram Bot

1.1 找到 BotFather

BotFather 是 Telegram 官方的 Bot 管理工具，所有 Bot 的创建都通过它完成。

  1. 打开 Telegram 应用
  2. 在搜索框中搜索 @BotFather
  3. 点击进入与 BotFather 的对话

提示：确保选择的是带有蓝色认证标志的官方 BotFather。

1.2 创建新 Bot

  1. 在 BotFather 对话中发送：

    /newbot

  2. BotFather 会要求你输入 Bot 的名称：

    • 这是显示名称，可以使用中文
    • 例如：Hermes AI 助手

  3. 接下来输入 Bot 的用户名：

    • 必须以 bot 结尾
    • 只能使用英文字母、数字和下划线
    • 例如：my_hermes_ai_bot

1.3 获取 Bot Token

创建成功后，BotFather 会返回一条消息，其中包含你的 Bot Token：

Done! Congratulations on your new bot. You will find it at t.me/my_hermes_ai_bot.

Use this token to access the HTTP API:
123456789:ABCdefGHIjklMNOpqrsTUVwxyz

请妥善保存这个 Token，它是访问 Bot API 的唯一凭证。

⚠️ 安全提醒：

  • 不要将 Token 分享给他人
  • 不要将 Token 提交到公开的代码仓库
  • 如果 Token 泄露，请立即通过 BotFather 使用 /revoke 命令重新生成

第二步：获取你的 Telegram User ID

Telegram User ID 用于授权哪些用户可以与 Bot 对话。

方法一：使用 @userinfobot（推荐）

  1. 在 Telegram 中搜索 @userinfobot
  2. 点击「Start」或发送任意消息
  3. 机器人会回复你的用户信息，其中包含 Id 字段

例如：

@your_username
Id: 123456789

这里的 123456789 就是你的 User ID。

方法二：使用 @getmyid_bot

  1. 在 Telegram 中搜索 @getmyid_bot
  2. 点击「Start」
  3. 机器人会直接返回你的 User ID

方法三：查看 Gateway 日志

  1. 先完成后续配置并启动 Gateway（暂时允许所有用户）
  2. 给你的 Bot 发送一条测试消息
  3. 查看 Gateway 日志，其中会包含发送者的 User ID

第三步：配置 Hermes Gateway

方式一：通过 Hermes 服务管理工具（推荐）

如果你使用的是我们的托管服务：

  1. 前往 Hermes 服务管理工具 页面
  2. 登录你的服务器管理界面
  3. 使用「Telegram Setup」快捷配置标签页：
    • 输入 Bot Token
    • 点击「完成配置」
  4. 系统会自动写入配置并重启 Gateway

或者在「Config」标签页手动配置：

  • gateway.telegram.bot_token：你的 Bot Token
  • gateway.telegram.allowed_users：授权的用户 ID（多个用逗号分隔）

方式二：通过交互式向导

在服务器终端中运行：

hermes gateway setup

按提示操作：

  1. 选择「Telegram」
  2. 输入 Bot Token
  3. 输入允许的用户 ID（多个用逗号分隔）

方式三：手动编辑配置文件

编辑 ~/.hermes/.env 文件，添加：

TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrsTUVwxyz
TELEGRAM_ALLOWED_USERS=123456789,987654321

环境变量说明：

  • TELEGRAM_BOT_TOKEN：必填，从 BotFather 获取的 Token
  • TELEGRAM_ALLOWED_USERS：可选，允许使用的用户 ID 列表，逗号分隔
  • 如果不设置 TELEGRAM_ALLOWED_USERS，需要设置 GATEWAY_ALLOW_ALL_USERS=true（不推荐用于生产环境）

第四步：启动并测试

4.1 启动 Gateway

前台运行（用于测试）：

hermes gateway run

或作为系统服务启动：

hermes gateway install
hermes gateway start

4.2 测试 Bot

  1. 在 Telegram 中找到你的 Bot（通过 BotFather 返回的链接）
  2. 点击「Start」或发送 /start
  3. 发送一条测试消息，如「你好」
  4. 如果配置正确，Bot 会回复 AI 生成的响应

可选配置

设置 Bot 描述和头像

通过 BotFather 可以进一步定制你的 Bot：

  1. 发送 /mybots 查看你的所有 Bot
  2. 选择要编辑的 Bot
  3. 可用选项：
    • Edit Bot → Edit Description：设置 Bot 描述
    • Edit Bot → Edit About Text：设置关于文字
    • Edit Bot → Edit Botpic：设置 Bot 头像

设置命令菜单

  1. 在 BotFather 中选择你的 Bot
  2. 选择 Edit Bot → Edit Commands
  3. 按格式添加命令： 
    start - 开始对话
help - 获取帮助
clear - 清除对话历史

常见问题

Q: Bot 不响应消息

可能原因：

  1. Gateway 未启动
  2. Bot Token 配置错误
  3. User ID 未在允许列表中

解决方法：

  1. 检查 Gateway 状态：hermes gateway status
  2. 确认 Token 正确无误
  3. 检查 TELEGRAM_ALLOWED_USERS 配置

Q: 收到 "Unauthorized" 错误

原因：Bot Token 无效或已被撤销

解决方法：

  1. 通过 BotFather 检查 Token 是否有效
  2. 如需要，使用 /revoke 重新生成 Token
  3. 更新配置文件中的 Token

Q: 消息延迟很高

可能原因：

  1. 服务器网络不稳定
  2. LLM API 响应慢

解决方法：

  1. 检查服务器到 Telegram 服务器的网络连接
  2. 考虑使用更快的 LLM 模型
  3. 检查 Gateway 日志中的响应时间

Q: 如何允许群组使用 Bot

默认情况下，Bot 只响应私聊消息。如需在群组中使用：

  1. 通过 BotFather 设置：/setprivacy → 选择 Bot → Disable
  2. 在配置中添加群组 ID（负数形式）到允许列表

相关资源

如有问题，请 联系我们 获取技术支持。