OpenClaw LaunchOpenClaw Launch
← Hermes Agent 中文介绍

渠道接入

Hermes Agent 接入 Telegram

把 Hermes Agent 接到 Telegram 机器人上。本文讲怎么从 BotFather 拿 token、TELEGRAM_BOT_TOKEN 环境变量怎么填、channels.telegram 字段、dmPolicy 配对登录怎么配，以及最常见的报错怎么修。

准备工作

  • 一个 Telegram 账号
  • 已经在跑的 Hermes Agent（没跑起来先看 安装指南）
  • 不需要公网 HTTPS：Telegram 默认走 getUpdates 长轮询，Hermes 主动拉消息

第一步：从 BotFather 创建机器人

  1. 在 Telegram 里搜 @BotFather，发 /newbot。
  2. 填机器人名字（显示用）和 username（必须以 bot 结尾，比如 my_hermes_bot）。
  3. BotFather 会返回一个 token，形如 1234567890:ABCdefGhI...。这是你的 TELEGRAM_BOT_TOKEN，要保管好，泄露了别人就能控制你的机器人。

第二步：用环境变量启动 Hermes（最快）

Hermes 对 Telegram 提供环境变量快捷方式，启动容器时直接传：

docker run -d \
  -e OPENROUTER_API_KEY="sk-or-v1-..." \
  -e TELEGRAM_BOT_TOKEN="1234567890:ABC..." \
  -p 8642:8642 \
  ghcr.io/nousresearch/hermes-agent:latest

Hermes 启动后会自动启用 Telegram 渠道，无需改 hermes.json。这种方式最快，但只能配一个机器人，且粒度最粗。

第三步：用 hermes.json 精细控制（推荐）

想配置 dmPolicy、限制白名单、或者跑多机器人，就走配置文件。~/.hermes/hermes.json：

{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "${TELEGRAM_BOT_TOKEN}",
      "dmPolicy": "pairing",
      "allowFrom": []
    }
  },
  "plugins": {
    "entries": {
      "telegram": { "enabled": true }
    }
  }
}

两处都要开：channels.telegram 和 plugins.entries.telegram。漏一处插件不会启动。

dmPolicy：千万不要用 open

Telegram 机器人是公开可搜索的。任何人在 Telegram 里搜你的 username 都能找到并发消息。如果 dmPolicy 设成 open，全互联网的人都能用你的机器人烧你的 OpenRouter 余额。

  • dmPolicy: "pairing"（必须）：用户先在 Web 网关上配对，把 Telegram username 跟 Hermes 用户绑定，然后才能私聊机器人。
  • dmPolicy: "closed"：直接拒所有私聊，只回群里被 @ 的消息。
  • dmPolicy: "open"：永远不要用。

配对流程：用户访问 https://你的-hermes-域名/pair，登录后拿到一个 6 位配对码，发给 Telegram 机器人，机器人确认绑定。之后这个 Telegram 账号就能私聊机器人了。

第四步：添加群和私聊

  • 私聊：dmPolicy: "pairing" 配好后，配对过的用户直接 /start 即可
  • 群聊：把机器人拉进群，群里 @ 它就行。注意 BotFather 默认开了 Privacy Mode（机器人只看到 @ 它的消息），如果想让它读所有消息，去 /setprivacy 关掉

测试

# 检查 Telegram API 凭据
curl https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/getMe

# 看 Hermes 日志确认渠道启动
docker logs hermes 2>&1 | grep -i telegram

常见报错

401 Unauthorized — getUpdates

Token 错了。检查 TELEGRAM_BOT_TOKEN 有没有复制完整（带冒号），有没有多余的引号或空格。BotFather 的 token 一旦泄露要立刻 /revoke 重发。

409 Conflict — terminated by other getUpdates request

同一个 token 被两个进程同时长轮询了。一般是你之前启过一个 Hermes 实例还在跑。docker ps | grep hermes 看看，把旧的停掉。

机器人能加群但群里 @ 不回

  • Privacy Mode 开着导致机器人看不到普通消息：BotFather /setprivacy → 选择机器人 → Disable
  • 群里没有 @ 机器人 username，只是发了消息：必须 @ 它才会回（Privacy Mode 开启时）
  • 看 docker logs hermes 确认消息有没有进来

私聊机器人没反应

  • dmPolicy: "pairing" 而你还没配对：先去 /pair 走配对流程
  • plugins.entries.telegram.enabled 没设 true：Hermes 的 Telegram 插件没启动
  • OPENROUTER_API_KEY 没传：机器人收到了但生成不了回复，看日志

多机器人场景

一个 Hermes 实例只能配一个 Telegram 机器人。需要多个机器人就跑多个 Hermes 容器，每个容器绑一个 token。或者用 OpenClaw Launch 托管版，每个订阅就是一个独立实例。

托管版：OpenClaw Launch

上面看着不复杂，但实操要管：长轮询挂掉后自动重连、token 泄露后撤销重发、多机器人怎么部署、怎么看每条消息的延迟。 OpenClaw Launch 直接提供 Hermes Agent 的托管网关，Telegram 渠道一键开通：在 Dashboard 填 BotFather 给的 token，机器人马上就能用。首月 $3，之后 $6/月。

下一步

一键接 Telegram

OpenClaw Launch 托管版直接开 Telegram 渠道，填个 token 就跑。

立即部署