https://blog.margrop.net/tag/%E8%B0%83%E8%AF%95/ Recent content in 调试 on 魔都水滴 Hugo zh-CN Sun, 31 May 2026 08:00:00 +0800 https://blog.margrop.net/post/hermesagent-wechat-wecom-relay-timeout-debugging/ Sun, 31 May 2026 08:00:00 +0800 https://blog.margrop.net/post/hermesagent-wechat-wecom-relay-timeout-debugging/ <h2 id="先说结论">先说结论</h2> <p>这次故障看起来像“模型不行”或者“微信通道坏了”，但真正把消息链路掐断的，是我本地那层 <code>relay</code> 的超时设置。它把整条上游请求的等待窗口限制成了 3 秒，而真实的 WeChat / WeCom 消息 turn 往往需要更久才能从新 API 网关拿到完整回复。结果就是：relay 先断开，HermesAgent 只能看到 <code>Connection error</code>、<code>RemoteProtocolError</code>，然后主模型和 fallback 一起被耗尽。</p> <p>更准确地说，这不是 HermesAgent 核心代码的问题，也不是模型名的问题，而是一个本地外置组件的连接策略问题。把 <code>connect timeout</code> 和 <code>response wait</code> 混成同一个超时，等于给长请求做了一个错误的截止时间。修复方式也不复杂：连接阶段保留短超时，连接成功后把 socket 切回阻塞等待；同时把 relay 做成独立、可持续启动的服务，不再把它绑死在临时 shell 里。</p> <p><img src="https://blog.margrop.net/post-images/hermesagent-wechat-wecom-relay-timeout-debugging/cover.png" alt="HermesAgent relay 调试封面"></p> <h2 id="问题背景">问题背景</h2> <p>HermesAgent 这条链路不是单机脚本，而是一条完整的消息生产线。用户从微信或企业微信发出一句话，消息会先进入 Hermes 的通道层，再进入 Gateway，接着经过本地 relay 转发到自建的 NewAPI 网关，最后才到模型服务。模型回来的内容还要经过 Hermes 的消息整理、工具调用处理、最终拼接，再发回原始通道。</p> <p>这种结构的好处是灵活，坏处也很现实：任何一层都可能制造“看起来像模型故障”的表象。你看到的是“没有回复”或者“Connection error”，但根因可能在更外层的 relay、socket、超时、代理或者会话路由里。</p> <p>这次我一开始也走了老路，先怀疑模型配置。因为从表象看，主模型和 fallback 都失败了，日志里反复出现：</p> <div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;-webkit-text-size-adjust:none;"><code class="language-text" data-lang="text"><span style="display:flex;"><span>Primary model failed </span></span><span style="display:flex;"><span>switching to fallback </span></span><span style="display:flex;"><span>API failed after 1 retries </span></span><span style="display:flex;"><span>Connection error </span></span><span style="display:flex;"><span>Max retries exhausted </span></span></code></pre></div><p>如果你只看这一段，很容易得出“模型端不稳定”的结论。但这类结论通常太早。因为同一批模型在别的入口上是能正常工作的，<code>/v1/models</code> 也能返回，简单的 health check 也没有异常。真正出问题的是“真实消息 turn”。</p>