把 Hermes 搬进 Telegram：最流行的机器人平台

好嘞，今天咱们来聊聊怎么把 Hermes Agent 搬进 Telegram——没错，就是那个你手机里天天用的聊天软件。装好之后，你就能在任意设备上跟你的 AI 助手唠嗑了，发语音它还能自动转文字，定时任务的结果也会主动推给你，甚至拉进群聊里一起用。听起来是不是很带感？

快速设置（仪表盘和桌面应用）

如果你用的是仪表盘或桌面应用，可以直接走捷径：打开 Messaging → Telegram 页面，点 Create with QR 按钮，用 Telegram 扫码（或打开链接）。Hermes 会自动帮你创建机器人、识别你的 Telegram 用户 ID，把 TELEGRAM_BOT_TOKEN 和 TELEGRAM_ALLOWED_USERS 写进你配置的 .env 文件，然后重启网关。如果你更喜欢自己动手，就按下面的手动步骤来。

第一步：找 BotFather 要个“身份证”

每个 Telegram 机器人都有一个专属的 API Token，这玩意儿得找官方机器人管理员 @BotFather 要。操作很简单：

1. 打开 Telegram，搜索 @BotFather（或者直接访问 t.me/BotFather）
2. 发送 /newbot 命令
3. 给它起个显示名字，比如 “Hermes Agent”，随便起
4. 再设一个用户名，这个必须唯一，而且要以 bot 结尾，比如 my_hermes_bot
5. BotFather 会回你一串 Token，长这样：123456789:ABCdefGHIjklMNOpqrSTUvwxYZ

⚠️ 警告：这串 Token 就是你家机器人的钥匙，谁拿到谁就能控制它。万一泄露了，赶紧回 BotFather 用 /revoke 吊销重发。

第二步：给机器人“化妆”（可选）

想让机器人更好用？这几个 BotFather 命令值得一试：

命令	作用
/setdescription	设置用户开聊前看到的“机器人能干啥”介绍
/setabouttext	机器人主页的简介文字
/setuserpic	上传头像
/setcommands	定义聊天框里 / 菜单的快捷命令
/setprivacy	控制机器人是否能看到群聊里所有消息

小建议：/setcommands 可以先用这套：

help - 显示帮助
new - 开启新对话
sethome - 把当前聊天设为默认频道

在线状态小圆点（可选）

Telegram 机器人其实没有像真人账号那样的绿色“在线”圆点，那是用户账号专属的。最接近的替代品是机器人主页上的简介文字。

在配置文件里加上 status_indicator，Hermes 就会在网关连接时把简介改成“Online”，正常退出时改成“Offline”：

gateway:
  platforms:
    telegram:
      extra:
        status_indicator: true
        status_online: "🟢 Online"
        status_offline: "🔴 Offline"

注意：这个状态是全局的，所有用户都能看到，而且只有正常关闭（比如 /stop）才会显示 Offline，直接断电崩溃的话会保留上次的状态。

冷启动时的待处理消息队列（可选）

默认情况下，网关冷启动时会把 Telegram 服务器上堆积的待处理消息直接丢掉（第一次 start_polling 时 drop_pending_updates=True）。这对 7×24 常开的服务器挺合适——重启就当“清个场”，旧队列算过期。但如果你用的是会关机的机器（比如晚上关掉的台式机），就不太妙了：网关离线期间别人发的消息会躺在 Telegram 的队列里，下次开机时还没等 Hermes 看到就被静默丢弃了，没日志、没重试。

想让这些积压消息在启动时按顺序补收，就把 drop_pending_on_cold_boot 设成 false：

platforms:
  telegram:
    extra:
      drop_pending_on_cold_boot: false

几点说明：默认是 true，不主动开就跟以前一样；网络抖动导致的 watcher 重连（进程还活着）无论怎么设都会保留队列；冲突恢复那条路径还是会丢待处理消息，跟这个开关无关；崩溃后如果保留了队列，可能会重放一条崩溃前处理到一半的消息，Telegram 的 offset 一般能挡住，但长时间离线期间发的时效性命令会在开机时执行。

命令菜单：优先级和上限（可选）

Hermes 启动时会自动注册命令菜单，默认最多显示 60 个命令，保证 Telegram 能稳定接收。如果你有特别想让用户看到的插件或技能命令，可以给它们“加塞”：

platforms:
  telegram:
    extra:
      command_menu:
        max_commands: 60
        priority_mode: prepend  # prepend 优先 | append 靠后 | replace 只用自己的
        priority:
          - my_plugin_command
          - songsee

priority_mode 控制你的列表和 Hermes 内置优先级的合并方式。以前技能命令总是被字母排序挤掉，现在只要设置了优先级，就保证有位置，哪怕内置命令已经塞满了。

内联搜索：所有命令一网打尽

/ 菜单有上限，但 Telegram 的内联模式没有！在任意聊天框输入 @你的机器人用户名 加关键词，就能实时搜索所有命令和技能：

@my_hermes_bot plan          → 点一下 /plan 就发送
@my_hermes_bot plan migrate auth to OIDC   → 直接发送完整命令
@my_hermes_bot pdf           → 按名字或描述搜技能

第一个词用来过滤，后面的词会作为参数带进命令里。点一下结果，命令就以你的身份正常发送了。

一次性设置：内联模式默认是关的，得去 @BotFather 用 /setinline 开启，随便填个占位文字，比如“搜索命令和技能…”。另外，只有通过你网关白名单的用户才能看到搜索结果，陌生人搜到的是空列表，你的技能库不会泄露。

第三步：隐私模式（关键）

这一步很重要，但文档在这里截断了……不过别担心，核心思路就是：默认情况下机器人看不到群聊里的所有消息，只有被 @ 或者使用命令时才响应。想让它“耳听八方”，需要调整隐私设置。具体怎么配，咱们下回分解！

---

好了，把 Hermes 搬进 Telegram 就这么简单。建好机器人、调好设置，你的 AI 助手就随时待命了。快去试试吧！