📖 前言
为了摆脱第三方网页端 AI 对话工具的会话配额限制和繁琐登录，并获得一个随时随地在手机端通过即时通讯软件即开即用的私人助手，决定利用手头的 Linux VPS 结合 Hermes Agent 框架，部署一个属于自己的 Telegram AI Bot。
实际搭建过程中踩了不少坑：第三方中转站的突发欠费冻结（HTTP 401）、官方接口模型更迭导致的弃用报错（HTTP 404），以及长消息在 Telegram 网关引起的流式截断与挂起（Mid-stream drop）。
本篇复盘从环境准备、接口配置到三大核心故障排查的完整流程。
最终效果：
- 📱 随时随地响应：手机 Telegram 客户端随时呼出专属 Bot。
- ⚡ 原生疾速体验：直连 Google Gemini 3.6 Flash 模型，无中转损耗与欠费停机风险。
- 🛡️ 隔离与常驻：基于用户 ID 白名单进行安全隔离，结合
tmux实现 7×24 小时后台稳定运行。
一、前期准备
1. 环境与依赖
- VPS 实例：一台能够顺畅访问外网的 Linux 服务器（Debian / Ubuntu 系列均可），Python 3.10+。
- Agent 框架：Hermes Agent。
- 核心模型：Google Gemini 官方 API（建议直接使用 Google AI Studio 申请的官方 Key，稳定性远优于第三方中转）。
2. 获取必要凭证
| 凭证名称 | 获取途径 | 作用说明 |
|---|---|---|
| Telegram Bot Token | 手机端搜索 @BotFather | 发送 /newbot，按引导创建 Bot 后获取专属 HTTP API Token |
| Telegram User ID | 手机端搜索 @userinfobot | 纯数字 ID，用于在网关中配置访问白名单，防止被他人滥用 |
| Google Gemini API Key | Google AI Studio | 点击 Get API key 获取，直连官方原厂接口 |
二、基础环境部署与运行
1. 创建 tmux 会话保持进程常驻
在开始之前，建议先创建独立的后台虚拟终端，避免 SSH 断开后导致服务被系统终止：
tmux new -s hermes
2. 克隆项目与配置虚拟环境
在服务器当前用户主目录下拉取仓库并安装依赖：
git clone https://github.com/nousresearch/hermes-agent.git ~/hermes-agent
cd ~/hermes-agent
# 创建并激活 Python 虚拟环境
python3 -m venv venv
source venv/bin/activate
# 安装项目依赖
pip install -r requirements.txt
三、踩坑复盘与核心排障
这是整个部署流程中最容易卡住的环节，以下按照排查顺序梳理并记录解决办法。
🚨 坑 1：第三方中转站鉴权失败（HTTP 401）
最初尝试使用 OpenAI API 兼容协议接入第三方中转站，控制台突然报出致命错误，提示 AuthenticationError [HTTP 401]，账户被判定为未激活状态。
- 问题原因：第三方中转站的账号触发了欠费机制、单 Token 额度用尽，或是该通道被中转平台暂时冻结。
- 解决方案：放弃不稳定且额度不可控的第三方中转平台，全面换用 Google Gemini 原生 API。
重新运行初始化命令：
./hermes setup
在选项中选择 Full setup – configure every provider, tool & option yourself (bring your own keys)，Provider 选择 Google Gemini，Base URL 保持默认（直接敲回车），并填入官方申请的 API Key。
🚨 坑 2：旧版模型停用报错（HTTP 404）
配置官方 API 后，若习惯性选择了旧款模型（如 gemini-2.5-flash），控制台会连续重试并报错，提示该模型已不再向新用户开放，需迁移到最新模型。
- 问题原因：Google 官方更新了 API 策略，旧版模型已禁止新用户接入，官方强制要求迁移至最新版模型。
- 避坑提示：Hermes Agent 的模型激活状态保存在本地数据库（
/root/.hermes/state.db）中，直接用纯文本sed替换环境变量通常无效。 - 解决方案：使用 Hermes 内置的模型管理命令快速切换：
./hermes model
在弹出的列表中选中 gemini-3.6-flash 并回车确认即可。
🚨 坑 3：长回答挂起与流式截断（Mid-stream drop）
测试简单问候时正常，但当输入代码或复杂问题时，控制台会卡在"流式结束但无 finish_reason"的中间状态，手机 Telegram 迟迟收不到回复。
- 问题原因：复杂问题生成的文本量较大，Telegram API 存在单条 4096 字符的限制；且在网络轻微抖动时，流式（Streaming）推送容易因超时被截断，导致消息处于未交付状态。
- 解决方案：为 Telegram 网关关闭实验性流式输出，改由 Agent 生成完整内容后一次性投递。
运行以下命令关闭流式：
./hermes config set gateway.telegram.stream false
检查 /root/.hermes/config.yaml 确认写入成功：
model:
default: gemini-3.6-flash
provider: gemini
base_url: https://generativelanguage.googleapis.com/v1beta
gateway:
telegram:
stream: false
四、启动网关与联调测试
完成上述配置调整后，启动 Telegram 网关服务：
./hermes gateway
打开手机 Telegram 客户端，找到你的 Bot，进行两轮测试：
- 单字测试：发送
hi，观察 Bot 是否在 1~2 秒内秒回。 - 长文本与代码测试：发送"帮我写一个 Python 的 hello world 并解释"。
手机端将顺利收到带有代码块排版的高亮文本，且控制台顺利完成会话生命周期，未再出现挂死现象。
五、后台常驻与日常运维
1. 脱离终端会话（保持 24 小时在线）
确认消息收发无误后，无需配置复杂的 systemd，直接从 tmux 中优雅脱离：
- 按下键盘快捷键组合：
Ctrl + B - 松开手后，紧接着按下：
D
终端将输出 [detached (from session hermes)]。此时可以安全关闭本地电脑或 SSH 终端，VPS 会在后台保持运行。
2. 常用管理速查
重新进入控制台查看实时日志：
tmux attach -t hermes
强制中断卡顿任务：在 attach 后的界面按下 Ctrl + C。
快速检查当前配置文件：
cat /root/.hermes/config.yaml
💡 总结
自建 Telegram AI Agent 的核心在于稳定的模型调用通道与平台消息投递协议的对齐：
- 避免过度依赖第三方中转：直连官方原生 API 可以杜绝 401 欠费风险，还能享受充足的原厂调用配额与上下文深度。
- 及时同步主流模型版本：避免因调用已下线的旧版模型 ID 而触发 404。
- 关闭不成熟的即时流式切片：在即时通信网关场景下，整包投递策略的抗网络抖动能力与兼容性远高于分块流式传输。