XiaoZhi AI Chatbot Documentation Center | XiaoZhi.Dev
Usage Guide
Self-Hosted Server: Connect XiaoZhi Devices to Your Own Server

Self-Hosted Server: Connect XiaoZhi Devices to Your Own Server

A XiaoZhi device does not run a large language model itself: the device captures and plays audio, and the server handles the conversation. The firmware connects to the official server by default. If you want to choose your own language model, speech recognition and speech synthesis, or decide where conversation data is kept, you can run your own server.

This page is an overview only. It explains how the device and the server fit together, which open-source servers the community offers, and, using xiaozhi-esp32-server as an example, how to connect a device. It does not copy the full tutorials of third-party projects; follow the documentation of the project you choose for the exact steps.

Self-hosting is an advanced topic. Community servers are independent third-party projects. They do not belong to this site or to the upstream firmware repository, and this site does not provide a server or vouch for third-party projects. Read the “Security Warnings” at the end before exposing a server to the internet.

1. Do You Need Your Own Server?

Your situationSuggestion
You just want a ready-made voice assistantUse the default official server, see First Boot
You want to use language, speech recognition and speech synthesis models of your choiceSelf-host a server
You want to decide where conversation data is stored, or add your own device control and knowledge baseSelf-host a server
You are developing or debugging the firmware communication protocolSelf-host a server, or implement one against the WebSocket protocol

2. How the Device Finds Your Server

After connecting to the network, the firmware sends a request to the OTA URL. The server answers with the websocket or mqtt configuration to use for conversations, and the device initializes its communication protocol from it (field descriptions are in First Boot). So a server must provide at least two parts:

  1. An OTA endpoint: returns the version, activation information and communication configuration;
  2. A conversation channel: WebSocket or MQTT + UDP, on which it does speech recognition, language model conversation and speech synthesis.

There are two ways to make a device use your OTA URL:

  • The “Advanced” tab of the provisioning page: enter the OTA URL in provisioning mode and save it; no rebuild is needed;
  • Build it yourself: change Default OTA URL (CONFIG_OTA_URL) in menuconfig.

The device sends identifiers such as Device-Id (the MAC address) and Client-Id with every request to the OTA URL, so only enter a server you trust.

3. Community Open-Source Servers

The table comes from the “related open-source projects” in the upstream firmware README, and the repository status and license of each entry were checked (2026-10-23). Contents, features and licenses change, so rely on the current state of the repository.

ProjectStackLicenseSummary
xinnan-tech/xiaozhi-esp32-serverPython + Java + VueMITSupports MQTT + UDP, WebSocket, MCP endpoints, voiceprint recognition and a knowledge base; offers minimal and full-module deployment
joey-zhou/xiaozhi-esp32-server-javaJava (Spring Boot)MITAdmin backend and conversation service run as two processes; the README stack depends on MySQL, Redis and Qdrant
AnimeAIChat/xiaozhi-server-goGoModified Apache 2.0 with extra conditionsAimed at personal and home use, talks over WebSocket, stores configuration in local SQLite; the extra conditions include no multi-tenant use without written permission, so read its LICENSE first
hackers365/xiaozhi-esp32-server-golangGoMITFully streaming ASR → LLM → TTS, supports WebSocket and MQTT + UDP, with a prebuilt one-click bundle and Docker deployment

For clients, embedded ports and other projects, see Ecosystem Projects.

4. Example: xiaozhi-esp32-server

The facts below come from the README and docs/ of the v0.9.7 tag of that project. For newer versions, rely on the main branch documentation.

Deployment Modes

ModeWhat it includesSuited for
Minimal installIntelligent conversation, a single agent; configuration lives in a file and no database is needed; runs with Docker or from sourceLow-spec environments, getting it running first
Full-module installIntelligent conversation, multiple users and agents, with a management console; data is kept in a databaseThe complete experience

Default Addresses and Ports

The default endpoints of the minimal install are:

  • WebSocket: ws://<LAN IP>:8000/xiaozhi/v1/
  • OTA: http://<LAN IP>:8003/xiaozhi/ota/

The device must be able to reach this address, so do not use localhost or 127.0.0.1. With a Docker deployment, the address printed in the startup log is not the real one; determine it from the LAN IP of the computer running the service.

Configuration Notes

  • Put your configuration in data/.config.yaml, which takes precedence over config.yaml in the xiaozhi-server directory; get a minimal configuration running first, then replace modules one by one;
  • It needs at least a WebSocket address the device can reach:
server:
  websocket: ws://<your LAN IP>:8000/xiaozhi/v1/
  • The default language model needs an account on the matching platform and an API key before it can start;
  • The default speech recognition model SenseVoiceSmall is large and must be downloaded separately as model.pt, then placed in models/SenseVoiceSmall/.

Connecting the Device

  1. Open the OTA URL in a browser. In a full-module deployment it should show “OTA接口运行正常” (the OTA endpoint is working); if it does not, log in to the console as super administrator, set server.websocket to your WebSocket address under “Parameter Management” (参数管理), and refresh to confirm.
  2. Put the device into provisioning mode (see First Boot), enter the OTA URL in the “Advanced” tab of the provisioning page, save it and restart the device.
  3. Wake the device and check whether the server log shows conversation records.

Common Situations

  • Wi-Fi works but 4G does not: the project’s FAQ explains that 4G mode needs a secure connection; one fix is to configure an SSL certificate with nginx, see its FAQ.
  • Server deployment problems: start with the project’s deployment guide (minimal) and full-module deployment guide, then report to its Issues.
  • Firmware and device problems: see the FAQ and Network Configuration.

5. Security Warnings

The README of xiaozhi-esp32-server states in its “Warning” section:

  1. This is open-source software. It has no commercial relationship with any third-party API provider it connects to (speech recognition, language models, speech synthesis and so on) and gives no guarantee of their service quality or the safety of your funds. Prefer providers that hold the relevant business licenses and read their terms and privacy policies. The software does not hold account keys and takes no part in money flows.
  2. The project is incomplete and has not passed a network security assessment. Do not use it in production. If you deploy it on the public internet for learning, put the necessary protection in place.

Based on how the firmware behaves, a few more general practices:

  • Only enter an OTA URL you trust: the device sends its identifiers to it and switches its communication configuration according to its response.
  • Keep API keys in the server configuration only: do not commit them to public repositories or share them in screenshots or logs.
  • Use TLS on the internet: ws:// and plain HTTP are fine inside a LAN; on the internet use wss:// and HTTPS and restrict who can reach the server.

Related Documents

Sources: main/ota.cc and main/Kconfig.projbuild of the firmware 78/xiaozhi-esp32 v2.5.2; third-party content comes from each repository’s README and docs, checked on 2026-10-23.

Network Configuration GuideFeature Usage Tutorial