Web Client Protocol Debugging
open-xiaozhi-client (AGPL-3.0) is a web protocol debugging client: it connects to a XiaoZhi server, shows text and binary frame logs, and sends manual JSON messages. This page covers the debugging workflow; message fields are defined only in the WebSocket protocol reference.
main commit 667531b8bba9 (2026-06-09, observed 2026-11-08); the project has no formal release yet, so the UI may change. Local startup tested (2026-11-08): npm install && npm run dev is up in about a minute (Node 22 / Vite 6.4.2; after the first install add the three transitive deps @babel/generator @babel/traverse @babel/types; tsc -b and the production build both pass); the page pre-fills a sample OTA address and exposes connect, protocol log, device, HTTP and settings entries. Not tested: an end-to-end WebSocket connection and dialogue with a real XiaoZhi server (needs a real endpoint and credentials).Prepare
- A reachable XiaoZhi server OTA service address — the client takes this as its entry, resolves OTA and activates the device, then opens the WebSocket itself (self-hosted: see Self-Hosted Server; do not enter endpoints of unknown origin);
- Device identity: in a browser this client cannot set custom WebSocket handshake headers; instead it appends
device-id,client-idandauthorization=Bearer <token>to the connection URL’s query string (sourcesrc/adapters/transport/WebSocketTransport.ts). That is this client’s adaptation and requires the server to accept query auth; the firmware-side header semantics remain defined solely in the protocol reference — the two do not conflict; - Run open-xiaozhi-client locally per its README (
--ota=<url>pre-fills the default), or use the author’s hosted entry (availability per the project’s notes).
Workflow
1. Connect and watch both hellos
Enter the OTA address in the top “service address” box and connect. The client first resolves and activates via the OTA endpoint (the log shows /activate polling), then opens the WebSocket with query auth and sends its client hello; the server replies with hello containing transport, protocol version and audio parameters — see the hello section.
Watch for: OTA resolution, client hello sent, server hello back, and version matching the firmware’s expectation.
2. Frame log
The client lists text frames (JSON) and binary frames (audio) in order. The type field decides the message kind (tts, stt, llm, mcp, …); the full table is in the protocol reference. Note: the token in the URL query is sensitive — redact screenshots and logs before sharing.
3. Manual JSON
Compose a message type the client actually implements (e.g. listen start/stop, or mcp messages). The pinned build (main 667531b) implements no goodbye frame — do not assume every frame name in the protocol docs is sendable here; trust the sendable types shown in the client’s protocol log. A wrong field may be silently ignored or the connection dropped — check against the reference.
4. Tool calls (MCP)
Mind the role direction: although this client initiates the WebSocket connection, in MCP interactions it acts as the MCP tool server — it answers tools/list (returning self.* device tools: volume, brightness, theme, photo) and handles tools/call, replying with results (source src/application/McpService.ts, handle(msg): line 44 responds to tools/list, line 50 handles tools/call); tool requests are issued by the XiaoZhi backend. Watch the backend’s tools/list / tools/call and the client’s replies to verify this path; see the MCP protocol spec.
5. Error paths
| Symptom | Check |
|---|---|
| Connection drops immediately | OTA address reachable; server supports query auth (backends without query auth cannot be reached by this browser client); port |
OTA OK but no server hello | device-id/client-id/authorization in the query accepted by the server; see the reference |
| JSON sent, no response | wrong fields or structure (including frame types the client does not implement); server logs |
| Binary frames garbled | non-audio payload parsed as text; confirm with a hex view |
Limits
- No real credentials on this page; examples are placeholders;
- The client is a third-party AGPL-3.0 project; mind license obligations when copying or adapting its code;
- Server compatibility follows the server’s own documentation; client UI claims are not protocol facts.