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

阅读提示本文基于 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 目前支持LinuxUbuntu / Debian / CentOS 等macOSWSL2Windows 用户请先在 WSL2 里操作原生 Windows 暂不支持2. 需要提前准备的东西一台能联网的电脑 / 服务器推荐 VPS 或云主机保持长期在线一个 Telegram 账号一个 Telegram Bot Token通过 BotFather 申请一个大模型 API KeyOpenRouter、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根据向导提示完成以下配置模型提供商选择你的 API 提供商如 OpenRouter、Anthropic输入 API Key。终端后端Terminal Backend初学者选择local后续如需沙箱隔离可切换为docker。最大迭代次数Max Iterations建议设为 50-100。复杂任务可提高到 200。上下文压缩阈值Compression Threshold默认 0.75 即可。长对话频繁触发压缩的场景可适当调高。重置模式Reset Mode建议选择Never auto-reset通过/new或/reset手动控制会话边界。配置完成后Hermes 会在~/.hermes/目录下生成config.yaml和.env文件。五、接入 Telegram核心步骤Step 1获取 Telegram Bot Token在 Telegram 中搜索并打开BotFather。发送/newbot按提示设置 Bot 名称和用户名。完成后BotFather 会发给你一串 Token格式如123456789:ABCdefGHIjklMNOpqrSTUvwxyz。妥善保存这个 Token不要泄露给他人。Step 2将 Token 写入配置文件打开~/.hermes/config.yaml在gateway键下添加 Telegram 配置gateway:telegram:enabled:truebot_token:${TELEGRAM_BOT_TOKEN}然后在~/.hermes/.env中添加你的实际 TokenTELEGRAM_BOT_TOKEN123456789: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 用 systemdmacOS 用 launchd并调用系统服务管理器注册进程。状态信息写入~/.hermes/gateway_status.jsonhermes gateway status就是读取这个文件。方案 B使用 tmux通用、灵活如果你不想用系统服务或者服务器环境受限可以用 tmux 保持前台进程# 安装 tmux如果还没装sudoaptupdatesudoaptinstalltmux# Ubuntu/Debian# 或brewinstalltmux# macOS# 创建一个 tmux 会话在里面运行网关tmux new-shermes-dhermes gateway run常用操作查看日志tmux attach -t hermes按CtrlB然后D退出停止网关tmux attach -t hermes然后按CtrlC输入exit列出会话tmux ls删除会话tmux kill-session -t hermestmux vs systemdtmux 更灵活适合临时测试systemd 更稳定适合生产环境。七、Telegram 里能做什么接入 Telegram 后Hermes 支持的功能与 CLI 完全一致因为所有入口最终都收敛到AIAgent.run_conversation()功能说明文字对话支持多轮上下文、记忆恢复、技能调用文件传输可接收文档、代码文件通过 Telegram 的文件消息消息分片超长回复会自动拆成多条消息避免被 Telegram 的 4096 字符限制截断Markdown 支持自动将回复格式化为 Telegram 的 MarkdownV2Telegram 里的常用指令在微信/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|grephermes gateway# 停止旧实例hermes gateway stop解决方案先停止旧的实例再启动新的。2. Telegram 连接成功但不回复排查清单# 1. 检查配置文件cat~/.hermes/config.yaml|grep-A3telegram:# 确认 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# 查看断开日志grepdisconnect\|error~/.hermes/gateway.log# 使用 systemd 自动重启Linuxsudosystemctlenablehermes-gatewaysudosystemctl restart hermes-gatewayHermes 的TelegramAdapter底层基于python-telegram-bot通常会自动重连。如果频繁断开建议检查服务器网络稳定性考虑使用 webhook 模式需要公网 IP 和 HTTPS 证书4. 如何在群组中使用 Hermes Bot步骤将 Bot 添加到群组在 BotFather 中调整 Bot 的Group Privacy设置默认行为Bot 只能读取 它的消息或回复它的消息关闭 Group Privacy 后Bot 可以读取群组中的所有消息配置方法1. 打开 BotFather 2. 发送 /mybots 3. 选择你的 Bot 4. Bot Settings → Group Privacy → Turn Off九、Gateway 的进阶机制1. 平台锁Platform Lockgateway/platforms/base.py中每个适配器在connect()时会获取一个 OS 级文件锁lock_pathget_hermes_home()/fgateway_{self.platform.value}.lockfcntl.flock(lock_file.fileno(),fcntl.LOCK_EX|fcntl.LOCK_NB)这防止了你误操作同时启动两个 Telegram Bot 实例竞争同一个 Token。进程崩溃时操作系统会自动释放锁。2. 静默 FlushSilent Flush当用户发送/new或会话超时时Gateway 会在后台创建一个临时AIAgent实例只启用memory和skills工具禁用terminal、write_file等可能产生副作用的工具_print_fn设为空函数确保没有任何输出骚扰用户自动回顾对话并提取关键信息写入~/.hermes/memories/MEMORY.md3. 流式响应缓冲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封装的第三方服务。接入思路如下启动一个独立的微信 MCP Server负责扫码登录个人微信并维护会话在 Hermes 中通过~/.hermes/config.yaml的mcp_servers配置该 ServerHermes 的ToolRegistry会自动将微信的发送消息、接收消息等能力注册为 MCP 工具你可以通过send_message等 MCP 工具让 Hermes 主动向微信推送消息或让微信消息触发 Hermes 的run_conversation()。⚠️注意这种方式下微信消息的生命周期由 MCP Server 管理Hermes 把它视为一个外部工具调用而非原生 Gateway 平台适配器。因此你无法直接使用 Gateway 的平台锁、静默 Flush 等机制。方案 B自建 Webhook 桥接服务详细步骤如果你希望微信消息也能享受 Gateway 的会话管理和记忆能力可以自建一个轻量的桥接服务。以下是一套基于wechatyNode.js 微信机器人库的完整落地步骤。⚠️重要风险声明个人微信对接机器人存在封号风险且受微信协议更新影响较大。以下方案仅供技术研究和学习交流请勿用于生产环境或高频账号。Hermes Gateway第三方桥接微信侧消息HTTP POSTMessageEventHTTP 回调回复个人微信wechaty 服务gateway/platforms/webhook.pyAIAgentStep 1环境准备你需要一台能长期联网的服务器或本地电脑并安装 Node.js建议 v18# 验证 Node.js 版本node-v# 应 18.0.0npm-vStep 2创建 wechaty 桥接服务新建一个目录并初始化项目mkdirhermes-wechaty-bridgecdhermes-wechaty-bridgenpminit-ynpminstallwechaty axios express创建bridge.jsconst{WechatyBuilder}require(wechaty);constaxiosrequire(axios);// Hermes Webhook 平台适配器地址constHERMES_WEBHOOK_URLhttp://localhost:8080/webhook;constbotWechatyBuilder.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;consttalkermsg.talker();constroommsg.room();consttextmsg.text();constchatIdroom?awaitroom.topic():talker.id;constuserIdtalker.id;constpayload{platform:webhook,chat_id:chatId,user_id:userId,message_text:text,thread_id:room?room.id:null,};try{constrespawaitaxios.post(HERMES_WEBHOOK_URL,payload,{timeout:120000,headers:{Content-Type:application/json},});constreplyTextresp.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不是官方适配器你需要手动实现或基于社区版本部署。其最简逻辑是启动一个 HTTP 服务器监听8080端口收到 POST 请求后将 JSON body 转换为MessageEvent调用AIAgent.run_conversation()获取回复将回复以 JSON 格式返回给桥接服务。桥接核心原则桥接服务只负责微信协议通信业务逻辑完全交给 Hermes。这样可以最大化复用 Hermes 的会话隔离、SQLite 持久化、上下文压缩等能力。Step 4启动服务终端 1启动 wechaty 桥接服务cdhermes-wechaty-bridgenodebridge.js首次运行会输出二维码链接用手机微信扫码登录。终端 2启动 Hermes Gatewayhermes 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 适配器中。这种方式不需要写代码但灵活度最低。三种方案对比维度方案 AMCP 桥接方案 BWebhook 桥接方案 CHA 转发技术难度中中高低是否能用 Gateway 能力❌ 不能✅ 能⚠️ 部分能是否需要写代码少量配置需要写桥接服务不需要封号风险高高中稳定性依赖第三方 MCP Server依赖 wechaty 协议依赖 HA 生态推荐人群快速验证有 Node.js 基础、追求完整能力已有 HA 环境总结如果你追求开箱即用、官方维护首选Telegram或Discord如果你确实需要对接个人微信请做好心理准备——目前不存在 Hermes 官方的一键接入方案你需要借助第三方 MCP Server 或自建 Webhook 桥接来完成。十一、写在最后把 Hermes 接入 Telegram相当于在云端放了一个 24 小时在线的数字分身。无论你是在地铁上用手机查资料还是在床上发一条指令让它帮你跑批处理任务它都能随时响应。整个过程并不复杂pip install hermes-agent完成安装hermes setup配好大模型在config.yaml.env中填入 Telegram Bot Tokenhermes gateway install hermes gateway start启动服务。当你在 Telegram 里收到第一条来自 Hermes 的回复时你就已经完成了从单机工具到常驻 Agent的关键一跃。Happy Hacking