Web 客户端协议调试

open-xiaozhi-client（AGPL-3.0）是一个 Web 协议调试客户端：能连接小智服务端，查看文本与二进制帧日志、手动发送 JSON 消息。本页介绍用它调试协议的操作；消息字段的定义只在WebSocket 协议参考维护，本页不复制协议规范。

版本边界：本页操作按 main 分支 commit 667531b8bba9（2026-06-09，2026-11-08 观察）整理；该项目尚无正式 Release，升级后界面可能变化。本地启动已实测（2026-11-08）：npm install && npm run dev 可在约 1 分钟拉起（Node 22 / Vite 6.4.2；首装后需补装 @babel/generator @babel/traverse @babel/types 三个传递依赖，tsc -b 与 production build 均通过）；页面默认预填一个示例 OTA 地址，含连接、协议日志、设备、HTTP、设置等入口。未实测：与真实小智服务端的 WebSocket 端到端连接与对话（需真实服务端地址与凭据）。

准备

  • 一个可访问的小智服务端 OTA 服务地址（客户端以此为入口，自动完成 OTA 解析与设备激活，再建立 WebSocket；自建服务端的获取方式见自建服务端；官方服务的地址不公开分发，勿填写来历不明的端点）；
  • 设备标识：此客户端在浏览器环境中不能自定义 WebSocket 握手头，它的做法是把 device-id、client-id、authorization=Bearer <令牌> 追加到连接 URL 的 query 参数（源码 src/adapters/transport/WebSocketTransport.ts）。这是该客户端的适配方式，要求服务端支持 query 鉴权；固件侧以 HTTP 头承载这些字段的语义仍以协议参考为唯一正文，两者不冲突；
  • 本地运行 open-xiaozhi-client（克隆仓库按其 README 启动；也可用 --ota=<url> 预填默认地址），或使用作者提供的在线入口（可用性以项目说明为准）。

调试流程

1. 建立连接并观察两次 hello

在顶部「服务地址」填入 OTA 地址，点击连接。客户端先经 OTA 接口完成解析与激活（日志可见轮询 /activate），随后以 query 鉴权建立 WebSocket 并发送客户端 hello；服务端返回 hello，其中包含 transport、协议版本与音频参数；这些字段的含义见协议参考的 hello 章节。

观察点：OTA 解析是否成功、客户端 hello 是否发出、服务端 hello 是否返回、version 是否与固件预期一致。连不上时先看错误路径一节。

2. 查看帧日志

客户端按时间顺序列出文本帧（JSON）与二进制帧（音频）。文本帧的 type 字段决定消息类型（tts、stt、llm、mcp 等），完整类型表在协议参考。注意：URL query 中的令牌属于敏感信息，截图与分享日志前先脱敏。

3. 手动发送 JSON

在消息输入框构造一条客户端实际支持的消息类型（如 listen 的开始/停止、mcp 类消息）。此客户端固定版本（main 667531b）的消息实现不包含 goodbye 帧——不要照搬协议文档里的帧名假设它可发送；以客户端「协议日志」中真实可发送的类型为准。字段写错时服务端可能静默忽略或断开，对照协议参考核对。

4. 工具调用（MCP）

注意角色方向：此客户端虽然是 WebSocket 连接的发起方，但在 MCP 交互中承担 MCP 工具服务端角色——它响应 tools/list（返回 self.* 设备工具：音量、亮度、主题、拍照等）并处理 tools/call 后回结果（源码 src/application/McpService.ts 的 handle(msg)：第 44 行响应 tools/list、第 50 行处理 tools/call）；工具请求由小智后端发起。观察后端下发的 tools/list / tools/call 与客户端应答帧即可核对这条链路；MCP 消息结构见MCP 协议规范。

5. 错误路径

现象检查
连接立即断开OTA 地址是否可达、服务端是否支持 query 鉴权（不支持 query 的后端无法用此浏览器客户端直连）、端口
OTA 成功但无服务端 helloquery 中 device-id/client-id/authorization 是否被服务端接受；对照协议参考
发送 JSON 无响应字段名或结构错误（含发送了客户端不支持的帧类型）；服务端日志是否记录
二进制帧乱码非音频负载被当文本解析；用十六进制视图确认

边界

  • 本页不进入任何真实凭据；示例均为占位符；
  • 客户端是第三方 AGPL-3.0 项目，复制或改造其代码时注意许可义务；
  • 服务端兼容性以对应服务端文档为准，客户端界面声明不等于协议事实。