Hermes Agent 接入 Telegram：把服务器里的 AI Agent 变成手机上的远程助手

这是「AI Agent 上手系列」第 3 篇。前两篇我们已经把 Hermes Agent 跑起来，并且接好了模型 API。这一篇做一个很实用的升级：把 Hermes 接到 Telegram，让你不用 SSH、不用打开电脑，只要在手机里发一句话，就能让服务器上的 AI Agent 帮你查日志、跑脚本、读文件、总结任务。

摘要

很多人第一次把 AI Agent 部署到服务器后，会遇到一个小问题：

Agent 已经在服务器上了，但我每次都要 SSH 上去跟它说话。

这就有点浪费了。AI Agent 真正好用的场景，往往不是你端坐电脑前“严肃办公”，而是：

出门在外，手机上问一句“服务挂了吗？”
群里有人反馈 bug，顺手让 Agent 查一下日志
晚上躺床上，让 Agent 把今天的运行状态总结一下
让 Agent 生成一个文件、图片、报告，然后直接发回聊天窗口

Hermes Agent 的 Messaging Gateway 就是干这个的。它可以把同一个 Hermes 接到 Telegram、Discord、Slack、WhatsApp、Weixin 等平台。Telegram 是其中最适合新手上手的一个：BotFather 创建机器人很快，消息、文件、图片、语音支持也比较完整。

本文会从 0 到 1 讲清楚：

如何用 BotFather 创建 Telegram Bot
如何把 Bot Token 写进 Hermes
如何设置允许访问的用户，避免机器人被陌生人调用
如何启动 Hermes Gateway
如何在私聊和群聊里使用
常见坑：隐私模式、群聊 @、文件路径、token 消耗

如果你前两篇已经按教程把模型 API 接到 Nbility，那么这篇做完之后，你就会拥有一个“手机远程 AI Agent”。

为什么 Telegram 很适合做 Agent 入口？

传统服务器运维入口通常是 SSH：

手机/电脑 -> SSH -> 服务器 -> 手动执行命令

接入 Telegram 后，入口会变成：

你在 Telegram 发消息，Gateway 收到之后把任务交给 Hermes Agent，Hermes 再按配置调用模型、工具和终端能力。最后结果回到 Telegram。

这带来几个很直接的好处：

移动端友好：不用随时带电脑。
天然通知系统：长任务完成、定时任务结果、监控提醒都能推到手机。
文件和图片好传：Agent 生成的 Markdown、ZIP、图片可以直接作为 Telegram 附件发回来。
群聊协作方便：小团队可以在群里 @机器人，让它查状态、总结讨论、生成报告。
低心智负担：相比搭网页面板，Telegram Bot 更快落地。

当然，方便也意味着要更注意安全。你是在把“能操作服务器的 Agent”接到聊天软件上，所以白名单、群聊触发规则和危险命令审批一定要配置好。

准备工作

你需要：

一台已经安装 Hermes Agent 的服务器或电脑
Hermes 已经可以正常调用模型
一个 Telegram 账号
可以访问 @BotFather
你的 Telegram 数字用户 ID

如果你还没有模型 API，可以先准备一个 OpenAI 兼容入口。比如用 Nbility：

Base URL: https://api.nbility.dev/v1
API Key: sk-[REDACTED]

Nbility 地址：

https://nbility.dev

这里不是为了强行让你充值，而是 Agent 接 Telegram 之后使用频率会明显提高：你会更频繁地让它查东西、跑命令、总结上下文。一个稳定的 token/API 入口，会比临时到处切模型省心很多。

第一步：用 BotFather 创建 Telegram Bot

打开 Telegram，搜索：

@BotFather

发送：

/newbot

它会问你两个问题：

Bot 显示名称，比如：My Hermes Agent
Bot 用户名，必须以 bot 结尾，比如：my_hermes_agent_bot

创建成功后，BotFather 会返回一个 Token，格式类似：

123456789:ABCdefGHIjklMNOpqrSTUvwxYZ

这个 Token 非常重要。谁拿到它，谁就能控制你的机器人。

所以请记住三条规则：

不要发到群里
不要写进文章截图
不要提交到 GitHub

如果泄露了，到 BotFather 里用：

/revoke

重新生成。

第二步：拿到自己的 Telegram 用户 ID

Hermes 的访问控制用的是数字 ID，不是用户名。

你可以用下面任意一个机器人查询：

@userinfobot
@get_id_bot

它会返回类似：

Id: 123456789

后面我们会把这个 ID 填到：

TELEGRAM_ALLOWED_USERS=123456789

这样只有你自己能调用这个 Hermes Bot。

第三步：用 Hermes Gateway 向导配置 Telegram

最简单的方式是直接运行：

hermes gateway setup

在交互式向导里选择 Telegram，然后填入：

Bot Token
允许访问的 Telegram 用户 ID
是否设置 home channel

如果你喜欢手动配置，也可以编辑：

hermes config env-path

通常是：

~/.hermes/.env

加入：

TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrSTUvwxYZ
TELEGRAM_ALLOWED_USERS=123456789

注意：这里的 Token 和用户 ID 都是示例。真实 Token 不要写进教程、截图或公开仓库。

配置完成后，检查一下：

hermes config check
hermes doctor

如果你已经接入了 Nbility 或其他 OpenAI 兼容模型，也可以顺便确认模型配置没问题：

hermes model

第四步：启动 Hermes Gateway

开发测试时，可以前台运行：

hermes gateway

看到类似日志就说明 Gateway 已经启动：

Starting Hermes Messaging Gateway...
Telegram adapter started

然后打开你刚创建的 Telegram Bot，发送：

你好，介绍一下你现在能做什么？

如果配置正确，它会像普通聊天机器人一样回复你。但区别在于：它背后不是一个只能聊天的 bot，而是一个有工具能力的 Hermes Agent。

你可以试一些轻量任务：

帮我看一下当前系统时间

帮我列出当前工作目录下有哪些文件

搜索一下 Hermes Agent 的 Telegram gateway 文档，总结配置步骤

这类请求会触发模型推理和工具调用，也会消耗 token。任务越复杂、日志越长、文件越多，token 消耗越明显。

第五步：让 Gateway 常驻后台

前台运行适合测试，但长期使用建议安装成服务：

hermes gateway install
hermes gateway start
hermes gateway status

如果你是在服务器上用 root 或 systemd 管理，也可以根据实际环境使用系统服务。关键是保证：

服务器重启后 Gateway 能自动起来
.env 里的 Bot Token 和 API Key 能被服务读取
日志能找到，出问题方便排查

常用检查命令：

hermes gateway status

journalctl --user -u hermes-gateway -n 100 --no-pager

如果是系统级服务，可能需要：

journalctl -u hermes-gateway -n 100 --no-pager

也可以直接看 Hermes 日志目录：

~/.hermes/logs/

第六步：群聊里怎么用？

私聊跑通后，很多人会想把机器人拉进群里。群聊确实很适合 AI Agent，例如：

群里有人说“网站打不开了”，@机器人查状态
项目群里让机器人总结今天讨论
运维群里让机器人截图状态页
内容群里让机器人生成 Markdown 草稿

但群聊比私聊更容易出问题，因为 Telegram 有隐私模式和触发规则。

1. BotFather 隐私模式

Telegram Bot 默认开启 privacy mode。开启时，机器人通常只能看到：

以 / 开头的命令
@机器人的消息
回复机器人的消息

如果你希望机器人“观察群聊上下文”，需要去 BotFather 关闭隐私模式：

/mybots

选择你的 bot，然后找到 privacy mode 设置。

重要提醒：

修改隐私模式后，通常需要把机器人从群里移除再重新邀请一次，Telegram 才会刷新权限。

如果你不想关闭隐私模式，也可以只让群成员通过 @机器人来触发，这样更安全。

2. Hermes 的群聊触发建议

新手建议使用“只在 @ 时回复”的模式，避免群里每句话都触发 Agent。

可以在 Hermes 配置里设置类似：

telegram:
  allowed_chats:
    - "-1001234567890"
  group_allowed_chats:
    - "-1001234567890"
  require_mention: true
  observe_unmentioned_group_messages: true

对应环境变量可以写成：

TELEGRAM_ALLOWED_CHATS=-1001234567890
TELEGRAM_GROUP_ALLOWED_CHATS=-1001234567890
TELEGRAM_REQUIRE_MENTION=true
TELEGRAM_OBSERVE_UNMENTIONED_GROUP_MESSAGES=true

这套配置的意思是：

只允许指定群使用
普通群消息可以进入上下文
但只有 @机器人、回复机器人或命中唤醒词时，才真正派发给 Agent

如果你的群很活跃，建议不要一开始就让它自由回复。否则一个热闹群聊可能会让 Agent 频繁触发，token 消耗和打扰感都会上来。

3. 如何拿到群 ID？

群 ID 通常是负数，超级群常见格式类似：

-1001234567890

可以通过机器人收到消息后的日志、/status、或者临时设置 home channel 来确认。群里也可以先发送：

/sethome

让当前聊天成为默认通知目标。

第七步：在 Telegram 里可以怎么用？

下面是一些适合新手的真实用法。

1. 查服务器状态

帮我检查一下当前服务器 CPU、内存、磁盘和运行中的关键服务，给我一个简短结论。

Agent 会调用系统命令，然后把结果整理成能读懂的摘要。

2. 查日志

帮我看一下最近 100 行 gateway 日志，有没有 Telegram 或 API 报错。

这比你在手机上 SSH、复制粘贴日志舒服很多。

3. 生成文件并发回来

帮我写一份今天服务器巡检报告，保存成 Markdown，并发给我。

Hermes 在 Telegram 里支持 MEDIA:/path/to/file 附件发送。注意文件路径必须对 Gateway 所在主机可读。

常见错误是：Agent 在 Docker 容器里生成了：

/workspace/report.md

但 Gateway 在宿主机上读不到这个路径。更稳妥的做法是把输出放到宿主机可访问目录，例如：

~/.hermes/cache/documents/report.md

然后发送：

MEDIA:/root/.hermes/cache/documents/report.md

4. 让 Agent 定时推送

Telegram 接好之后，Hermes 的 cron 任务会变得非常有用。例如：

每天早上 9 点总结一下服务器状态和昨天的关键日志，发到 Telegram。

以后你不用主动问，它会按计划推给你。

Token 消耗会变大吗？

会，而且这是正常现象。

接入 Telegram 后，你和 Agent 的交互频率会提高。以前你可能一天只在终端里问两句；接到手机后，看到任何问题都会顺手发给它。

另外，Telegram 场景经常伴随：

更长的上下文
群聊历史
日志摘要
文件读取
网页搜索
定时任务
图片和文档处理

这些都会带来更多 token 消耗。

所以我的建议是：

日常轻量问答用便宜模型
代码修改、日志分析、长上下文任务用强模型
群聊里默认 require mention
大日志先让 Agent 摘要，不要整段塞给模型
给常用任务写成 skill，减少每次重复解释背景

如果你用 Nbility，可以把它当成统一 token 入口：同一个 API Key 管理多种模型，Hermes 端只需要保持 OpenAI 兼容配置。后面你再接 Dify、Open WebUI、NextChat、OpenClaw，也能沿用同一套思路。

常见问题排查

1. Bot 私聊没回复

检查：

hermes gateway status

hermes config check

grep -i "telegram\|error\|failed" ~/.hermes/logs/gateway.log | tail -50

常见原因：

TELEGRAM_BOT_TOKEN 写错
Gateway 没启动
服务没加载最新 .env
模型 API Key 不可用
发送者不在 TELEGRAM_ALLOWED_USERS

2. 群里 @了也没反应

检查：

bot 是否在群里
是否被 Telegram 隐私模式限制
是否改完 privacy mode 后重新邀请了 bot
群 ID 是否填进 TELEGRAM_ALLOWED_CHATS
用户 ID 是否在 TELEGRAM_ALLOWED_USERS 或 TELEGRAM_GROUP_ALLOWED_USERS
是否设置了 TELEGRAM_REQUIRE_MENTION=true

3. 群里每句话它都回复，太吵

设置：

TELEGRAM_REQUIRE_MENTION=true

并限制群：

TELEGRAM_ALLOWED_CHATS=-1001234567890

必要时只保留私聊，不把它放群里。

4. 文件发不出来

确认文件路径对 Gateway 进程可读：

test -r /path/to/file && echo OK

如果 Gateway 跑在宿主机，文件却生成在容器里，需要挂载共享目录或把文件复制到宿主机路径。

5. API 费用突然上升

先看是不是这些原因：

群聊自由回复导致频繁触发
日志太长
定时任务太密
让 Agent 反复读取大文件
选了过强/过贵模型做轻任务

优化方式：

require mention
限制 allowed chats
把巡检频率从每 5 分钟改成每天/每小时
长日志先 grep，再让模型总结
日常任务换成便宜模型

一句话总结

前两篇我们做的是“让 Hermes Agent 在服务器上跑起来，并接好模型 API”。

这一篇做完后，它就不再只是一个终端里的工具，而是一个可以随时从手机唤起的远程助手：

Telegram -> Hermes Gateway -> Hermes Agent -> 模型 + 工具 + 服务器

如果你准备认真玩 AI Agent，Telegram 入口非常值得先接。它会让 Agent 从“偶尔打开用一下的软件”，变成“随时可以派活的助手”。

模型 API 和 token 入口方面，可以继续沿用前一篇的 OpenAI 兼容配置。如果你想省事，也可以直接用：

https://nbility.dev

一个 API Key 接 Hermes，后面再接 OpenClaw、Dify、NextChat、LobeChat，也都是同一套思路。

下一篇我准备继续写：

Hermes Agent 接 QQ 群：自动答疑、总结群聊、状态页截图

这个场景会更适合中文社区、项目群和产品客服群。

本文配图提示词

封面图

A polished tech blog cover illustration. niku, Nbility mascot, cute anime catgirl, long fluffy black hair with warm brown highlights, black cat ears with pink inner ears and white fur, fluffy black cat tail with orange bow, oversized black hoodie with orange drawstrings and orange lightning logo, black choker with golden bell, black and orange brand color palette. She is holding a smartphone showing a Telegram chat with an AI agent, while a glowing server rack and terminal window run in the background. Include visual elements of message bubbles, secure token icons, API lines, and remote control workflow. Dark futuristic dashboard, orange accents, clean empty space for Chinese title, no readable secrets, no real API keys, high quality anime tech illustration.

正文图：手机远程控制 Agent

A clean anime-tech illustration showing a smartphone Telegram chat controlling a remote AI agent on a server. Include niku as a small assistant mascot, server rack, command terminal, glowing API connection lines, message bubbles, checklist panels, black and orange Nbility palette. No real tokens, use [REDACTED] for any key-like text, polished technical blog illustration.