【xiaozhi-客户端】xiaozhi-web-client 连接客户端 6位有效码

当服务器启用设备认证时，新设备首次连接需要获取六位验证码进行激活。本项目提供了脚本用于获取验证码。xiaozhi-web-client 提供了一个便捷的Web界面来使用小智语音助手。通过简单的配置，你可以快速启动服务并开始语音对话。配置 .env 文件- 设置服务器地址和端口获取验证码- 如果服务器启用认证，使用获取六位验证码启动服务- 使用 Poetry 或 Docker 运行开始使用- 打开浏

CodeWang_NC

19人浏览 · 2026-04-26 19:24:09

CodeWang_NC · 2026-04-26 19:24:09 发布

小智Web客户端介绍与使用指南

一、项目概述

xiaozhi-web-client 是一个开源的小智Web客户端实现，提供了语音对话功能。该项目通过WebSocket实现实时通信，支持Opus音频编码，让用户可以在浏览器中直接与小智进行语音交互。

项目	说明	链接
xiaozhi-esp32-server	小智ESP32服务器端	xiaozhi-esp32-server
xiaozhi-web-client	小智ESP32客户端	xiaozhi-web-client

项目地址：xiaozhi-web-client

注意：该项目目前暂停维护，但仍可使用。官方推荐使用开源的安卓端获得更好的体验。
启动客户端的的时候，最好是已经启动好咯服务端。

二、功能特点

功能	说明
实时语音对话	通过麦克风进行语音交互，支持实时录音和播放
文字消息支持	可以直接在输入框输入文字进行对话
WebSocket通信	使用WebSocket协议实现低延迟的双向通信
Opus音频编码	采用高效的Opus编码，保证音质的同时减少带宽占用
自动重连机制	连接断开后自动尝试重连
流式音频播放	支持音频流的实时播放，无需等待完整下载
设备认证支持	可配置Token进行身份验证

三、项目架构

核心文件说明

xiaozhi-web-client/
├── app.py                 # Web服务器，提供Web界面并管理代理服务
├── proxy.py               # WebSocket代理服务器，处理音频转换和数据转发
├── get_valid_code.py      # 获取六位验证码的工具脚本
├── templates/index.html   # 前端界面
├── static/                # 静态资源目录
│   ├── audio-processor.js # 音频处理模块
│   └── styles.css         # 样式文件
├── .env                   # 环境配置文件
└── .env.example           # 环境配置示例文件

工作流程

浏览器 (Web界面)
    ↓ WebSocket连接
本地代理服务器 (proxy.py, 端口5002)
    ↓ 音频编码/解码 + 数据转发
远程服务器 (xiaozhi-esp32-server)

四、快速开始

方式一：源码运行

1. 配置环境变量

首先从 .env.example 创建 .env 文件：

cp .env.example .env

2. 安装依赖

推荐方式 - 使用 Poetry：

poetry install
poetry run python app.py

直接运行：

pip install -r requirements.txt
python app.py

方式二：Docker运行

使用 docker-compose（推荐）：

# 构建并启动
docker-compose up -d

# 查看日志
docker-compose logs -f

# 停止服务
docker-compose down

直接使用 Docker：

# 构建镜像
docker build -t xiaozhi-web .

# 运行容器
docker run -d \
  --name xiaozhi-web \
  -p 5001:5001 \
  -p 5002:5002 \
  -e WS_URL=ws://your_server_address:9005 \
  -e DEVICE_TOKEN=your_token \
  xiaozhi-web

启动后访问 http://localhost:5001 即可使用。

五、.env 文件配置详解

.env 文件是项目的核心配置文件，控制着服务器地址、认证信息等关键参数。

配置参数说明

序号	参数	说明	默认值	示例
1	`WS_URL`	WebSocket服务器地址	`ws://localhost:9005`	`ws://your_server:8000/xiaozhi/v1/`
2	`DEVICE_TOKEN`	设备认证令牌	`123`	从服务器获取的Token
3	`WEB_PORT`	Web服务器端口	`5001`	`5001`
4	`PROXY_PORT`	WebSocket代理端口	`5002`	`5002`
5	`ENABLE_TOKEN`	是否启用Token验证	`true`	`true` / `false`
6	`LOCAL_PROXY_URL`	本地代理地址	`ws://localhost:5002`	`ws://localhost:5002`
7	`CLIENT_ID`	客户端唯一标识	自动生成UUID	`6d6ca305-10ac-4349-8609-6ca6330d092c`

配置示例

完整配置（启用认证）：

# 1. WebSocket服务器地址
WS_URL=ws://your_server_address:8000/xiaozhi/v1/

# 2. 设备认证令牌（从服务器获取）
DEVICE_TOKEN=your_valid_token

# 3. Web服务器端口
WEB_PORT=5001

# 4. WebSocket代理端口
PROXY_PORT=5002

# 5. 启用Token验证
ENABLE_TOKEN=true

# 6. 本地代理地址
LOCAL_PROXY_URL=ws://localhost:5002

# 7. 客户端唯一标识（首次运行自动生成）
CLIENT_ID=6d6ca305-10ac-4349-8609-6ca6330d092c

配置要点

WS_URL：如果你使用 xiaozhi-esp32-server，地址格式为 ws://服务器地址:端口/xiaozhi/v1/
ENABLE_TOKEN：设为 false 可跳过Token验证，适合本地测试
CLIENT_ID：首次运行时自动生成并写入配置，用于标识客户端身份

六、如何获取六位有效验证码

概述

当服务器启用设备认证时，新设备首次连接需要获取六位验证码进行激活。本项目提供了 get_valid_code.py 脚本用于获取验证码。

工作原理

验证码获取流程：

1. 获取设备MAC地址作为设备ID
2. 构造OTA请求（模拟ESP32设备）
3. 向服务器OTA接口发送请求
4. 服务器返回激活码（如设备未认证）
5. 使用验证码完成设备激活

使用方法

1. 确保服务器正在运行

确保你的 xiaozhi-esp32-server 已启动，OTA接口默认端口为 8002。

2. 修改脚本中的服务器地址

编辑 get_valid_code.py，将 ota_http_url 改为你的服务器地址：

ota_http_url = "http://127.0.0.1:8002/xiaozhi/ota/"

如果服务器在其他地址，改为：

ota_http_url = "http://your_server_ip:8002/xiaozhi/ota/"

3. 运行脚本获取验证码

python get_valid_code.py

4. 输出结果

脚本会输出以下信息：

已认证设备：输出 6位有效验证码...已认证
未认证设备：输出具体的六位验证码，如 6位有效验证码...123456

获取验证码后

在Web界面的设置面板中输入验证码
或直接将验证码配置到 .env 文件的 DEVICE_TOKEN 参数
设备激活后，后续连接无需再次验证

源码解析

import requests
import json
from loguru import logger
from app import get_mac_address

def load_param():
    device_id = get_mac_address()               # e:7a:00:f1:4a:2b
    ota_headers = {
        'Device-Id': device_id,
        'Content-Type': 'application/json'
    }
    ota_post_data = {
        "flash_size": 16777216,
        "minimum_free_heap_size": 8318916,
        "mac_address": device_id,
        "chip_model_name": "esp32",
        "chip_info": {
            "model": 9,
            "cores": 2,
            "revision": 2,
            "features": 18
        },
        "application": {
            "name": "xiaozhi",
            "version": "1.0.1"
        },
        "partition_table": [

        ],
        "ota": {
            "label": "factory"
        },
        "board": {
            "type": "demo",
            "ip": "127.0.0.1",
            "mac": device_id
        }
    }
    return device_id, ota_headers, ota_post_data

def get_ota_version(ota_http_url, device_id, ota_headers, ota_post_data):
    response = requests.post(ota_http_url, headers=ota_headers, data=json.dumps(ota_post_data))
    response_data = response.json()
    logger.info(f"device_id....................................{device_id}")
    if response_data.get('activation', '') == "":
        logger.info(f"6位有效验证码..................................已认证")
    else:
        valid_code = response_data.get('activation', '').get('code', '123321')
        logger.info(f"6位有效验证码.........................................{valid_code}")
    return response

# 获取六位有效验证嘛
if __name__ == "__main__":
    ota_http_url = "http://127.0.0.1:8002/xiaozhi/ota/"
    device_id, ota_headers, ota_post_data = load_param()
    response = get_ota_version(ota_http_url, device_id, ota_headers, ota_post_data)

七、使用说明

基本操作

语音对话：点击绿色的"开始通话"按钮开始录音，再次点击结束录音
文字对话：直接在输入框输入文字，按回车或点击发送按钮
设置面板：点击右上角齿轮图标可配置服务器地址和认证信息

注意事项

注意点	说明
浏览器权限	需要允许浏览器访问麦克风
HTTPS要求	生产环境建议使用HTTPS，否则部分浏览器可能限制麦克风访问
浏览器推荐	建议使用Chrome或Firefox浏览器
端口占用	确保5001和5002端口没有被其他程序占用
服务器配置	确保 `WS_URL` 和 `DEVICE_TOKEN` 配置正确