WebUI 指南

浏览器访问根路径 http://127.0.0.1:8787/ 即可打开 WebUI (端口同网关监听端口， 本文示例用 18787，见 快速上手)。启用 [auth] 后需先完成 OIDC 登录，详见 配置参考 — auth。

Records — 转发记录与会话时间线

Records 页是查看 “LLM 到底看到了什么” 的窗口：

• 会话 / 轮次时间线： 每次转发按请求内容的前缀延续性聚类为会话 (Session)，会话内按 轮次 (Node) 排列。点击会话展开轮次列表，点击轮次查看该次请求与响应的完整详情。
• LLM 视角： 详情中的请求内容是 Redact 之后发往上游的样子 — Secret 位置以高亮 Mock 呈现，可以此确认保护确实生效。
• 路由归属： 经路由 endpoint 转发的轮次带 “via …” 角标，Upstream 字段显示 该轮实际命中的上游 (路由切换后历史轮次仍如实记录各自归属)。
• 响应解析： 响应体按协议解析展示 (含流式响应的累积视图)。

典型操作： 发完请求后回到 Records 页确认该笔转发的 redactions 计数；排查 “LLM 为什么这么回答” 时对照 LLM 视角查看 Mock 替换后的上下文。

图: Records 页 — 会话列表与轮次时间线, Secret 位置以高亮 Mock 呈现 (LLM 视角)。

注意

Records 的会话徽章统计是进程内口径，重启网关后归零；持久的用量账本在 Usage 页 (见文末)。

Secrets — Secret 注册表

管理 Redact 保护清单：

• 查看： 当前生效的 Secret 列表 (id / 名称 / 类别)。
• 新增 / 编辑： 在 WebUI 创建的 Secret 保存在动态状态文件 secret-guard.state.toml (明文落盘，敏感级别与 secret-guard.toml 同级，见 配置参考 — 双层配置)。
• 覆盖决策： 对声明式文件里的 static 条目可做动态决策 — 覆盖字段值或直接禁用 (Disabled)，不改动 secret-guard.toml 本身。

典型操作： 临时让某个 Secret 停止 Redact 排障时，将其决策置为禁用；排完再恢复。

图: Secrets 页 — Secret 注册表与覆盖决策。

Providers — Provider 注册表

管理上游端点清单：

• Direct / Router 两种构造： 对话框顶部 Kind 选择器切换构造，表单按构造显示对应 字段组 (Direct: Protocol / Base URL / API Key；Router: Routes 编辑器)。
• Router 的 routes 编辑： 调整 priority、禁用某条路由、新增路由行，均通过提交 完整的 routes 数组 表达 (覆盖静态 Router 的写法，语义见 配置参考 — 路由 endpoint)。
• 启停： 对 Provider 做禁用 / 启用决策，禁用后转发返回 503。

图: Providers 页 — Direct / Router 两种构造的 Provider 注册表。

警告

已知限制： 仅存在于动态状态 (WebUI 创建、无 static 基线) 的条目从 Direct 切到 Router 再切回 Direct 时会丢失 api_key — Router 构造无处存放鉴权字段，切回后需重新 填写 (表单 placeholder 显示 “(optional)” 而非 “unchanged” 即是提示)。 声明式文件有条目的 Provider 不受影响。

API Keys — 转发路径认证

签发 / 管理转发路径认证用的 API key (启用 [auth] 后，SDK 请求需带 Authorization: Bearer sg_...)：

• 签发： 生成新 key，配置到 Agent 工具的 api_key 参数 (网关侧用它认证客户端， 上游真正的 key 由 Provider 配置注入)。
• 禁用 / 启用： 随时吊销某个 key。声明式文件里 [[auth.api_keys]] 预设的静态 key 不可删除，只能 disable / enable。

图: API Keys 页 — 签发与管理转发路径认证 key。

Usage — 用量统计

WebUI 另有 Usage 页展示模型用量统计： token 用量 100% 来自上游响应回显的 usage 字段，成本按 models.dev 价目表估算 (恒为估算)。明细持久化为 JSONL 账本 (重启不丢)。数据采集与定价的配置见 配置参考 — usage。

WebUI 编辑落盘到哪？

所有通过 WebUI 做的修改 (Secrets / Providers / API Keys / 覆盖决策) 都写入动态状态文件 secret-guard.state.toml，删除该文件即重置全部动态修改。[server] / [redact] / [auth] 等声明式段落仅在启动时读取，WebUI 改不生效 (重启网关才生效)。