docs(tui): correct HERMES_TUI_GATEWAY_URL — dashboard-internal, not remote-attach (#42162)

The TUI docs presented HERMES_TUI_GATEWAY_URL + /api/ws as a supported
'attach the TUI to a standalone running gateway' workflow. It isn't.

/api/ws exists only inside the dashboard's FastAPI server
(hermes_cli/web_server.py), which spawns its own embedded TUI child and
injects the var as an internal wiring detail. The OpenAI-compat API
server (api_server platform) deliberately does not serve /api/ws, so the
documented ws://host:port/api/ws workflow 404s — the cause of #32882 and
the two PRs (#32904, #32955) that tried to add the route to the wrong
surface.

Rewrites the section in en + zh-Hans to describe the var accurately and
point users at shared state.db / dashboard embedded chat for multi-surface
session sharing.
This commit is contained in:
Teknium
2026-06-08 09:37:03 -07:00
committed by GitHub
parent 399b8ee5f0
commit 74744795af
2 changed files with 10 additions and 28 deletions
@@ -229,24 +229,15 @@ TUI 附带有主见的按区块默认值,将轮次以实时转录形式流式
会话生命周期、搜索、压缩和导出,请参阅[会话](sessions.md)。
## 连接到运行中的 gateway
## TUI 如何与其 gateway 通信
默认情况下,TUI 会在进程内启动自己的 gateway,因此每个 TUI 实例是自包含的。如果你已有一个长期运行的 gateway(例如在 tmux 中运行 `hermes gateway run`,或 systemd / launchd 服务),可以将 TUI 指向该 gateway——TUI 将成为一个瘦客户端,与连接到同一 gateway 的所有其他界面(消息平台、Web 仪表板、其他 TUI 会话)共享状态
默认情况下,TUI 会在进程内启动自己的 gateway,因此每个 TUI 实例是自包含的——无需任何配置
启动前通过环境变量设置 websocket URL
你可能会在代码或日志中看到 `HERMES_TUI_GATEWAY_URL` 环境变量。它是 **Web 仪表板的内部接线细节**,并非面向用户的远程连接开关。当你打开仪表板的 "Chat" 标签页(`hermes dashboard``/chat`)时,仪表板的 Web 服务器会派生一个内嵌的 TUI 子进程,并注入 `HERMES_TUI_GATEWAY_URL`,让该子进程通过本地回环 WebSocket(`/api/ws`)连接到仪表板自己的进程内 `tui_gateway``/api/ws` 端点仅存在于仪表板服务器内部(`hermes_cli/web_server.py`),并绑定到该进程的生命周期和认证。
```bash
export HERMES_TUI_GATEWAY_URL="ws://localhost:8765/api/ws?token=<auth-token>"
hermes --tui
```
不存在通用的"将任意 TUI 指向任意独立 gateway 端口"的模式。特别是,OpenAI 兼容 API 服务器(`hermes gateway` / `api_server` 平台)**不**提供 `/api/ws`——它是模型后端接口(`/v1/chat/completions``/v1/models` 等),并刻意不暴露 TUI 的 JSON-RPC 控制通道。将 `HERMES_TUI_GATEWAY_URL` 设置为该端口将返回 404。
token 来自 gateway 的 API 认证配置(参见 [API Server](features/api-server.md))。设置该环境变量后,TUI 将:
- 完全跳过启动本地 gateway——无重复平台适配器,无端口冲突。
- 通过 websocket 将所有操作(斜杠命令、图片附件、浏览器进度、语音事件等)路由到共享 gateway。
- 在请求之间 gateway URL 轮换(新 token)时自动重连。
这与 Web 仪表板内嵌 TUI 使用的是同一通道(参见 [Web Dashboard](features/web-dashboard.md#chat))——一个 gateway,多个客户端。
如果你希望多个界面共享同一组会话,请使用共享的 `~/.hermes/state.db`(参见[会话](sessions.md))或 Web 仪表板的内嵌聊天(参见 [Web Dashboard](features/web-dashboard.md#chat))——而不是手动设置 gateway URL。
## 回退到 Classic CLI