当前位置： 首页 > news >正文

10 分钟把 Hermes 接入 Telegram：Gateway 实战指南

news 2026/4/17 19:10:58

阅读提示：本文基于 Hermes Agent 真实源码（gateway/目录），带你从零开始将本地 Agent 扩展为 7×24 小时在线的 Telegram Bot。预计阅读时间 10 分钟。

一、为什么需要 Gateway？

在上一篇中，我们已经学会了如何在本地用hermes chat与 Agent 对话。但这只是一个"单机版"——一旦你关掉终端，Agent 就下线了。

Hermes Gateway的作用，就是让 Agent 成为一个常驻的异步消息网关。无论你是在地铁上用手机发 Telegram 消息，还是在办公室里用 CLI 深度调试，背后的 Agent 都共享同一套记忆、技能和对话历史。

Gateway vs CLI 对比

特性CLI 模式Gateway 模式
运行方式前台进程后台服务
可用性终端关闭即停止7×24 小时在线
访问方式本地终端多平台（Telegram/Discord/Slack）
并发支持单用户多用户/多会话
适用场景本地开发调试生产环境、移动访问
SQLiteAIAgentBasePlatformAdapterTelegram Bot用户SQLiteAIAgentBasePlatformAdapterTelegram Bot用户发送消息转换为 MessageEventrun_conversation()读取历史 / 写入回复模型回复发送给用户

核心设计：Gateway 不是简单的 Webhook 转发器。它内置了平台锁、会话隔离、流式响应缓冲和静默 Flush 机制，是生产环境的稳定基石。

二、安装前的环境准备

1. 操作系统要求

Hermes Agent 目前支持：

  • Linux（Ubuntu / Debian / CentOS 等）
  • macOS
  • WSL2（Windows 用户请先在 WSL2 里操作，原生 Windows 暂不支持）

2. 需要提前准备的东西

  • 一台能联网的电脑 / 服务器（推荐 VPS 或云主机，保持长期在线）
  • 一个 Telegram 账号
  • 一个 Telegram Bot Token（通过 @BotFather 申请）
  • 一个大模型 API Key（OpenRouter、Anthropic、OpenAI、DeepSeek 等均可）

💡小提示：Hermes 要求模型上下文至少 64K tokens。目前主流模型（Claude 3.5 Sonnet、GPT-4o、DeepSeek-V3 等）都能满足。

三、快速安装 Hermes Agent

如果你已经完成了第 1 篇的安装，可以直接跳到下一章。如果还没有，执行以下命令：

pipinstallhermes-agent

验证安装：

hermes--version

预期输出：

hermes-agent version 0.x.x

看到版本号即表示安装成功。

四、配置大模型提供商

在接入 Telegram 之前，先确保大模型已配置好。运行交互式配置向导：

hermes setup

根据向导提示完成以下配置：

  1. 模型提供商：选择你的 API 提供商（如 OpenRouter、Anthropic），输入 API Key。
  2. 终端后端（Terminal Backend）：初学者选择local，后续如需沙箱隔离可切换为docker。
  3. 最大迭代次数（Max Iterations）：建议设为 50-100。复杂任务可提高到 200。
  4. 上下文压缩阈值（Compression Threshold）：默认 0.75 即可。长对话频繁触发压缩的场景可适当调高。
  5. 重置模式（Reset Mode）：建议选择Never auto-reset，通过/new或/reset手动控制会话边界。

配置完成后，Hermes 会在~/.hermes/目录下生成config.yaml和.env文件。

五、接入 Telegram（核心步骤）

Step 1：获取 Telegram Bot Token

  1. 在 Telegram 中搜索并打开@BotFather。
  2. 发送/newbot，按提示设置 Bot 名称和用户名。
  3. 完成后，BotFather 会发给你一串 Token，格式如：123456789:ABCdefGHIjklMNOpqrSTUvwxyz。
  4. 妥善保存这个 Token，不要泄露给他人。

Step 2：将 Token 写入配置文件

打开~/.hermes/config.yaml，在gateway键下添加 Telegram 配置：

gateway:telegram:enabled:truebot_token:"${TELEGRAM_BOT_TOKEN}"

然后在~/.hermes/.env中添加你的实际 Token：

TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrSTUvwxyz

💡为什么分开存？config.yaml支持${VAR}语法展开。将敏感信息放在.env中，可以避免在分享配置或提交到版本控制时意外泄露密钥。

Step 3：测试 Gateway 启动

在终端中执行：

hermes gateway run

预期输出：

[INFO] Hermes Gateway 启动中... [telegram] 平台锁已获取: ~/.hermes/gateway_telegram.lock [telegram] 连接成功，开始 polling... [telegram] Bot 用户名: @your_bot_name [telegram] 等待消息...

此时打开 Telegram，找到你的 Bot，发送一条消息（如 “你好”）。

预期回复：

你好！我是 Hermes Agent，一个基于大语言模型的智能助手。 我可以帮你： - 回答技术问题 - 执行代码任务 - 管理文件和数据 - 以及更多... 有什么我可以帮你的吗？

如果 Bot 回复了，说明 Gateway 已经跑通了！

六、把 Gateway 设为后台服务（长期运行）

hermes gateway run是前台运行，关掉终端后 Gateway 就会停止。为了让 Agent 7×24 小时在线，你需要把它注册为系统后台服务。

方案 A：使用 hermes 自带的服务管理（推荐）

macOS / Linux 用户：

# 安装为用户级服务（当前用户登录后自动启动）hermes gatewayinstallhermes gateway start# Linux 如需系统级服务（开机自启，无需登录）sudohermes gatewayinstall--systemsudohermes gateway start

预期输出：

✓ Service installed successfully ✓ Service started ✓ Gateway is now running in the background 查看状态: hermes gateway status 查看日志: hermes gateway logs

常用命令：

hermes gateway status# 查看运行状态hermes gateway stop# 停止服务hermes gateway restart# 重启服务hermes gateway logs# 查看实时日志hermes gateway uninstall# 卸载服务

💡底层原理：hermes gateway install会根据你的系统生成对应的 service 文件（Linux 用 systemd，macOS 用 launchd），并调用系统服务管理器注册进程。状态信息写入~/.hermes/gateway_status.json，hermes gateway status就是读取这个文件。

方案 B：使用 tmux（通用、灵活）

如果你不想用系统服务，或者服务器环境受限，可以用 tmux 保持前台进程：

# 安装 tmux（如果还没装）sudoaptupdate&&sudoaptinstalltmux# Ubuntu/Debian# 或brewinstalltmux# macOS# 创建一个 tmux 会话，在里面运行网关tmux new-shermes-d'hermes gateway run'

常用操作：

  • 查看日志：tmux attach -t hermes（按Ctrl+B然后D退出）
  • 停止网关：tmux attach -t hermes，然后按Ctrl+C，输入exit
  • 列出会话：tmux ls
  • 删除会话：tmux kill-session -t hermes

💡tmux vs systemd：tmux 更灵活，适合临时测试；systemd 更稳定，适合生产环境。

七、Telegram 里能做什么？

接入 Telegram 后，Hermes 支持的功能与 CLI 完全一致，因为所有入口最终都收敛到AIAgent.run_conversation()：

功能说明
文字对话支持多轮上下文、记忆恢复、技能调用
文件传输可接收文档、代码文件（通过 Telegram 的文件消息）
消息分片超长回复会自动拆成多条消息，避免被 Telegram 的 4096 字符限制截断
Markdown 支持自动将回复格式化为 Telegram 的 MarkdownV2

Telegram 里的常用指令

在微信/Telegram 聊天窗口里，你可以直接发以下 slash 指令：

指令作用
/new或/reset开启新对话，清空当前上下文
/model查看或切换当前模型
/tools查看当前启用的工具
/compress手动触发上下文压缩
/skills浏览已安装的技能

💡Session-Scoped 模型覆盖：在 Gateway 中发送/model anthropic/claude-opus-4-6，只会影响当前聊天线程，不会影响其他用户或群组。这是通过 GatewayRunner 维护的_session_model_overrides字典实现的。

八、常见问题与排错

1.Another gateway instance is already running for telegram

原因：每个 Telegram Bot Token 只能被一个 Gateway 实例使用。

排查步骤：

# 检查 Gateway 状态hermes gateway status# 查找运行中的进程psaux|grep"hermes gateway"# 停止旧实例hermes gateway stop

解决方案：先停止旧的实例再启动新的。

2. Telegram 连接成功但不回复

排查清单：

# 1. 检查配置文件cat~/.hermes/config.yaml|grep-A3"telegram:"# 确认 enabled: true# 2. 检查 Tokencat~/.hermes/.env|grepTELEGRAM_BOT_TOKEN# 确认 Token 格式正确# 3. 检查日志tail-f~/.hermes/gateway.log

常见原因：

  • gateway.telegram.enabled未设为true
  • .env中的TELEGRAM_BOT_TOKEN格式错误或过期
  • Bot 被 Telegram 封禁或触发 Rate Limit
  • 大模型 API Key 无效或余额不足

3. Gateway 启动后过一段时间断开

原因：Telegram 的 polling 模式可能因网络抖动中断。

解决方案：

# 检查网络连接pingapi.telegram.org# 查看断开日志grep"disconnect\|error"~/.hermes/gateway.log# 使用 systemd 自动重启（Linux）sudosystemctlenablehermes-gatewaysudosystemctl restart hermes-gateway

Hermes 的TelegramAdapter底层基于python-telegram-bot，通常会自动重连。如果频繁断开，建议：

  • 检查服务器网络稳定性
  • 考虑使用 webhook 模式（需要公网 IP 和 HTTPS 证书）

4. 如何在群组中使用 Hermes Bot？

步骤：

  1. 将 Bot 添加到群组
  2. 在 @BotFather 中调整 Bot 的Group Privacy设置

默认行为：

  • Bot 只能读取 @它的消息或回复它的消息

关闭 Group Privacy 后：

  • Bot 可以读取群组中的所有消息

配置方法：

1. 打开 @BotFather 2. 发送 /mybots 3. 选择你的 Bot 4. Bot Settings → Group Privacy → Turn Off

九、Gateway 的进阶机制

1. 平台锁（Platform Lock）

gateway/platforms/base.py中，每个适配器在connect()时会获取一个 OS 级文件锁：

lock_path=get_hermes_home()/f"gateway_{self.platform.value}.lock"fcntl.flock(lock_file.fileno(),fcntl.LOCK_EX|fcntl.LOCK_NB)

这防止了你误操作同时启动两个 Telegram Bot 实例竞争同一个 Token。进程崩溃时，操作系统会自动释放锁。

2. 静默 Flush（Silent Flush）

当用户发送/new或会话超时时，Gateway 会在后台创建一个临时AIAgent实例：

  • 只启用memory和skills工具，禁用terminal、write_file等可能产生副作用的工具
  • _print_fn设为空函数，确保没有任何输出骚扰用户
  • 自动回顾对话并提取关键信息写入~/.hermes/memories/MEMORY.md

3. 流式响应缓冲

LLM 的流式 token 不会一个字一个字发到 Telegram。gateway/stream_consumer.py会将 token 缓冲后按段落或长度阈值分批发送，既保证了"打字机"般的体验，又避免了频繁调用 Telegram API。

十、扩展平台：第三方微信接入方案（非官方）

需要特别说明的是，个人微信并不是 Hermes 官方 Gateway 原生支持的平台。在官方源码中，Gateway 的BasePlatformAdapter目前只内置了 Telegram、Discord、Slack、WhatsApp、Signal、Matrix、Email 等适配器。

不过，得益于 Hermes 开放的MCP 协议和Webhook 适配器，你完全可以通过第三方生态将 Hermes 的能力延伸到微信。以下是社区中常见的两种可行思路：

方案 A：通过第三方 MCP 服务器桥接

市面上已有一些开源的微信 MCP Server 项目（如基于wechaty或itchat封装的第三方服务）。接入思路如下：

  1. 启动一个独立的微信 MCP Server，负责扫码登录个人微信并维护会话；
  2. 在 Hermes 中通过~/.hermes/config.yaml的mcp_servers配置该 Server；
  3. Hermes 的ToolRegistry会自动将微信的"发送消息"、"接收消息"等能力注册为 MCP 工具；
  4. 你可以通过send_message等 MCP 工具让 Hermes 主动向微信推送消息，或让微信消息触发 Hermes 的run_conversation()。

⚠️注意：这种方式下，微信消息的生命周期由 MCP Server 管理，Hermes 把它视为一个外部工具调用，而非原生 Gateway 平台适配器。因此你无法直接使用 Gateway 的平台锁、静默 Flush 等机制。

方案 B：自建 Webhook 桥接服务（详细步骤）

如果你希望微信消息也能享受 Gateway 的会话管理和记忆能力，可以自建一个轻量的桥接服务。以下是一套基于wechaty（Node.js 微信机器人库）的完整落地步骤。

⚠️重要风险声明：个人微信对接机器人存在封号风险，且受微信协议更新影响较大。以下方案仅供技术研究和学习交流，请勿用于生产环境或高频账号。

Hermes Gateway

第三方桥接

微信侧

消息

HTTP POST

MessageEvent

HTTP 回调

回复

个人微信

wechaty 服务

gateway/platforms/webhook.py

AIAgent

Step 1：环境准备

你需要一台能长期联网的服务器（或本地电脑），并安装 Node.js（建议 v18+）：

# 验证 Node.js 版本node-v# 应 >= 18.0.0npm-v
Step 2：创建 wechaty 桥接服务

新建一个目录并初始化项目：

mkdirhermes-wechaty-bridge&&cdhermes-wechaty-bridgenpminit-ynpminstallwechaty axios express

创建bridge.js：

const{WechatyBuilder}=require('wechaty');constaxios=require('axios');// Hermes Webhook 平台适配器地址constHERMES_WEBHOOK_URL='http://localhost:8080/webhook';constbot=WechatyBuilder.build({name:'hermes-bridge',puppet:'wechaty-puppet-wechat4u',// 纯协议实现，无需浏览器});bot.on('scan',(qrcode,status)=>{console.log(`扫码登录:${status}`);console.log(`二维码链接: https://wechaty.js.org/qrcode/${encodeURIComponent(qrcode)}`);}).on('login',(user)=>{console.log(`登录成功:${user}`);}).on('message',async(msg)=>{// 过滤自己发的消息，避免循环if(msg.self())return;consttalker=msg.talker();constroom=msg.room();consttext=msg.text();constchatId=room?awaitroom.topic():talker.id;constuserId=talker.id;constpayload={platform:'webhook',chat_id:chatId,user_id:userId,message_text:text,thread_id:room?room.id:null,};try{constresp=awaitaxios.post(HERMES_WEBHOOK_URL,payload,{timeout:120000,headers:{'Content-Type':'application/json'},});constreplyText=resp.data?.reply||resp.data?.message_text||'收到';awaitmsg.say(replyText);}catch(err){console.error('Hermes 调用失败:',err.message);awaitmsg.say('服务暂时不可用，请稍后再试。');}});bot.start().catch(console.error);
Step 3：配置 Hermes 的 Webhook 平台适配器

编辑~/.hermes/config.yaml，启用 webhook 平台：

gateway:webhook:enabled:trueport:8080path:/webhookhost:0.0.0.0

由于gateway/platforms/webhook.py不是官方适配器，你需要手动实现或基于社区版本部署。其最简逻辑是：

  1. 启动一个 HTTP 服务器监听8080端口；
  2. 收到 POST 请求后，将 JSON body 转换为MessageEvent；
  3. 调用AIAgent.run_conversation()获取回复；
  4. 将回复以 JSON 格式返回给桥接服务。

💡桥接核心原则：桥接服务只负责微信协议通信，业务逻辑完全交给 Hermes。这样可以最大化复用 Hermes 的会话隔离、SQLite 持久化、上下文压缩等能力。

Step 4：启动服务

终端 1：启动 wechaty 桥接服务

cdhermes-wechaty-bridgenodebridge.js

首次运行会输出二维码链接，用手机微信扫码登录。

终端 2：启动 Hermes Gateway

hermes gateway run

注意：如果webhook平台未在官方源码中提供完整实现，你可能需要自行扩展gateway/platforms/webhook.py，或直接在本地运行一个独立的 HTTP 转发脚本作为替代。

Step 5：验证消息通路

在微信里给你的桥接账号发一条消息。如果配置正确，消息会通过以下链路：

个人微信 → wechaty bridge → HTTP POST → Hermes Webhook → AIAgent → 微信回复
常见排错
现象原因解决
wechaty 扫码后无法登录微信协议更新或账号风控尝试换wechaty-puppet-wechat或换号测试
Hermes 无响应Webhook 端口未监听或路由不通检查localhost:8080/webhook是否可达
回复延迟 > 30 秒LLM API 调用超时调大axios的timeout参数
消息循环（自己回复自己）未过滤msg.self()确认bridge.js中已添加该过滤

方案 C：通过 Home Assistant 转发

Hermes 官方 Gateway 已经支持Home Assistant适配器。如果你的智能家居环境里已经部署了 Home Assistant，可以借助 HA 的自动化脚本或第三方微信插件，将微信消息转发到 Hermes 的 HA 适配器中。这种方式不需要写代码，但灵活度最低。

三种方案对比

维度方案 A：MCP 桥接方案 B：Webhook 桥接方案 C：HA 转发
技术难度中中高低
是否能用 Gateway 能力❌ 不能✅ 能⚠️ 部分能
是否需要写代码少量配置需要写桥接服务不需要
封号风险高高中
稳定性依赖第三方 MCP Server依赖 wechaty 协议依赖 HA 生态
推荐人群快速验证有 Node.js 基础、追求完整能力已有 HA 环境

总结：如果你追求开箱即用、官方维护，首选Telegram或Discord；如果你确实需要对接个人微信，请做好心理准备——目前不存在 Hermes 官方的一键接入方案，你需要借助第三方 MCP Server 或自建 Webhook 桥接来完成。

十一、写在最后

把 Hermes 接入 Telegram，相当于在云端放了一个 24 小时在线的数字分身。无论你是在地铁上用手机查资料，还是在床上发一条指令让它帮你跑批处理任务，它都能随时响应。

整个过程并不复杂：

  1. pip install hermes-agent完成安装；
  2. hermes setup配好大模型；
  3. 在config.yaml+.env中填入 Telegram Bot Token；
  4. hermes gateway install && hermes gateway start启动服务。

当你在 Telegram 里收到第一条来自 Hermes 的回复时，你就已经完成了从"单机工具"到"常驻 Agent"的关键一跃。

Happy Hacking！

http://www.jsqmd.com/news/656878/

相关文章：

  • Android Camera2录像实战：从MediaRecorder配置到视频保存到相册的完整避坑指南
  • DEDECMS与帝国CMS深度对比
  • 从Fluent残差图看网格质量：如何解读震荡、发散背后的网格‘凶手’
  • Llama Factory新手指南：如何选择模型、准备数据并训练你的第一个AI
  • FastAdmin后台配置分组实战：从添加分组到前端调用的完整流程（附代码）
  • 深度拆解RK3588显示子系统：从uboot报错到内核logo加载失败的全链路分析
  • rk3568 Android 11.0 从F2FS迁移到EXT4：优化数据擦除与掉电保护
  • Windows系统优化的终极神器：WinUtil完全指南
  • 想学斯坦福CS231A计算机视觉？先看看这份保姆级的Python与数学基础自查清单
  • MATLAB Simulink搭建电动汽车整车七自由度模型及模糊控制算法与轮胎模型研究
  • 3个核心功能揭秘：如何用AI智能移除图像中的任何对象
  • 为什么你需要永久保存微信聊天记录：数字记忆的终极守护方案
  • 实战演练：从双线程到三线程的并行累加重构
  • 长芯微LPS6288完全P2P替代TPS61288,是一款具有 15A 开关电流的全集成同步升压转换器
  • 别再傻傻用mutex了！C++11 std::atomic原子变量实战，性能提升看得见
  • 从电流采样到SVPWM：手把手解析PMSM有感FOC的闭环实现
  • Beego ORM避坑指南：从数据库设计到高效查询
  • 2026年主流安卓加固平台效果与价格横评：谁才是性价比之王？
  • 从原理到实践：MATLAB仿真线性调频信号的脉冲压缩全流程
  • 大模型在天文科研中的应用：天体数据分析
  • Edge浏览器一启动就自动打开2345？别急着重装系统，试试这个权限修改法
  • Vivado Tcl脚本自动化：如何一键解决DRC NSTD-1等常见I/O标准警告
  • Android基于WallpaperService打造实时摄像头动态壁纸
  • 手把手教你从OpenSSL开始，在CentOS/Ubuntu上编译一套支持HTTPS的Git（避坑libcurl链接错误）
  • XAMPP环境下Pikachu靶场搭建与常见端口冲突解决方案
  • 用 xv6 的 Lab1 理解 Unix 管道与进程：手把手教你实现 pingpong 和 primes 筛子
  • DL-2007数字水准仪：从外业数据采集到内业精度验证全流程解析
  • 半导体工程师必看：Calibre DESIGNrev 命令行模式全解析，告别GUI提升效率
  • 一站式免费Switch模拟方案：用Ryujinx在PC上畅玩任天堂游戏
  • 2026年4月北京校园餐智慧监管平台/膳食营养/食安监管/智慧厨房/餐饮智能品牌公司五强深度测评与选型指南 - 2026年企业推荐榜