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:
@@ -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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user