自前サーバー：小智デバイスを自分のサーバーに接続する

小智デバイス自体は大規模言語モデルを動かしません。デバイスは音声の収録と再生を担当し、対話の処理はサーバーが担当します。ファームウェアは既定で公式サーバーに接続します。言語モデル、音声認識、音声合成を自分で選びたい場合や、対話データの保管場所を自分で決めたい場合は、自前のサーバーを動かせます。

このページは概要だけを扱います。デバイスとサーバーがどう組み合わさるか、コミュニティがどのようなオープンソースサーバーを提供しているか、そして xiaozhi-esp32-server を例にデバイスを接続する方法を説明します。サードパーティプロジェクトの完全なチュートリアルは転載しません。具体的な手順は、選んだプロジェクトのドキュメントに従ってください。

自前サーバーは上級者向けのテーマです。コミュニティ製サーバーは独立したサードパーティのプロジェクトで、本サイトにも上流のファームウェアリポジトリにも属しません。本サイトはサーバーを提供せず、サードパーティのプロジェクトを保証するものでもありません。サーバーをインターネットに公開する前に、末尾の「セキュリティ上の警告」を読んでください。

1. 自前サーバーは必要か

お使いの状況	おすすめ
すぐ使える音声アシスタントがほしいだけ	既定の公式サーバーを使う。初回起動を参照
好きな言語モデル、音声認識、音声合成のモデルを使いたい	自前サーバーを動かす
対話データの保管場所を自分で決めたい、または独自のデバイス制御やナレッジベースを加えたい	自前サーバーを動かす
ファームウェアの通信プロトコルを開発・デバッグしている	自前サーバーを動かす、または WebSocket プロトコルに沿って自分で実装する

2. デバイスはどうやってサーバーを見つけるか

ネットワークに接続すると、ファームウェアは OTA URL にリクエストを送ります。サーバーは、対話に使う websocket または mqtt の設定を返し、デバイスはそれをもとに通信プロトコルを初期化します（フィールドの説明は初回起動にあります）。したがって、サーバーには少なくとも次の 2 つの部分が必要です。

OTA エンドポイント：バージョン、アクティベーション情報、通信設定を返します。
対話チャネル：WebSocket または MQTT + UDP。ここで音声認識、言語モデルとの対話、音声合成を行います。

デバイスに自分の OTA URL を使わせる方法は 2 つあります。

設定ページの「詳細設定」タブ：設定モードで OTA URL を入力して保存します。再ビルドは不要です。
自分でビルドする：menuconfig の Default OTA URL（CONFIG_OTA_URL）を変更します。

デバイスは OTA URL へのリクエストのたびに、Device-Id（MAC アドレス）や Client-Id などの識別子を送ります。信頼できるサーバーだけを入力してください。

3. コミュニティ製オープンソースサーバー

この表は、上流ファームウェアの 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	管理バックエンドと対話サービスが 2 つのプロセスで動く。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 デプロイあり

クライアント、組み込みへの移植、その他のプロジェクトはエコシステムプロジェクトを参照してください。

4. 例：xiaozhi-esp32-server

以下の内容は、このプロジェクトの v0.9.7 タグの README と docs/ に基づきます。新しいバージョンについては、main ブランチのドキュメントを基準にしてください。

デプロイ方式

方式	含まれるもの	向いている用途
最小インストール	インテリジェントな対話、単一のエージェント。設定はファイルに置き、データベースは不要。Docker またはソースから実行	低スペックの環境、まず動かしたいとき
フルモジュールインストール	インテリジェントな対話、複数のユーザーとエージェント、管理コンソール。データはデータベースに保存	完全な体験

既定のアドレスとポート

最小インストールの既定のエンドポイントは次のとおりです。

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

デバイスがこのアドレスに到達できる必要があるため、localhost や 127.0.0.1 は使えません。Docker でデプロイした場合、起動ログに出力されるアドレスは実際のものではありません。サービスを動かしているコンピューターの LAN の IP から判断してください。

設定のポイント

設定は data/.config.yaml に書きます。これは xiaozhi-server ディレクトリの config.yaml より優先されます。まず最小限の設定で動かし、そのあとモジュールを 1 つずつ置き換えてください。
最低限、デバイスから到達できる WebSocket アドレスが必要です。

server:
  websocket: ws://<your LAN IP>:8000/xiaozhi/v1/

既定の言語モデルは、対応するプラットフォームのアカウントと API キーがないと起動できません。
既定の音声認識モデル SenseVoiceSmall は大きく、model.pt を別途ダウンロードして models/SenseVoiceSmall/ に置く必要があります。

デバイスの接続

ブラウザで OTA URL を開きます。フルモジュールのデプロイでは「OTA接口运行正常」（OTA エンドポイントは正常に動作しています）と表示されるはずです。表示されない場合は、スーパー管理者としてコンソールにログインし、「参数管理」（パラメータ管理）で server.websocket を自分の WebSocket アドレスに設定し、再読み込みして確認します。
デバイスを設定モードにし（初回起動を参照）、設定ページの「詳細設定」タブに OTA URL を入力して保存し、デバイスを再起動します。
デバイスをウェイクして、サーバーのログに対話の記録が出ているか確認します。

よくある状況

Wi-Fi では動くが 4G では動かない：プロジェクトの FAQ によると、4G モードにはセキュアな接続が必要です。対処の 1 つは nginx で SSL 証明書を設定することです。その FAQ を参照してください。
サーバーのデプロイで問題が出る：まずプロジェクトのデプロイガイド（最小構成）とフルモジュールのデプロイガイドを確認し、そのうえでプロジェクトの Issues に報告してください。
ファームウェアやデバイスの問題：よくある質問とネットワーク設定を参照してください。

5. セキュリティ上の警告

xiaozhi-esp32-server の README は、「Warning」の節で次のように述べています。

これはオープンソースソフトウェアです。接続先のサードパーティ API プロバイダー（音声認識、言語モデル、音声合成など）とは商業的な関係がなく、そのサービス品質や資金の安全性も保証しません。関連する事業のライセンスを持つプロバイダーを優先し、その利用規約とプライバシーポリシーを読んでください。このソフトウェアはアカウントのキーを保持せず、資金の流れにも関与しません。
このプロジェクトは未完成で、ネットワークセキュリティの評価を受けていません。本番環境では使わないでください。学習のためにインターネットに公開する場合は、必要な防御策を講じてください。

ファームウェアの動作に基づく、一般的な心得をいくつか挙げます。

信頼できる OTA URL だけを入力する：デバイスは自分の識別子をそこへ送り、そのレスポンスに従って通信設定を切り替えます。
API キーはサーバーの設定にだけ置く：公開リポジトリにコミットしたり、スクリーンショットやログで共有したりしないでください。
インターネットでは TLS を使う：LAN 内なら ws:// と平文の HTTP で構いません。インターネットに出すときは wss:// と HTTPS を使い、サーバーに到達できる相手を制限してください。