小智 AI 聊天机器人文档中心 | 小智AI.Dev
使用指南
自建服务端：让小智设备连接你自己的服务器

自建服务端：让小智设备连接你自己的服务器

小智设备本身不运行大模型：设备负责采集和播放音频，对话由服务端完成。固件默认连接官方服务器；如果你想自己选择大模型、语音识别与语音合成，或者自己决定对话数据放在哪里，可以自建服务端。

本页只做概览：讲清设备与服务端怎么衔接、社区有哪些开源服务端，并以 xiaozhi-esp32-server 为例说明接入步骤。第三方项目的完整教程不在这里搬运，具体步骤以所选项目的文档为准。

自建服务端是进阶用法。社区服务端是独立的第三方项目，不属于本站，也不属于上游固件仓库；本站不提供服务端，也不为第三方项目担保。公网部署前请先读完文末「安全警示」。

一、先判断是否需要自建

你的情况建议
只想用现成的语音助手使用默认的官方服务器，流程见首次启动
想接入自己选择的大模型、语音识别和语音合成自建服务端
想自己决定对话数据的保存位置，或加入自己的设备控制与知识库自建服务端
开发或调试固件的通信协议自建服务端，或对照WebSocket 协议自行实现

二、设备如何找到你的服务器

固件联网后向 OTA 地址发起请求，服务器在响应里下发后续对话使用的 websocket 或 mqtt 配置，设备按这份配置初始化通信协议（字段说明见首次启动）。因此一个服务端至少要提供两部分：

  1. OTA 接口：返回版本、激活信息和通信配置；
  2. 对话通道：WebSocket，或 MQTT + UDP，并在其上完成语音识别、大模型对话和语音合成。

让设备改用你的 OTA 地址有两种方式：

  • 配网页的「高级」选项卡：进入配网模式后填写 OTA 地址并保存，不需要重新编译；
  • 自行编译：在 menuconfig 中修改 Default OTA URL（CONFIG_OTA_URL）。

设备会把 Device-Id（MAC 地址）、Client-Id 等标识随请求发给 OTA 地址，所以只填写你信任的服务器。

三、社区开源服务端

下表来自上游固件 README 的「相关开源项目」，并已逐个核对仓库状态与许可证（2026-10-23）。仓库内容、功能和许可证会变化，请以仓库当前状态为准。

项目技术形态许可证概要
xinnan-tech/xiaozhi-esp32-serverPython + Java + VueMIT支持 MQTT + UDP、WebSocket、MCP 接入点、声纹识别、知识库；提供最简化与全模块两种部署方式
joey-zhou/xiaozhi-esp32-server-javaJava（Spring Boot）MIT管理后台与对话服务分为两个进程；README 技术栈依赖 MySQL、Redis 和 Qdrant
AnimeAIChat/xiaozhi-server-goGo修改版 Apache 2.0，含附加条件面向个人和家庭场景，通过 WebSocket 通信，本地 SQLite 存储配置；附加条件包括未经书面授权不得用于多租户，请先阅读其 LICENSE
hackers365/xiaozhi-esp32-server-golangGoMIT全流式 ASR → LLM → TTS，支持 WebSocket 与 MQTT + UDP，提供预编译一键启动包和 Docker 部署

客户端、嵌入式移植等其他项目见生态项目。

四、以 xiaozhi-esp32-server 为例

下面的事实取自该项目 v0.9.7 标签的 README 与 docs/。更新的版本请以主分支文档为准。

部署方式

方式内容适用
最简化安装智能对话、单智能体；配置保存在配置文件，不需要数据库；可用 Docker 或源码运行配置较低的环境，先跑通
全模块安装智能对话、多用户、多智能体，并带智控台界面；数据保存在数据库完整功能体验

默认地址与端口

最简化安装的默认接口为：

  • WebSocket：ws://<局域网 IP>:8000/xiaozhi/v1/
  • OTA：http://<局域网 IP>:8003/xiaozhi/ota/

设备要能访问到这个地址，所以不要使用 localhost 或 127.0.0.1。用 Docker 部署时，启动日志里打印的地址不是真实地址，请按运行服务的电脑的局域网 IP 确定。

配置要点

  • 把配置写在 data/.config.yaml，它的优先级高于 xiaozhi-server 目录下的 config.yaml；先用最小配置跑通，再逐项替换模块；
  • 其中至少要写上设备可访问的 WebSocket 地址：
server:
  websocket: ws://<你的局域网 IP>:8000/xiaozhi/v1/
  • 默认的大模型需要先到对应平台注册并填写 API 密钥才能启动；
  • 默认的语音识别模型 SenseVoiceSmall 体积较大，需要单独下载 model.pt，放到 models/SenseVoiceSmall/ 目录。

让设备连上

  1. 用浏览器打开 OTA 地址。全模块部署时应显示「OTA接口运行正常」；如果显示不正常，用超级管理员登录智控台，在「参数管理」里把 server.websocket 设为你的 WebSocket 地址，再刷新确认。
  2. 让设备进入配网模式（见首次启动），在配网页「高级」选项卡填写 OTA 地址，保存并重启设备。
  3. 唤醒设备，查看服务端日志是否有对话记录。

常见情况

  • Wi-Fi 能连，4G 连不上：该项目 FAQ 的解释是 4G 模式需要安全连接，解决办法包括用 nginx 配置 SSL 证书，详见其 FAQ。
  • 服务端部署问题：先查该项目的 部署文档（最简化）与 全模块部署文档，再到其 Issues 反馈。
  • 固件与设备问题：见常见问题和网络配置。

五、安全警示

xiaozhi-esp32-server 的 README 在「警告」中写明：

  1. 本项目为开源软件，与对接的任何第三方 API 服务商（语音识别、大模型、语音合成等）不存在商业合作关系，不为其服务质量及资金安全提供任何形式的担保；建议优先选择持有相关业务牌照的服务商，并仔细阅读其服务协议及隐私政策；本软件不托管任何账户密钥、不参与资金流转。
  2. 本项目功能未完善，且未通过网络安全测评，请勿在生产环境中使用；如果在公网环境中部署学习，请务必做好必要的防护。

结合固件行为，再补充几条通用做法：

  • 只填写信任的 OTA 地址：设备会把设备标识发给它，并按它的响应切换通信配置。
  • API 密钥只放在服务端配置里：不要提交到公开仓库，也不要写进截图或日志分享。
  • 公网访问使用 TLS：局域网内使用 ws:// 和明文 HTTP 即可；放到公网时改用 wss:// 和 HTTPS，并限制可访问的来源。

相关文档

对照来源：固件 78/xiaozhi-esp32 v2.5.2 的 main/ota.cc、main/Kconfig.projbuild；第三方项目的内容取自各仓库 README 与文档，核对日期 2026-10-23。

网络配置说明功能使用教程