首次啟動：配網、啟用與綁定

小智裝置第一次通電後，依序完成三件事：連上 Wi‑Fi、向伺服器報到並檢查版本、用啟用碼綁定到你的帳號。本頁依韌體 v2.5.2 的實際程式碼，說明每一步裝置在做什麼、你會看到什麼，以及卡住時怎麼處理。

流程總覽

1. 上電後，裝置檢查是否儲存過 Wi‑Fi：沒有就進入配網模式；有則嘗試連線，60 秒內沒連上同樣回到配網模式。
2. 連線後裝置進入「啟用設備」狀態，向 OTA 位址請求版本資訊。
3. 伺服器回傳新韌體則先升級；回傳啟用碼則顯示並朗讀啟用碼。
4. 你在控制台輸入啟用碼完成綁定。裝置隨後載入通訊設定，進入待機並播放成功提示音。

第一步：配網

什麼時候進入配網模式

• 裝置沒有儲存任何 Wi‑Fi（首次啟動）；
• 已儲存的 Wi‑Fi 在 60 秒內沒有連上；
• 在啟動階段按下開發板上的配網按鍵。按鍵因板而異：例如 bread-compact-wifi 在啟動階段單擊 BOOT 鍵進入配網，其他開發板請查看 main/boards/ 下對應目錄的 README。

熱點配網（預設）

韌體預設使用熱點配網（menuconfig 中 WiFi Configuration Method → Hotspot，預設開啟）。

1. 螢幕和語音提示「網路設定模式」，內容包含熱點名稱與設定網址，例如 Xiaozhi-XXXX 和 192.168.4.1。熱點名稱以 Xiaozhi- 開頭，後接裝置 MAC 位址末兩個位元組，以螢幕顯示為準。
2. 手機連上該熱點，在瀏覽器中開啟 192.168.4.1。熱點是開放網路，沒有密碼，最多同時連接 4 台裝置，請在可信環境中盡快完成配網。
3. 在配網頁選擇路由器並輸入密碼。多數晶片只支援 2.4 GHz；ESP32-C5 另支援 5 GHz。
4. 儲存後裝置離開配網模式，並用新的 Wi‑Fi 憑證重新連線。

配網頁的「進階」分頁提供 OTA 位址、Wi‑Fi 發射功率和 Wi‑Fi 休眠模式（OTA 位址與休眠兩項由韌體決定是否顯示，v2.5.2 均已顯示）。在這裡填寫的 OTA 位址會取代預設值，裝置此後向該位址請求版本與啟用資訊，請只填寫你信任的伺服器。

BluFi 配網

BluFi 在建置韌體時選擇，不能與熱點配網同時啟用。啟用後裝置的藍牙名稱為 Xiaozhi-Blufi，用 EspBlufi 等用戶端傳送 Wi‑Fi 憑證即可。設定方法見 BluFi 配網指南。

第二步：檢查版本

連線後，韌體向 OTA 位址發出請求。位址取自配網頁的設定，沒有設定時使用 menuconfig 中 Default OTA URL（CONFIG_OTA_URL）的值。請求標頭帶有裝置識別：Device-Id（MAC 位址）、Client-Id（裝置 UUID）、Activation-Version、User-Agent、Accept-Language；讀到有效 eFuse 序號的裝置還會帶上 Serial-Number。

伺服器回傳的 JSON 可以包含：

沒有 activation 欄位時，裝置視為無需啟用，直接繼續啟動。

第三步：啟用與綁定

1. 回應帶有啟用碼時，裝置在螢幕上顯示伺服器給出的提示文字，播放提示音，再逐位朗讀啟用碼中的數字。
2. 登入官方控制台，依頁面指引輸入啟用碼，把裝置綁定到你的帳號。
3. 在你操作期間，裝置持續向 <OTA 位址>/activate 提交回應：讀到 eFuse 序號的裝置提交 hmac-sha256 結果（用 eFuse 中的 HMAC 金鑰對 challenge 簽章），其他裝置提交空物件。伺服器回傳 200 表示啟用成功，回傳 202 表示還沒綁定（裝置等 3 秒再試），其他狀態則等 10 秒再試。
4. 一輪最多嘗試 10 次；仍未完成時裝置回到「檢查版本」再來一輪，請以螢幕上最新顯示的啟用碼為準。
5. 啟用成功後，裝置依伺服器下發的設定初始化通訊協定（回應中沒有任何協定設定時預設使用 MQTT），顯示版本號並播放成功提示音，隨後即可開始對話。

常見問題排查

相關閱讀

• 韌體下載與燒錄
• 網路設定說明
• 常見問題
• BluFi 配網指南

來源：78/xiaozhi-esp32 v2.5.2 的 wifi_board.cc、ota.cc、application.cc、Kconfig.projbuild，以及配網元件 78/esp-wifi-connect 的 README。