ESP32-S3 小智 AI 音箱 · 用户配置指南

这份指南只讲一件事：固件烧录完成后，第一次开机你要准备并填写哪些东西。
所有配置都在板子开机后弹出的 Web 配置页 里完成，不需要改代码、不需要重新编译。

🚀 小白最快上手（3 步，不用懂代码）

1. 手机/电脑连上板子发出的 Xiaozhi-Speaker WiFi → 浏览器打开 192.168.4.1。
2. 准备三样东西填进去（下面第 3 章一步步教你怎么免费申请）：
   • 你家 WiFi 密码
   • DeepSeek 的 API Key（大模型"大脑"）
   • 百度语音的 Key + Secret（让音箱能"听"和"念"）
3. 点「保存并重启」，对着音箱说话，它就会回答你、还会念出来。
   照着第 2、3、5 章填完即可；第 4 章的 Hermes 进阶版先不用看，等玩熟了再折腾。

0. 这份指南是给谁的

ESP32-S3 固件首次启动后，必须联网并填入 3 类凭据，音箱才能听你说话、调用大模型、把回复念出来。

• 如果你是拿到一块已烧好固件的板子、想让它跑起来 → 看本指南。
• 如果你是要编译 / 烧录固件 → 那是开发流程，本指南不涉及。

1. 你要准备的三样东西

"大脑"有两种方案，按自己情况选：

• 基础版（推荐新手）：直接用 DeepSeek 云端 API。简单、稳定、无需额外设备常开。
• 进阶版（Hermes）：在你自己的 电脑 上跑 Hermes Agent 网关，音箱把请求发给它。好处是可接工具调用 / 记忆 / 技能、可随时换模型、还能接本地 Ollama 离线跑；代价是那台电脑必须一直开机。

👉 小白建议：先把「基础版（DeepSeek）」跑通——它最简单、最稳，免费额度足够个人玩。Hermes 进阶版要你电脑一直开着，等熟悉了再试也不迟。

2. 第一次开机：连上配置页

1. 给板子供电，0.91" OLED 屏会显示提示文字。
2. 未配网时，板子会自动发出一个临时 WiFi（热点，无密码），名称是 Xiaozhi-Speaker——这就相当于板子的"配置入口"，连上它才能打开配置页。
3. 用手机或电脑连接这个 Xiaozhi-Speaker 热点。
4. 打开浏览器访问 http://192.168.4.1，即可看到「ESP32-S3 智能音箱」配置页。
   • 页面有四张卡片：WiFi 配置 / DeepSeek API / 百度语音 API / 固件更新。
5. 想强制重进配网模式：长按板子上标着 BOOT 的小按钮（通常在板子侧面，一颗小黑按键）不放，再上电，几秒后松开（已配过网、想改配置时也用这个办法重新进入热点）。

配网页是板子当 AP 时的地址，固定为 192.168.4.1；连上自己的 WiFi 后板子会变成普通上网设备，此时不再提供该页面。

💡 WiFi 扫描：配置页的 WiFi 名称输入框旁边有个「扫描」按钮，点击后会自动列出附近的 WiFi 热点（显示信号强度和加密标志 🔒），点击即可自动填入，不用手动输入名称。

3. 基础版：填 DeepSeek + 百度

3.1 DeepSeek API（大模型大脑）

1. 打开 https://platform.deepseek.com/ ，注册登录。
2. 进入 API Keys 页面 → 创建 API Key → 复制保存（API Key 就是一串只有你能用的"密码"，音箱靠它调用大模型；它只显示这一次，复制存好，丢了只能重新生成）。
3. 在配置页的 DeepSeek API 卡片填写：
   • API Key：sk-xxxx（填你自己的）
   • Base URL：https://api.deepseek.com/v1（就是"地址"，页面已默认填好，小白直接别动它）
   • Model：deepseek-chat（默认，推荐）或 deepseek-reasoner（推理模型，更慢但更强）
4. 填好以上三项即可对话。到这步音箱就已经有"大脑"了，对着它说句话试试，它会回答你——如果没反应，先往下把百度语音也填好（音箱还要靠它"听"和"念"）。

3.2 百度语音（ASR + TTS）

1. 打开 https://console.bce.baidu.com/ai/ ，登录百度账号。
2. 进入「语音技术」→「创建应用」，勾选 语音识别（短语音/一句话识别） + 语音合成（在线合成）。
3. 创建后得到 API Key 和 Secret Key —— 这俩就是页面里要填的（就是百度给你的一对"账号 + 密码"，缺一不可）。
4. 在配置页的 百度语音 API 卡片填写：
   • API Key：百度应用的 API Key
   • Secret Key：百度应用的 Secret Key
5. 固件会用这对 Key 自动去百度换一个 access_token（相当于"临时通行证"，板子自己搞定，你不用管它），它负责：
   • ASR：把你对着音箱说的话转成文字；
   • TTS：把大模型的文字回复合成成语音播放。
6. 注意：免费额度对个人体验足够；若报鉴权/配额错误，回去核对应用是否勾选了「语音识别」和「语音合成」权限。

4. 进阶版：用 Hermes 代替 DeepSeek

🧭 小白看这里：这一章是"进阶玩法"，先不用看。用第 3 章的 DeepSeek 基础版，音箱已经能正常对话了。等你想让音箱更聪明、更个性化，再回来折腾 Hermes 也不迟。

核心思路：Hermes 在你电脑上开一个 OpenAI 兼容的 API 网关（网关 = 中转站，负责把音箱的请求转给你电脑上的模型），你只需在音箱配置页的「DeepSeek API」卡片里，把地址和 Key 指向它即可——固件代码无需改动。

⚡ Hermes 不是"一次成型"的大脑，而是可以"养"大的：它支持设定人格、挂载记忆与技能、随时切换更强/更省钱的底层模型——也就是说，经过调教它会持续进步，越用越懂你的习惯。这是选进阶版相对固定云端 API 最大的意义。

4.1 在电脑上安装并启动 Hermes

方式一：桌面应用（推荐新手）

直接下载安装，无需命令行：

下载后双击安装，打开 Hermes 桌面应用。

方式二：命令行安装

# macOS / Linux
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
source ~/.bashrc          # 或 source ~/.zshrc

# Windows (PowerShell)
irm https://hermes-agent.nousresearch.com/install.ps1 | iex

配置 API Server

安装完成后，需要开启 API Server 让音箱能连上：

1. 选择 LLM 模型（命令行方式需此步，桌面应用在设置界面里选）：

   hermes model              # 交互式选择 LLM 提供商/模型（DeepSeek、OpenRouter、Ollama 等）
   

2. 编辑 hermes/.env 文件，开启 API Server：

   # Hermes API Server (OpenAI-compatible)
   API_SERVER_HOST=0.0.0.0          # 允许局域网访问（默认 127.0.0.1 仅本机）
   API_SERVER_KEY=your-secret-key   # 自定义密钥，音箱端要填一样的
   

   端口默认 8642，如需修改在 .env 中设置 API_SERVER_PORT。

3. 启动网关：

   hermes gateway
   

   桌面应用在界面中点击「启动 Gateway」即可。

4. 验证是否正常工作：

   curl http://127.0.0.1:8642/health
   # 期望：{"status":"ok","platform":"hermes-agent"}
   
   curl -H "Authorization: Bearer your-secret-key" http://127.0.0.1:8642/v1/models
   # 期望：{"object":"list","data":[{"id":"hermes-agent", ...}]}
   

⚠️ 关键一步：API_SERVER_HOST 必须设成 0.0.0.0。白话解释：默认 127.0.0.1 意思是"只允许这台电脑自己连"，那音箱（另一台设备）就进不来；改成 0.0.0.0 表示"允许家里其他设备连进来"。改完记得重启 gateway 才生效。

记下这台电脑的局域网 IP（如 192.168.1.50），下一步要用。

🖥️ 怎么查自己电脑的局域网 IP？

• Windows：按 Win+R 输入 cmd 回车，在黑框里输 ipconfig，找「IPv4 地址」那一行（一般是 192.168.x.x）。
• macOS：打开「终端」（启动台搜"终端"），输入 ifconfig | grep inet，找 192.168.x.x 那个。
  记下它；如果家里路由器重启过，这个号码可能变，连不上时回来重新查一下。

4.2 在配置页把"大脑"指向 Hermes

回到音箱配置页的 DeepSeek API 卡片，填：

• API Key：上面设的 API_SERVER_KEY（即 your-secret-key）
• Base URL：http://<电脑局域网IP>:8642/v1
  • 例：http://192.168.1.50:8642/v1
• Model：hermes-agent

注意 Base URL 是 http（不是 https）。Hermes 网关在局域网内运行，用明文即可。
端口默认 8642，如果你改过就用改后的端口。

4.3 进阶注意事项

• 那台跑 Hermes 的电脑必须一直开着，否则音箱会"没有大脑"。
• 想让回复更短更口语化：在 Hermes 侧设置 personality（就是给它定个"人设 / 说话风格"），例如：
  你是一个智能音箱，请用 40 字以内的简短口语化中文回答。
• 想换底层模型：直接 hermes model 一键切换，音箱端无需改动。
• Hermes 挂了可随时回退：把配置页 DeepSeek 卡片改回 DeepSeek 官方地址和 Key 即可。

5. 保存并生效

1. WiFi、DeepSeek、百度三张卡片都填好后，点页面底部的 「保存并重启」。
2. 板子保存配置并重启，随后自动用你填的 WiFi 联网、用你选的"大脑"对话。
3. 之后想改配置：长按 BOOT 键开机 → 重新进入 Xiaozhi-Speaker 热点 → 打开 http://192.168.4.1 重新填即可。

6. 固件更新（OTA）

配网页面底部有一张 「固件更新 (OTA)」 卡片，可以在不接电脑、不用烧录工具的情况下升级音箱固件。

6.1 操作步骤

1. 长按 BOOT 键开机，进入配网模式。
2. 电脑连上 Xiaozhi-Speaker 热点，打开 http://192.168.4.1。
3. 滚动到页面底部的「固件更新 (OTA)」区域。
4. 点击文件选择框，选中新的固件文件（.bin 后缀）。
5. 点击「上传固件并重启」，页面会显示实时上传进度。
6. 上传完成后，音箱自动重启并运行新固件。

6.2 注意事项

• 固件文件必须是 .bin 格式，从开发者处获取或自行编译生成。
• 上传过程中不要关闭浏览器或断开热点连接。
• 如果上传后无法启动，长按 BOOT 键重进配网模式，重新上传即可恢复。

7. 故障排查

📖 名词小抄（看不懂的词点这里）

祝你把小智音箱跑起来，玩得开心 🎉