给小智AI换个「自家大脑」:Stick S3 接入自建服务端与 Hermes Agent 实战

给小智AI换个「自家大脑」:Stick S3 接入自建服务端与 Hermes Agent 实战

最近入手了一个好玩的玩具——M5Stack 的 Stick S3,一颗小小的 ESP32-S3 语音盒子:带麦克风、喇叭、屏幕,喊一声「你好小智」就能对话。开箱烧录官方固件后十分钟就能聊起来,体验相当惊喜。

但聊了几天之后,技术人的老毛病犯了:它的大脑在别人家。官方方案里,语音识别、大模型、语音合成全跑在 xiaozhi.me 的云端,我能定制的只有音色和开场白。作为一个天天折腾私有化部署的人,这怎么能忍。

于是有了这篇:把小智的后端搬到自己家里,再把大脑换成我自己的 AI Agent。现在我对着它喊一嗓子「帮我看看电脑还剩多少存储空间」,它是真的会去执行命令然后把结果念给我听。

整体架构长这样:

00-架构

本文会覆盖两条路线:

  • 玩法 A(人人可玩):官方云开箱流程,十分钟上手
  • 玩法 B(进阶折腾):自建后端 xiaozhi-esp32-server + 自选大脑(接任何 OpenAI 兼容的 LLM,我接的是自己部署的 Hermes Agent)

以及一份真实的踩坑实录——包括那个让我查了半天的 code=113。


一、原理:三层架构,大脑是可替换的

小智生态(开源项目 xiaozhi-esp32)把整个语音助手拆成了三层:

1
2
3
4
5
6
7
你说话 → [小智硬件]        只有耳朵(麦克风)、嘴(喇叭)、唤醒词
│ 小智私有协议(WebSocket + Opus 音频流)
▼
[后端服务] 听写(ASR)→ 把文字交给大脑 → 把回答念出来(TTS)
│ OpenAI 兼容接口
▼
[大模型大脑] 真正思考的部分:官方用 Qwen,你可以换成任何东西

关键洞察是:硬件和后端之间是小智协议,后端和大脑之间是标准 OpenAI 兼容 API。开源社区(xinnan-tech/xiaozhi-esp32-server)已经把中间那层后端完整实现了——ASR/TTS 本地跑,大脑随便接。

做过集成的朋友可以这么理解:小智硬件是 Fiori 前端,自建后端是中间件,大脑就是后端业务系统。中间件不换,业务系统随便换。


二、玩法 A:官方云开箱(建议先走这步)

不管后面折腾什么,先花十分钟验证硬件是好的,别把硬件问题和部署问题搅在一起。

2.1 烧录固件

  1. 官方教程页下载 M5Burner(M5Stack 的烧录工具,免安装解压即用):https://docs.m5stack.com/zh_CN/guide/sticks3/xiaozhi_voice_assistant
  2. Stick S3 用数据线连电脑(纯充电线不行,插上没反应先怀疑线)
  3. 长按机身侧边复位键,看到内部绿色 LED 闪烁即进入下载模式
  4. Burner 左侧选 STICK 分类,找到「StickS3 小智语音助手」固件,Download 后 Burn

02-固件列表

2.2 配网 + 绑定

  1. 烧完重启,设备进入配网模式,手机连接它发出的热点 Xiaozhi-xxxx
  2. 浏览器打开 192.168.4.1,选你家 WiFi(必须 2.4G,5G 搜不到)、输密码
  3. 设备连上后会语音播报「请登录到控制面板添加设备,输入验证码 xxxxxx」
  4. 打开 https://xiaozhi.me 注册登录,添加设备、输验证码,完成

之后「你好小智」唤醒就能聊了。到这里玩法 A 结束,官方绑定留着别删——它是你的备胎,自建服务翻车时随时切回去。


三、玩法 B 第一步:自建后端(xiaozhi-esp32-server)

3.1 准备

  • 一台一直开机的电脑(Windows/Linux 均可,我用的 Windows)或 NAS
  • 安装 Docker + Docker Compose
  • 检查端口 8000 / 8002 / 8003 没被占用

3.2 目录与文件

建一个部署目录,结构如下(文件都从项目仓库拿):

1
2
3
4
5
6
7
xiaozhi-server/
├─ docker-compose_all.yml # 官方全模块 compose
├─ data/
│ └─ .config.yaml # 配置文件(config_from_api.yaml 改名而来)
└─ models/
└─ SenseVoiceSmall/
└─ model.pt # 本地语音识别模型,约 1GB

model.pt 建议从魔搭 ModelScope 下载(国内快):https://modelscope.cn/models/iic/SenseVoiceSmall/resolve/master/model.pt

.config.yaml 里把 manager-api 的地址改成 Docker 容器互联地址:

1
2
3
manager-api:
url: http://xiaozhi-esp32-server-web:8002/xiaozhi # 容器名互联,别写 127.0.0.1
secret: 稍后从智控台拿 # 见下文「三个重要的事」

3.3 安全加固(强烈建议,一行都不省)

官方 compose 默认把端口绑在 0.0.0.0(所有网卡)。全模块里跑着 MySQL(root 默认密码)和管理后台,不要让它们裸奔。我的做法是加一个 docker-compose.override.yml(compose 会自动合并,升级不冲突):

1
2
3
4
5
6
7
8
services:
xiaozhi-esp32-server:
ports: !override
- "192.168.x.99:8000:8000" # 换成你主机的局域网 IP
- "192.168.x.99:8003:8003"
xiaozhi-esp32-server-web:
ports: !override
- "192.168.x.99:8002:8002"

只绑内网网卡、不开公网。MySQL 和 Redis 在 compose 里本来就没映射宿主端口,保持就好。

3.4 启动 + 「三个重要的事」

1
docker compose -f docker-compose_all.yml -f docker-compose.override.yml up -d

等 MySQL 初始化完(首次约 1 分钟),浏览器打开 http://你的IP:8002(智控台):

01-智控台登录

第一个注册的账号自动成为超级管理员,所以部署完尽快注册,别让窗口期开着。

然后按官方文档做三件事:

  1. 参数管理 → 复制 server.secret → 填进 data/.config.yaml 的 manager-api.secret → docker restart xiaozhi-esp32-server(服务端和智控台的握手密钥,没它服务端起不来)
  2. 模型配置 → 大语言模型 → 给默认模型填一个 API key(官方默认智谱 glm-4-flash,免费;本文后面会换成自己的 Agent)
  3. 参数管理 → 配置两个地址(决定设备拿到什么连接信息):
    • server.ota = http://你的IP:8002/xiaozhi/ota/
    • server.websocket = ws://你的IP:8000/xiaozhi/v1/

验证:浏览器打开 http://你的IP:8002/xiaozhi/ota/,显示 OTA 接口运行正常即可。


四、玩法 B 第二步:把大脑换成自己的 Agent

这是我最好感兴奋的一步。智控台 → 模型配置 → 大语言模型,修改默认那行:

  • API 地址:http://你的Agent主机IP:端口/v1(任何 OpenAI 兼容服务都行:DeepSeek、智谱、Ollama 本地模型、自建 Agent……)
  • API 密钥:对应服务的 key
  • 模型名称:对应服务的模型 ID

07-模型配置

我接的是自己部署的 Hermes Agent——一个带技能库、持久记忆和完整工具链(终端/浏览器/文件)的开源 Agent 框架,它自带 OpenAI 兼容 API。接上之后,小智就不再是「问答玩具」,而是能动手干活的语音入口:

「帮我看看 D 盘还剩多少空间」→ 它真的去执行命令 → 把数字念给你听

⚠️ 安全提示(必读):能给 Agent 的 API key = 这个 Agent 的完整权限。语音是随口的、不可控的输入,谁都能对它喊话。所以:

  • 只在内网用,绝对不要映射公网
  • 进阶做法:给语音助手单独建一个权限受限的 Agent 实例(只开查询类工具、禁终端写操作),和主实例隔离

五、玩法 B 第三步:设备切到自家服务

  1. 对设备说「你好小智,进入配网模式」(或重启后按住按键进配网,还是不行就重新执行2.1和2.2)
  2. 电脑连 Xiaozhi-xxxx 热点,浏览器打开 192.168.4.1
  3. 页面顶部展开「高级选项」,把 OTA 地址改成你自己的:
1
http://你的IP:8002/xiaozhi/ota/
  1. 保存,设备重连 WiFi 后会自动向你家 OTA 接口报到,并播报新的验证码
  2. 打开自家智控台(不是 xiaozhi.me!),添加设备、输验证码

06-添加设备

搞定。现在整条链路——耳朵、翻译官、大脑——全在你自己家里。


六、踩坑实录(都是真金白银的时间)

坑 1:code=113,「检查新版本失败,XX秒后重试」循环

症状:设备切了 OTA 地址后一直报 113,屏幕循环「检查新版本失败」。

排查思路(值得分享的方法论):先看服务端日志——设备有没有来敲门?结果发现设备成功拉取过一次 OTA 响应(拿到了 WS 地址),然后就没然后了。服务端无责,问题在设备→服务器的网络路径上。

根因:Windows 防火墙。我的主机网卡被识别为「公用网络」,这个配置档默认丢弃所有入站连接。Docker 发布的端口并不自动获得防火墙放行。

修复(管理员 PowerShell,只对内网网段放行,不裸奔):

1
2
3
4
5
foreach ($p in 8000,8002,8003) {
New-NetFirewallRule -DisplayName "xiaozhi-lan-tcp$p" `
-Direction Inbound -Protocol TCP -LocalPort $p `
-RemoteAddress 192.168.0.0/16 -Action Allow -Profile Any
}

修完设备立刻上线。排查局域网设备连不上时,先 ping/先看服务端日志,最后才怀疑玄学——防火墙是确定性的,但它藏在视线之外。

坑 2:OTA 接口 curl 测试返回 500

新版智控台的 OTA 接口要求请求头带 Device-Id、请求体带 application 字段,缺了就 500。这是给设备用的接口,不是给浏览器用的——用模拟请求测试时要带全:

1
2
3
curl -X POST "http://你的IP:8002/xiaozhi/ota/" \
-H "Content-Type: application/json" -H "Device-Id: aa:bb:cc:dd:ee:ff" \
-d '{"application":{"version":"1.6.1"},"board":{"type":"m5stack-sticks3"}}'

返回里有 websocket.url 和激活码 activation.code 才算通。

坑 3:局域网 IP 会变

DHCP 环境下主机 IP 一变,设备缓存的 OTA 地址就失效。在路由器里给主机做 DHCP 静态绑定,一劳永逸。

坑 4:curl 在 git-bash 下的假象

本机验证端口时,git-bash 的 curl 可能被系统代理劫持,返回 000/exit 52 之类的假故障。加 --noproxy '*' 再测,或者干脆用 netstat -ano | grep LISTEN 看监听状态——判定端口通不通,读状态码,别读退出码。


七、成本清单

项目 花费
Stick S3 硬件 约两百元(M5Stack 官方渠道)
xiaozhi-esp32-server 开源免费,跑在已有电脑/NAS 上
ASR 模型(SenseVoiceSmall) 本地运行,免费
大脑 看你接什么:免费 LLM(智谱 glm-4-flash)零成本;自建 Agent 用已有算力
时间 玩法 A 十分钟;玩法 B 半天(含踩坑)

八、写在最后

这个小盒子目前是我家使用率最高的 AI 入口——做饭时手湿着喊一嗓子查个东西、路过电脑前让它看一眼磁盘、睡前让它定个时。语音交互的价值不在技术多先进,而在它把「打开电脑→打开浏览器→输入」的成本降到了零。

而自建后端的意义在于:我知道我说的每句话存在哪、大脑是谁、什么时候换、怎么换。AI 时代,数据主权和折腾的乐趣,都值得花一个下午。

有问题的朋友欢迎留言交流。下一篇可能写「给语音助手单独建一个权限受限的 Agent 实例」——毕竟现在这个,权限大得我自己都有点慌(笑)。