Hermes Agent WhatsApp 老是要求重扫二维码，或者明明连上了却收不到消息，通常是两类问题：session 没持久化，或者 WHATSAPP_ALLOWED_USERS 没放行发件人。官方 WhatsApp 文档把这两点都写得很细，先查这两个比重装快得多。
先查 session
Hermes 会把 WhatsApp 会话保存在 ~/.hermes/platforms/whatsapp/session。如果这个目录不存在、不可写，或者你跑在容器里却没挂持久卷，就会出现“每次重启都得重扫”的症状。手机长期离线、WhatsApp 更新、手动 unlink 也会让旧 session 失效。
再查为什么收不到消息
如果只是部分人发不过来，重点看 WHATSAPP_ALLOWED_USERS 是否包含对方号码，格式必须带国家码、但不要 + 和空格。想全部放行可以临时设成 *，先验证链路是否正常。
什么时候该重扫
只有 session 真的失效时才需要 hermes whatsapp 重新配对。若只是网络抖动，网关会自己处理临时断线。若是 Hermes 更新后突然桥接异常，官方建议先更新版本，再考虑重配。
一句话：频繁扫二维码，多半是 session；收不到消息，多半是 allowlist。先把这两件事拆开，排障就快了。
官方开源地址：https://github.com/NousResearch/hermes-agent；官方文档入口：https://hermes-agent.nousresearch.com/。
