WhatsApp 上的 Hermes Agent 连不上：修复方法

机器人从不回复,日志一片安静

你把 Hermes Agent 连到 WhatsApp,网关无报错启动,而你写去的那个号码像块石头一样毫无反应。日志里没有任何入站事件,手机上没有任何送达回执,也没有明显的线索指向十个活动部件里到底哪个坏了。WhatsApp 是 Hermes 全栈里最脆弱的通道,几乎每一个静默连接的案例都可以归结为四种原因之一。

其中三种是按设计悄悄失败的,所以配置看起来正确,却什么都不工作。本文逐个走一遍:如何确认是不是你的情况,以及对应的精确修复。从头开始 - 顺序很重要,因为第一个原因就是从 2026 年 5 月起把所有人都坑住的那个。

原因一:WhatsApp Shortcake 把你的二维码库弄坏了

如果你在通过 Baileys、WAHA 或任何其他抓取 WhatsApp Web 的库运行 Hermes Agent,二维码要么扫不动,要么扫完立刻又把机器人踢下线,你就撞上了 Shortcake 关联设备的上线。WhatsApp 现在要求关联设备提供 WebAuthn passkey,而无头服务器根本没有 passkey 可以出示:navigator.credentials.get() 失败,链接被以 428 拒绝。

症状:二维码画出来了,你的手机扫了它,配对要么一直完不成,要么会话在几分钟内死掉。原本能自动重连的旧会话从 2026 年 5 月之后开始返回 Stream Errored (conflict),同样是这个原因。如果四月还能用,某一晚上突然不行,那就是这个原因。

修复有两种形态:

改用官方 Cloud API。 这是被支持的路径,不会因为 Meta 某个星期二突然打断一个抓取库而崩掉,也是本文剩余部分假设的路径。用 WHATSAPP_ACCESS_TOKEN、WHATSAPP_PHONE_NUMBER_ID 和 WHATSAPP_WEBHOOK_VERIFY_TOKEN 配置 Hermes Agent,取代二维码流程。WhatsApp 部署指南会带你走完整的凭据流程。
继续留在 Baileys 如果你别无选择,把当前还能工作的确切上游 commit 钉死(维护者在 issue #2672 追踪 passkey 相关的绕行方案)。要明白 Meta 下一次改动就会再把你打断。对任何你真依赖的东西来说,这都不是正确选择。

本文剩余部分覆盖 Cloud API 路径。

原因二:你的 WABA 没有订阅到你的应用

这是 Cloud API 上最常见的失败,也是最安静的一种。你在 App Dashboard 里设置了 webhook URL,验证的 GET 通过,Meta 在端点旁边打了绿钩,而消息事件永远不到达。

发生了什么:在应用上设置 webhook URL 只完成了一半的接线。每个 WhatsApp Business Account(WABA)还必须单独订阅到那个应用,它的消息才会被路由到你的端点。App Dashboard 里根本看不到这个订阅关系,而 webhook 界面也会让你在没挂 WABA 的情况下顺利完成设置。Meta 把这种情况叫做 shadow delivery 问题,而修复方法就是一次设置向导从不提及的 API 调用。

先检查:

curl -s "https://graph.facebook.com/v20.0/<WABA_ID>/subscribed_apps" \
  -H "Authorization: Bearer $WHATSAPP_ACCESS_TOKEN"

如果 data 数组为空,或不包含你的应用 ID,这就是你的问题。

修复方法:

curl -X POST "https://graph.facebook.com/v20.0/<WABA_ID>/subscribed_apps" \
  -H "Authorization: Bearer $WHATSAPP_ACCESS_TOKEN"

这个调用会返回 {"success": true},之后下一条入站消息会在几秒内到达 Hermes Agent 的 webhook。不需要重启网关。如果之后你轮换 access token,记得再跑一次这个调用:订阅是绑定到应用的,但写入需要带 whatsapp_business_management 权限的 token。

原因三:你还在用 24 小时的临时 token

Meta 在 WhatsApp 设置页面上显示的 token 恰好在 24 小时后过期。如果你周二下午把它复制到 Hermes Agent 的 .env,机器人在周三下午哑了,就是这个原因。

症状:过期之后,网关在下一次外发时会记录 OAuthException 或 HTTP 401。来自 Meta 的入站 webhook 调用还能继续到达(它们不需要你的 token),但 Hermes 尝试回发的每条回复都会失败,所以机器人收到了你的消息、生成了回复,却在路上把它丢掉了。

修复方法是拿到一个永久的 System User token,而不是更长的临时 token:

在 Meta Business Suite 打开 Users 然后 System Users,创建一个角色为 Admin 的新 System User。
用 Full control 把你的 WhatsApp 应用和 WhatsApp Business Account 分配给这个 System User。
点击 Generate new token,选中你的应用,同时勾选 whatsapp_business_messaging(发消息需要)和 whatsapp_business_management(原因二的 subscribed_apps 调用需要)。
把过期时间设为 Never。复制 token,放进 WHATSAPP_ACCESS_TOKEN,重启网关。

离开之前先自检一下:

curl -s "https://graph.facebook.com/v20.0/me?access_token=$WHATSAPP_ACCESS_TOKEN"

应该返回你的 System User 的 ID 和名字,而不是一个 OAuth 错误。

原因四:你发到了错误的 Phone Number ID

WhatsApp Cloud API 用到三个 ID,都非常容易混淆:电话号码本身、Phone Number ID 和 WABA ID。Hermes Agent 需要的是 Phone Number ID,不是号码。如果你把电话号码填到了 WHATSAPP_PHONE_NUMBER_ID,每一次外发调用都会返回 Object with ID '+86...' does not exist,而每一次入站调用会到达但找不到对应的回复路径。

更让人晕的是,Phone Number ID 是一个 15 或 16 位的数字,看起来非常像一个电话号码。它不是。

去哪里找: 在 App Dashboard 里,打开 WhatsApp 然后 API Setup。From 下拉框列出你已注册的号码。每个号码下面用小字标着一个字段叫 Phone number ID,那就是 Hermes Agent 需要的值。

验证你手里的值是真的:

curl -s "https://graph.facebook.com/v20.0/$WHATSAPP_PHONE_NUMBER_ID?access_token=$WHATSAPP_ACCESS_TOKEN"

一个有效的 ID 会返回 display_phone_number、verified_name 和 quality_rating。错误的 ID 会返回 Graph API 错误,消息里会说出它找不到的那个 ID。

顺便检查一下 WHATSAPP_BUSINESS_ACCOUNT_ID 环境变量:那是拥有该号码的 WABA 的另一个 ID,原因二的订阅调用会用它,而从 dashboard 复制时把两个换错位置太容易了。

另外两个值得排除的陷阱

如果上面四个原因都排除了、消息还是不流动,再检查这两个:

应用还卡在 Dev 模式。 WhatsApp 只会为 24 小时内应用所有者发送或接收过消息、并且是在 WhatsApp 然后 API Setup 然后 To 里显式加入过的号码投递 webhook。等你准备好接真实用户流量时,在 App Review 里把应用切到 Live。
messages 这个 webhook 字段没有被订阅。 在 WhatsApp 然后 Configuration,看 Webhook fields 区域,确认 messages 有一个绿色钩。Meta 允许你保存一个没订阅任何字段的 webhook URL,而这会导致什么都收不到。

省时间的诊断顺序

当机器人变哑时,按这个顺序排查,而不是把所有东西重装一遍:

你在 QR 路径上吗? 如果是,先迁到 Cloud API,再花任何时间去做别的。Shortcake 不会走。
你的 WABA 订阅到你的应用了吗? 上面那个 curl 调用三秒钟就能回答。这是 Cloud API 部署上命中率最高的一项。
自检 token。 如果 token 死了、错了、缺少权限,curl /me 会立刻失败。
验证 Phone Number ID。 有效时,curl /$PHONE_NUMBER_ID 会返回号码的展示字段。
检查 Dev 模式和已订阅字段。 检查更慢,作为根因更少见,但在给 Meta 开工单前值得排除。

完整的第一次 WhatsApp 安装路径,参见 Hermes Agent WhatsApp 部署指南。如果 Telegram 适合你的用例,Telegram 与 WhatsApp 对比会在你做出承诺之前走一遍取舍。

当你不想每周和 Meta 斗一次

Meta 会按自己的节奏推 webhook UI 变更、收紧验证要求、打断 QR 路径。如果你的看法是,个人 AI 助手不应该为了回句"你好"就要求一个 Business Manager 账户和一个 System User token,从 Hermify 开始。Hermify 在 Telegram 上运行托管版 Hermes Agent,记忆和 skill 都一样,大约一分钟上线,不用管 Meta 那边的配置。