Hermes Agent 网关:4 步打通 WebSocket 实时链路【免费下载链接】hermes-agentThe agent that grows with you项目地址: https://gitcode.com/GitHub_Trending/he/hermes-agent复现一个卡点:HTTP 通了,聊天页却连不上你装好 Hermes Desktop 客户端,填上远程网关地址,Test remote 亮了绿灯。可聊天页一直卡在Could not connect to Hermes gateway,消息发不出去。大多数人会反复检查 HTTP 服务起没起,但真正卡住的其实是第二条通道——WebSocket 实时链路,而不是 HTTP 存活探测。Hermes Agent 用一个 gateway 进程作为对外统一入口:Telegram、Discord、Slack 这些平台的聊天,以及 Desktop 客户端,都挂在同一个网关上。Desktop 的启动流程实际做两件独立的事:主进程先发一个 HTTP 请求到/api/status确认网关活着,随后聊天界面再打开/api/ws的 WebSocket 通道,这一步成功后消息收发才真正可用。核心概念速览维度HTTP 通道WebSocket 通道适用场景职责/api/status探活,一问一答/api/ws全双工,承载聊天流判断服务在不在 vs 能不能聊天认证方式token 放在请求头查询参数?token或 OAuth 签发的?ticket本地 token 模式 / OAuth 模式失败表现超时或 401握手成功后在宽限窗口内被关闭区分服务挂了和凭证被拒关键差异在升级请求上:WS upgrade 额外挂了 Host/Origin 检查、对端 IP 检查这些 HTTP 状态路由看不到的守卫,所以网关完全可能通过 HTTP 探活,却在 WebSocket 这一侧拒绝连接。先跑通:最小可用配置拉代码并装好环境:git clone https://gitcode.com/GitHub_Trending/he/hermes-agent,安装脚本会替你处理 uv 和 Python 3.11,已有安装可直接用。跑一遍hermes setup完成首次配置向导,拿到网关 token。执行hermes gateway start启动网关,本地默认监听 127.0.0.1:9119。接入客户端:Desktop 里填 base URL,应用自动拼好 WebSocket 地址;用脚本自接时直接用下面两种形态。# 本地 http base → ws 通道 ws://127.0.0.1:9119/api/ws?token你的token # 远程 https base → wss 通道,OAuth 场景用 ?ticket wss://your-host.example.com/api/ws?ticketws-ticket效果:连接成功后你会收到gateway.ready帧,之后客户端的流式输出、工具活动、消息全部走这条通道,聊天页立刻可用。调优与进阶现象:Test remote 绿灯,聊天却用不了。原因是两次检查跑在不同进程、不同传输、不同凭证上,按钮只覆盖了前半段。处理方式:照 gateway-ws-probe.ts 里内置探测的写法,在 HTTP 探活后再真开一次 WS——握手成功后等 750ms 宽限窗口,收到任意帧或连接仍算成功,提前断开就判为升级被接受但凭证被拒。这套两段判定,自己集成时值得原样抄。现象:握手成功后几百毫秒内连接被关闭。原因是网关接受了 upgrade,但在后续阶段拒绝了 token 或 ws-ticket。处理方式:先查 token 是否过期或被轮换;OAuth 场景下 ws-ticket 是 POST/api/auth/ws-ticket在连接瞬间现签的,旧 ticket 复用必被拒,每次重连前都重新签发。签发与选凭证的完整逻辑在 connection-config.ts 里,token 模式和 ticket 模式各走一条 URL 拼装分支。现象:远程网关 HTTP、WS 双双失败,本地却正常。原因是网关前面套了 Cloudflare Access 这类接入代理,要求额外认证头。处理方式:在 Desktop 的 Settings → Connections 里按连接配置 Extra gateway headers,应用会把 https 与 wss 视为同一网关源,WS 升级自动带上这些头,不用配两遍。避坑清单❌ 远程 https 地址拼出 ws:// 明文通道 → ✅ 按 base URL 的 scheme 强制切换 ws/wss,否则浏览器直接拦❌ 把含/、、空格的 token 原样塞进链接 → ✅ 先做 URL 编码再放进查询参数,否则凭证在中间就被截断❌ 只用 HTTP 探活绿灯判定网关健康 → ✅ 探活和 WS 握手都要通过,聊天页只听 WebSocket 的❌ 断线后用同一个 ws-ticket 重连 → ✅ OAuth 场景每次连接前重新签发 ticket❌ 自测时只盯端口通不通 → ✅ 升级请求还带 Host/Origin 与对端 IP 校验,本机改个 Host 头一样会被拒一句话收束:HTTP 负责服务在不在,WebSocket 负责能不能聊,token 或新签 ticket 通过查询参数的二次校验,通道才算真正打通。继续往下读,建议先看 apps/desktop/README.md 里远程连接与额外头的说明,再翻 AGENTS.md 了解网关在整个架构里的位置。【免费下载链接】hermes-agentThe agent that grows with you项目地址: https://gitcode.com/GitHub_Trending/he/hermes-agent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Hermes Agent 网关:4 步打通 WebSocket 实时链路
Hermes Agent 网关:4 步打通 WebSocket 实时链路【免费下载链接】hermes-agentThe agent that grows with you项目地址: https://gitcode.com/GitHub_Trending/he/hermes-agent复现一个卡点:HTTP 通了,聊天页却连不上你装好 Hermes Desktop 客户端,填上远程网关地址,Test remote 亮了绿灯。可聊天页一直卡在Could not connect to Hermes gateway,消息发不出去。大多数人会反复检查 HTTP 服务起没起,但真正卡住的其实是第二条通道——WebSocket 实时链路,而不是 HTTP 存活探测。Hermes Agent 用一个 gateway 进程作为对外统一入口:Telegram、Discord、Slack 这些平台的聊天,以及 Desktop 客户端,都挂在同一个网关上。Desktop 的启动流程实际做两件独立的事:主进程先发一个 HTTP 请求到/api/status确认网关活着,随后聊天界面再打开/api/ws的 WebSocket 通道,这一步成功后消息收发才真正可用。核心概念速览维度HTTP 通道WebSocket 通道适用场景职责/api/status探活,一问一答/api/ws全双工,承载聊天流判断服务在不在 vs 能不能聊天认证方式token 放在请求头查询参数?token或 OAuth 签发的?ticket本地 token 模式 / OAuth 模式失败表现超时或 401握手成功后在宽限窗口内被关闭区分服务挂了和凭证被拒关键差异在升级请求上:WS upgrade 额外挂了 Host/Origin 检查、对端 IP 检查这些 HTTP 状态路由看不到的守卫,所以网关完全可能通过 HTTP 探活,却在 WebSocket 这一侧拒绝连接。先跑通:最小可用配置拉代码并装好环境:git clone https://gitcode.com/GitHub_Trending/he/hermes-agent,安装脚本会替你处理 uv 和 Python 3.11,已有安装可直接用。跑一遍hermes setup完成首次配置向导,拿到网关 token。执行hermes gateway start启动网关,本地默认监听 127.0.0.1:9119。接入客户端:Desktop 里填 base URL,应用自动拼好 WebSocket 地址;用脚本自接时直接用下面两种形态。# 本地 http base → ws 通道 ws://127.0.0.1:9119/api/ws?token你的token # 远程 https base → wss 通道,OAuth 场景用 ?ticket wss://your-host.example.com/api/ws?ticketws-ticket效果:连接成功后你会收到gateway.ready帧,之后客户端的流式输出、工具活动、消息全部走这条通道,聊天页立刻可用。调优与进阶现象:Test remote 绿灯,聊天却用不了。原因是两次检查跑在不同进程、不同传输、不同凭证上,按钮只覆盖了前半段。处理方式:照 gateway-ws-probe.ts 里内置探测的写法,在 HTTP 探活后再真开一次 WS——握手成功后等 750ms 宽限窗口,收到任意帧或连接仍算成功,提前断开就判为升级被接受但凭证被拒。这套两段判定,自己集成时值得原样抄。现象:握手成功后几百毫秒内连接被关闭。原因是网关接受了 upgrade,但在后续阶段拒绝了 token 或 ws-ticket。处理方式:先查 token 是否过期或被轮换;OAuth 场景下 ws-ticket 是 POST/api/auth/ws-ticket在连接瞬间现签的,旧 ticket 复用必被拒,每次重连前都重新签发。签发与选凭证的完整逻辑在 connection-config.ts 里,token 模式和 ticket 模式各走一条 URL 拼装分支。现象:远程网关 HTTP、WS 双双失败,本地却正常。原因是网关前面套了 Cloudflare Access 这类接入代理,要求额外认证头。处理方式:在 Desktop 的 Settings → Connections 里按连接配置 Extra gateway headers,应用会把 https 与 wss 视为同一网关源,WS 升级自动带上这些头,不用配两遍。避坑清单❌ 远程 https 地址拼出 ws:// 明文通道 → ✅ 按 base URL 的 scheme 强制切换 ws/wss,否则浏览器直接拦❌ 把含/、、空格的 token 原样塞进链接 → ✅ 先做 URL 编码再放进查询参数,否则凭证在中间就被截断❌ 只用 HTTP 探活绿灯判定网关健康 → ✅ 探活和 WS 握手都要通过,聊天页只听 WebSocket 的❌ 断线后用同一个 ws-ticket 重连 → ✅ OAuth 场景每次连接前重新签发 ticket❌ 自测时只盯端口通不通 → ✅ 升级请求还带 Host/Origin 与对端 IP 校验,本机改个 Host 头一样会被拒一句话收束:HTTP 负责服务在不在,WebSocket 负责能不能聊,token 或新签 ticket 通过查询参数的二次校验,通道才算真正打通。继续往下读,建议先看 apps/desktop/README.md 里远程连接与额外头的说明,再翻 AGENTS.md 了解网关在整个架构里的位置。【免费下载链接】hermes-agentThe agent that grows with you项目地址: https://gitcode.com/GitHub_Trending/he/hermes-agent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考