自建服務端：讓小智裝置連線你自己的伺服器
小智裝置本身不執行大模型：裝置負責採集和播放音訊，對話由服務端完成。韌體預設連線官方伺服器；如果你想自己選擇大模型、語音識別與語音合成，或者自己決定對話資料放在哪裡，可以自建服務端。
本頁只做概覽：講清裝置與服務端怎麼銜接、社群有哪些開源服務端，並以 xiaozhi-esp32-server 為例說明接入步驟。第三方專案的完整教程不在這裡搬運，具體步驟以所選專案的文件為準。
一、先判斷是否需要自建
| 你的情況 | 建議 |
|---|---|
| 只想用現成的語音助手 | 使用預設的官方伺服器，流程見首次啟動 |
| 想接入自己選擇的大模型、語音識別和語音合成 | 自建服務端 |
| 想自己決定對話資料的儲存位置，或加入自己的裝置控制與知識庫 | 自建服務端 |
| 開發或除錯韌體的通訊協議 | 自建服務端，或對照WebSocket 協議自行實現 |
二、裝置如何找到你的伺服器
韌體聯網後向 OTA 位址發起請求，伺服器在回應裡下發後續對話使用的 websocket 或 mqtt 配置，裝置按這份配置初始化通訊協議（欄位說明見首次啟動）。因此一個服務端至少要提供兩部分：
- OTA 介面：回傳版本、啟用資訊和通訊配置；
- 對話通道：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-server | Python + Java + Vue | MIT | 支援 MQTT + UDP、WebSocket、MCP 接入點、聲紋識別、知識庫；提供最簡化與全模組兩種部署方式 |
| joey-zhou/xiaozhi-esp32-server-java | Java（Spring Boot） | MIT | 管理後台與對話服務分為兩個行程；README 技術堆疊依賴 MySQL、Redis 和 Qdrant |
| AnimeAIChat/xiaozhi-server-go | Go | 修改版 Apache 2.0，含附加條件 | 面向個人和家庭場景，透過 WebSocket 通訊，本地 SQLite 儲存配置；附加條件包括未經書面授權不得用於多租戶，請先閱讀其 LICENSE |
| hackers365/xiaozhi-esp32-server-golang | Go | MIT | 全流式 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/目錄。
讓裝置連上
- 用瀏覽器開啟 OTA 位址。全模組部署時應顯示「OTA接口运行正常」；如果顯示不正常，用超級管理員登入智控台，在「參數管理」裡把
server.websocket設為你的 WebSocket 位址，再重新整理確認。 - 讓裝置進入配網模式（見首次啟動），在配網頁「進階」分頁填寫 OTA 位址，儲存並重啟裝置。
- 喚醒裝置，檢視服務端日誌是否有對話記錄。
常見情況
- Wi-Fi 能連，4G 連不上：該專案 FAQ 的解釋是 4G 模式需要安全連線，解決辦法包括用 nginx 配置 SSL 證書，詳見其 FAQ。
- 服務端部署問題：先查該專案的 部署文件（最簡化）與 全模組部署文件，再到其 Issues 反饋。
- 韌體與裝置問題：見常見問題和網路配置。
五、安全警示
xiaozhi-esp32-server 的 README 在「警告」中寫明：
- 本專案為開源軟體，與對接的任何第三方 API 服務商（語音識別、大模型、語音合成等）不存在商業合作關係，不為其服務品質及資金安全提供任何形式的擔保；建議優先選擇持有相關業務牌照的服務商，並仔細閱讀其服務協議及隱私政策；本軟體不託管任何賬戶金鑰、不參與資金流轉。
- 本專案功能未完善，且未透過網路安全測評，請勿在生產環境中使用；如果在公網環境中部署學習，請務必做好必要的防護。
結合韌體行為，再補充幾條通用做法：
- 只填寫信任的 OTA 位址：裝置會把裝置標識發給它，並按它的回應切換通訊配置。
- API 金鑰只放在服務端配置裡：不要提交到公開儲存庫，也不要寫進截圖或日誌分享。
- 公網訪問使用 TLS：區域網內使用
ws://和明文 HTTP 即可；放到公網時改用wss://和 HTTPS，並限制可訪問的來源。
相關文檔
- 首次啟動：配網、啟用與綁定：裝置如何向 OTA 位址報到
- WebSocket 通訊協議、MQTT + UDP 混合協議、MCP 協議：服務端需要實現的協議
- 生態專案：服務端、客戶端與移植方案
- 常見問題
對照來源：韌體 78/xiaozhi-esp32 v2.5.2 的 main/ota.cc、main/Kconfig.projbuild；第三方專案的內容取自各儲存庫 README 與文件，核對日期 2026-10-23。