小爱音箱接入 ChatGPT：MiGPT 部署与使用指南

小爱音箱接入 ChatGPT：MiGPT 部署与使用指南

【免费下载链接】mi-gpt🏠 将小爱音箱接入 ChatGPT 和豆包，改造成你的专属语音助手。项目地址: https://gitcode.com/GitHub_Trending/mi/mi-gpt

MiGPT 的作用是把家里的小爱音箱接入 ChatGPT、豆包等大模型，让原本只能回答固定套路话的音箱，变成可以连续问答、记得住聊天内容的语音助手。项目支持 Docker 和 Node.js 两种启动方式，部署在一台能长期联网的机器上即可，不需要和音箱在同一局域网。

📋 它能做什么

🧾 部署前要准备什么

动手前把这五样准备好，缺一样都会在启动阶段卡住：

• 一台 兼容型号的小爱音箱，小爱音箱 Pro 的兼容性最好；小度、天猫精灵等不在此项目范围内
• 小米账号的userId（在"个人信息"里的小米 ID，不是手机号或邮箱）和密码
• 一个 OpenAI 兼容接口的大模型密钥（ChatGPT、通义千问、DeepSeek 等，只要接口兼容 OpenAI SDK 即可）
• 一台可长期联网的机器：家用主机、NAS、VPS 或 Unraid 都行
• 两个配置文件：.env放模型密钥和环境变量，.migpt.js放账号与音箱参数，均从仓库里的同名 example 文件复制而来，参数含义见 docs/settings.md

网络条件方面：服务本身通过云端接口与音箱通信，跨网络没问题；但模型接口在国内网络访问 OpenAI 官方地址时通常需要代理或改用国产模型，这一点后面常见问题里会再提。

🚀 完成首次部署

拿到代码

把仓库克隆到部署机上，Docker 和 Node.js 路线都从这里开始：

git clone https://gitcode.com/GitHub_Trending/mi/mi-gpt cd mi-gpt

填好配置

把.env.example复制为.env，填入OPENAI_API_KEY、OPENAI_MODEL、OPENAI_BASE_URL；把.migpt.example.js复制为.migpt.js，填入小米userId、密码和音箱的did（米家中设置的设备名称），再按音箱型号填上ttsCommand与wakeUpCommand，型号对照表在 docs/compatibility.md。

跑起来

下面这条命令启动一个后台容器，并把本地的两个配置文件挂载进容器：

docker run -d --env-file .env \ -v $(pwd)/.migpt.js:/app/.migpt.js \ idootop/mi-gpt:latest

Windows 终端下$(pwd)不可用，请写成配置文件所在的绝对路径。如果走 Node.js 路线，则执行npm install后运行node app.js（入口脚本 app.js），并把.migpt.js中的参数作为MiGPT.create的初始化参数传入。

服务跑起来后的原理不复杂：它通过 MIoT 和 MiNA 开放接口给音箱下发播放、暂停、唤醒指令，同时轮询音箱的对话列表，发现以唤醒词开头的新消息就调用大模型生成回复，再经 TTS 合成语音让音箱播报，详见 docs/how-it-works.md。

🩺 部署后如何确认生效与排查高频问题

确认是否生效分两步：先看容器日志，出现登录小米账号成功、拉取到音箱设备列表的日志即可；再对音箱说"小爱同学，请问地球为什么是圆的"，音箱用 AI 风格的语言念出回答，就代表全链路通了。

以下是几个高频问题，按"现象 → 原因 → 处理"来说：

• 现象：日志报"70016：登录验证失败"。原因：userId填成了手机号或邮箱。处理：到小米账号"个人信息"页复制小米 ID 重新填入。
• 现象：触发小米账号异地登录保护。原因：账号在陌生网络首次登录需要安全验证。处理：在与部署机相同的网络环境下手动登录小米账号通过验证，等待约 1 小时后重启服务；仍不行的话，先在本地网络登录一次，把生成的.mi.json挂载到容器的/app/.mi.json下。
• 现象：报"找不到设备"。原因：did与米家中的设备名称不一致，常见于错别字、多余空格或大小写（如"小爱音响"、"小爱音箱 Pro"）。处理：直接从米家复制设备名；若名称对不上，就开启debug和enableTrace查看 MiNA 设备列表，把日志里的miotDID填入did。
• 现象：控制台打印了 AI 回复，但音箱不发声。原因：不同型号的ttsCommand不同。处理：按型号查 MIoT 规格表改对应参数，参考 docs/faq.md 的播放异常章节。
• 现象：对音箱说话没有任何反应。原因：MiGPT 只处理以唤醒关键词开头的消息，且必须先唤醒小爱同学。处理：把话组织成"小爱同学，请 xxx"的形式；需要时再扩展callAIKeywords列表。

🔧 按需深入的方向

想让回答更跟手：提示语与检测参数

默认配置偏保守，前后都有提示语，回复之间会有停顿感。如果嫌慢，把onAIAsking和onAIReplied置为空数组去掉提示语，调小连续对话时的播放状态检测间隔，或者干脆换一个响应更快的模型，效果都会立竿见影，详见 docs/faq.md 中"AI 回答速度"一节。

想连续聊：记忆与流式响应

长短期记忆模块默认就在运行，对话摘要存在本地数据库里。需要注意的是"流式响应/连续对话"在不同型号上的支持情况不同：设备无法正确查询播放状态时（比如小米音箱 Play 增强版），就应关闭streamResponse，否则会出现播报被截断、戛然而止的现象。

想换个开场方式：自定义唤醒词

音箱固件层的"小爱同学"改不了，但进入 AI 模式的短语可以自定义：把wakeUpKeywords改成自己喜欢的说法（比如"打开傻妞"），说"小爱同学，打开傻妞"就能进入连续对话状态，再用exitKeywords定义的短语退出。进入后会播一句onEnterAI欢迎语，这些提示语都可以按场景增删。

想换音色：接入第三方 TTS

默认走小米自带 TTS。部署一个 TTS 服务后，把环境变量TTS_BASE_URL指向它，再把speaker.tts设为custom，就能用"小爱同学，把声音换成 xxx"这类语音指令在线切换音色，接入步骤见 docs/tts.md。

写在最后

MiGPT 本身是单实例服务，一个容器对应一台音箱，多音箱或多账号就再起一个容器即可。想继续深挖，可以从这三个地方入手：docs/settings.md 的完整参数表、docs/faq.md 的问题索引，以及 src/services/speaker/ 里音箱通信的实现源码。另外项目目前处于停止维护状态，使用前建议先阅读 README 顶部的说明。

【免费下载链接】mi-gpt🏠 将小爱音箱接入 ChatGPT 和豆包，改造成你的专属语音助手。项目地址: https://gitcode.com/GitHub_Trending/mi/mi-gpt