给小智AI换个「自家大脑」:Stick S3 接入自建服务端与 Hermes Agent 实战
给小智AI换个「自家大脑」:Stick S3 接入自建服务端与 Hermes Agent 实战
最近入手了一个好玩的玩具——M5Stack 的 Stick S3,一颗小小的 ESP32-S3 语音盒子:带麦克风、喇叭、屏幕,喊一声「你好小智」就能对话。开箱烧录官方固件后十分钟就能聊起来,体验相当惊喜。
但聊了几天之后,技术人的老毛病犯了:它的大脑在别人家。官方方案里,语音识别、大模型、语音合成全跑在 xiaozhi.me 的云端,我能定制的只有音色和开场白。作为一个天天折腾私有化部署的人,这怎么能忍。
于是有了这篇:把小智的后端搬到自己家里,再把大脑换成我自己的 AI Agent。现在我对着它喊一嗓子「帮我看看电脑还剩多少存储空间」,它是真的会去执行命令然后把结果念给我听。
整体架构长这样:

本文会覆盖两条路线:
- 玩法 A(人人可玩):官方云开箱流程,十分钟上手
- 玩法 B(进阶折腾):自建后端 xiaozhi-esp32-server + 自选大脑(接任何 OpenAI 兼容的 LLM,我接的是自己部署的 Hermes Agent)
以及一份真实的踩坑实录——包括那个让我查了半天的 code=113。
一、原理:三层架构,大脑是可替换的
小智生态(开源项目 xiaozhi-esp32)把整个语音助手拆成了三层:
1 | 你说话 → [小智硬件] 只有耳朵(麦克风)、嘴(喇叭)、唤醒词 |
关键洞察是:硬件和后端之间是小智协议,后端和大脑之间是标准 OpenAI 兼容 API。开源社区(xinnan-tech/xiaozhi-esp32-server)已经把中间那层后端完整实现了——ASR/TTS 本地跑,大脑随便接。
做过集成的朋友可以这么理解:小智硬件是 Fiori 前端,自建后端是中间件,大脑就是后端业务系统。中间件不换,业务系统随便换。
二、玩法 A:官方云开箱(建议先走这步)
不管后面折腾什么,先花十分钟验证硬件是好的,别把硬件问题和部署问题搅在一起。
2.1 烧录固件
- 官方教程页下载 M5Burner(M5Stack 的烧录工具,免安装解压即用):https://docs.m5stack.com/zh_CN/guide/sticks3/xiaozhi_voice_assistant
- Stick S3 用数据线连电脑(纯充电线不行,插上没反应先怀疑线)
- 长按机身侧边复位键,看到内部绿色 LED 闪烁即进入下载模式
- Burner 左侧选
STICK分类,找到「StickS3 小智语音助手」固件,Download 后 Burn

2.2 配网 + 绑定
- 烧完重启,设备进入配网模式,手机连接它发出的热点
Xiaozhi-xxxx - 浏览器打开
192.168.4.1,选你家 WiFi(必须 2.4G,5G 搜不到)、输密码 - 设备连上后会语音播报「请登录到控制面板添加设备,输入验证码 xxxxxx」
- 打开 https://xiaozhi.me 注册登录,添加设备、输验证码,完成
之后「你好小智」唤醒就能聊了。到这里玩法 A 结束,官方绑定留着别删——它是你的备胎,自建服务翻车时随时切回去。
三、玩法 B 第一步:自建后端(xiaozhi-esp32-server)
3.1 准备
- 一台一直开机的电脑(Windows/Linux 均可,我用的 Windows)或 NAS
- 安装 Docker + Docker Compose
- 检查端口
8000 / 8002 / 8003没被占用
3.2 目录与文件
建一个部署目录,结构如下(文件都从项目仓库拿):
1 | xiaozhi-server/ |
model.pt 建议从魔搭 ModelScope 下载(国内快):https://modelscope.cn/models/iic/SenseVoiceSmall/resolve/master/model.pt
.config.yaml 里把 manager-api 的地址改成 Docker 容器互联地址:
1 | manager-api: |
3.3 安全加固(强烈建议,一行都不省)
官方 compose 默认把端口绑在 0.0.0.0(所有网卡)。全模块里跑着 MySQL(root 默认密码)和管理后台,不要让它们裸奔。我的做法是加一个 docker-compose.override.yml(compose 会自动合并,升级不冲突):
1 | services: |
只绑内网网卡、不开公网。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(智控台):

第一个注册的账号自动成为超级管理员,所以部署完尽快注册,别让窗口期开着。
然后按官方文档做三件事:
- 参数管理 → 复制
server.secret→ 填进data/.config.yaml的manager-api.secret→docker restart xiaozhi-esp32-server(服务端和智控台的握手密钥,没它服务端起不来) - 模型配置 → 大语言模型 → 给默认模型填一个 API key(官方默认智谱 glm-4-flash,免费;本文后面会换成自己的 Agent)
- 参数管理 → 配置两个地址(决定设备拿到什么连接信息):
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

我接的是自己部署的 Hermes Agent——一个带技能库、持久记忆和完整工具链(终端/浏览器/文件)的开源 Agent 框架,它自带 OpenAI 兼容 API。接上之后,小智就不再是「问答玩具」,而是能动手干活的语音入口:
「帮我看看 D 盘还剩多少空间」→ 它真的去执行命令 → 把数字念给你听
⚠️ 安全提示(必读):能给 Agent 的 API key = 这个 Agent 的完整权限。语音是随口的、不可控的输入,谁都能对它喊话。所以:
- 只在内网用,绝对不要映射公网
- 进阶做法:给语音助手单独建一个权限受限的 Agent 实例(只开查询类工具、禁终端写操作),和主实例隔离
五、玩法 B 第三步:设备切到自家服务
- 对设备说「你好小智,进入配网模式」(或重启后按住按键进配网,还是不行就重新执行2.1和2.2)
- 电脑连
Xiaozhi-xxxx热点,浏览器打开192.168.4.1 - 页面顶部展开「高级选项」,把 OTA 地址改成你自己的:
1 | http://你的IP:8002/xiaozhi/ota/ |
- 保存,设备重连 WiFi 后会自动向你家 OTA 接口报到,并播报新的验证码
- 打开自家智控台(不是 xiaozhi.me!),添加设备、输验证码

搞定。现在整条链路——耳朵、翻译官、大脑——全在你自己家里。
六、踩坑实录(都是真金白银的时间)
坑 1:code=113,「检查新版本失败,XX秒后重试」循环
症状:设备切了 OTA 地址后一直报 113,屏幕循环「检查新版本失败」。
排查思路(值得分享的方法论):先看服务端日志——设备有没有来敲门?结果发现设备成功拉取过一次 OTA 响应(拿到了 WS 地址),然后就没然后了。服务端无责,问题在设备→服务器的网络路径上。
根因:Windows 防火墙。我的主机网卡被识别为「公用网络」,这个配置档默认丢弃所有入站连接。Docker 发布的端口并不自动获得防火墙放行。
修复(管理员 PowerShell,只对内网网段放行,不裸奔):
1 | foreach ($p in 8000,8002,8003) { |
修完设备立刻上线。排查局域网设备连不上时,先 ping/先看服务端日志,最后才怀疑玄学——防火墙是确定性的,但它藏在视线之外。
坑 2:OTA 接口 curl 测试返回 500
新版智控台的 OTA 接口要求请求头带 Device-Id、请求体带 application 字段,缺了就 500。这是给设备用的接口,不是给浏览器用的——用模拟请求测试时要带全:
1 | curl -X POST "http://你的IP:8002/xiaozhi/ota/" \ |
返回里有 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 实例」——毕竟现在这个,权限大得我自己都有点慌(笑)。