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

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

0. 这份指南是给谁的

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

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

1. 你要准备的三样东西

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

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

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

1. 给板子供电，0.91" OLED 屏会显示提示文字。
2. 未配网时，板子会自动开启一个开放热点（无密码），名称为 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 → 复制保存（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

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

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（全 0 = 监听所有网卡）。默认 127.0.0.1 只允许本机访问，音箱会连不上。改完后重启 gateway 生效。

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

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. 故障排查

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