小爱音箱语音通知工具:提供 CLI/TUI/MCP/Webhook 一键播报与控制音量,支持 PM2 常驻部署,支持docker部署。
小爱音箱语音通知工具:提供 CLI/TUI/MCP/Webhook 一键播报与控制音量,支持 PM2 常驻部署,支持docker部署。
speaker.defaultDid 与 speaker.speakers,并兼容旧 speaker.diddid(tts/audio/volume/command),不传按默认优先级路由xiaoi command(动作)与 xiaoi getprop(属性读取)do_action 与 get_property,并统一支持可选 didXIAOI_DEFAULT_DID 与 OH2P(xiaomi.wifispeaker.oh2p)简单 cmd 用例.mi.json(登录凭证缓存)在任意目录执行 CLI 时被写到当前目录的问题,现在固定写入 ~/.xiaoi/ 目录pm2-runtime 不支持的 --log-date-format 参数npm ci 改为 npm install(兼容 pnpm 项目)XIAOI_TOKEN 环境变量示例,方便用户自定义 Webhook 鉴权 Token.env.example 环境变量模板,降低 Docker 部署门槛pm2-runtime)管理进程,自动健康检查与重启ttscmd 输入解析错误:[7,3] 不再被误解析为 [0,7]ttscmd 未设置时,自动显示当前 did 解析出的设备命令(自动映射)ttscmd 自动映射日志输出:显示 model / match / source / command[XIAOI] 前缀,便于在 PM2/控制台过滤检索did 自动解析机型并展示“生效 ttscmd 映射”cmd、临时链路模式、详细日志开关auto / command / defaultttscmd 与临时模式,便于现场调试ttscmd 与默认链路执行细节ttscmd(MiOT.doAction),失败后回退默认 MiNA.play(text)ttsFallbackCommands 映射(含 LX04 等常见型号),并支持用户自定义覆盖speaker.ttsFallbackCommand 与 speaker.ttsFallbackCommandsttscmd 链路和默认链路(MiNA.play)ttscmd 编辑入口:支持修改默认命令与按机型覆盖命令auto / command / default 三种模式,用户可手动切换ttscmd 与默认链路的执行日志ttscmd 与临时链路模式,便于现场调试pm2/npm/npx 探测误判(.cmd shim 导致的 ENOENT/不可执行问题)npm bin -g 导致的全局 pm2 识别失败(改用 npm prefix -g 回退)XIAOI_NO_UPDATE_CHECK=1 禁用)# npm
npm i -g xiaoii
# 或 pnpm
pnpm add -g xiaoii安装后即可在任何目录使用 xiaoi 和 xiaoi-mcp 命令。
git clone https://github.com/xvhuan/xiaoi.git
cd xiaoi
# npm
npm i
npm link
# 或 pnpm
pnpm install
pnpm link --global安装完成或首次执行 xiaoi 时,会自动创建:
~/.xiaoi/(Windows 为 %USERPROFILE%\.xiaoi\)~/.xiaoi/config.json(空模板)编辑 ~/.xiaoi/config.json:
…配置文件查找优先级:
~/.xiaoi/config.jsonconfig.json字段说明(常用):
| 字段 | 说明 |
|---|---|
speaker.userId |
小米 ID(数字,在小米账号个人信息中查看) |
speaker.password |
小米账号密码(可能因安全验证失败) |
speaker.passToken |
passToken(推荐) |
speaker.did |
兼容字段(旧版本默认设备);新版本会与 defaultDid 同步 |
speaker.defaultDid |
默认音箱 did(未在请求体传 did 时优先使用) |
speaker.speakers |
已添加音箱列表(did/name/model/enabled) |
speaker.ttsMode |
TTS 链路模式:auto(先 ttscmd 后默认)、command(仅 ttscmd)、default(仅默认链路) |
speaker.verboseLog |
详细日志开关(true/false),控制是否打印链路执行细节 |
speaker.ttsFallbackCommand |
默认 ttscmd(默认 [5,1],优先调用) |
speaker.ttsFallbackCommands |
按型号覆盖 ttscmd(如 lx04:[5,1]、l09a:[3,1]) |
webhook.host |
监听地址;需要外网访问可设置为 0.0.0.0(注意安全) |
webhook.port |
Webhook 端口 |
webhook.token |
Webhook 鉴权 Token(可选;常驻 Webhook 如果留空会自动生成并写回配置) |
Webhook 默认音箱优先级:
speaker.defaultDidXIAOI_DEFAULT_DID(环境变量)speaker.did(兼容字段)请求体显式传
did时,did必须在speaker.speakers中且enabled=true,否则返回400。
提示:在 TUI 的「账号设置」里可切换 TTS 模式、修改默认/机型
ttscmd、开关详细日志;在「连接测试」里可手动输入临时ttscmd与临时模式进行调试。
推荐使用 passToken 登录。passToken 获取参考:migpt-next/issues/4
xiaoi# 发送语音通知
xiaoi tts "代码编译完成"
xiaoi tts 部署已完成,请查看
# 设置音量
xiaoi volume 30
# 发送 MiOT 指令(可选 did)
xiaoi command 3 1 "[]"
xiaoi command 3 1 '[{"piid":1,"value":true}]' --did 客厅小爱
# 读取 MiOT 属性(可选 did)
xiaoi getprop 3 1 --did 客厅小爱
# 检查连接状态
xiaoi status
# 帮助
xiaoi helpcmd 简单用例(xiaomi.wifispeaker.oh2p)https://home.miot-spec.com/spec/xiaomi.wifispeaker.oh2pttscmd:[7,3]# 1) 最简单:直接发 TTS(推荐)
xiaoi tts "主人,这是一条 OH2P 测试" --did 你的设备did
# 2) 走 MiOT cmd 方式发 TTS(oh2p 常见 [7,3])
xiaoi command 7 3 "[\"主人,这是一条 OH2P cmd 测试\"]" --did 你的设备did
# 3) 读取 playing-state(SIID=3, PIID=1)
xiaoi getprop 3 1 --did 你的设备did
# 返回值常见含义:1=播放中,0=停止,2=暂停构建 cmd(siid/aiid/params)的简单方法:
oh2p 链接)。Service / Action,记录 siid 和 aiid。Action 的参数定义准备 params:无参数用 [],有参数按文档顺序组装 JSON 数组。xiaoi command '' [--did ]。说明:不同动作的
params结构不同,务必以规格书中的 action 参数定义为准。
需要先全局安装并运行
xiaoi完成账号配置。
在项目中创建 .vscode/mcp.json:
{
"servers": {
"xiaoi-voice-notify": {
"type": "stdio",
"command": "xiaoi-mcp"
}
}
}[mcp_servers.xiaoi-voice-notify]
command = "xiaoi-mcp"工具列表:
| 工具 | 说明 |
|---|---|
notify |
发送语音通知(TTS) |
play_audio |
播放音频链接 |
set_volume |
设置音量 |
do_action |
发送 MiOT 指令(siid/aiid/params) |
get_property |
读取 MiOT 属性值(siid/piid) |
这 5 个 MCP 工具都支持可选参数
did:不传走默认音箱,传了走指定音箱。
你可以在 TUI 里启动 Webhook,也可以使用 PM2 常驻方式(见下节)。
当你配置了 webhook.token(或使用常驻 Webhook 自动生成的 token)时,请在请求中携带请求头:
Authorization: Bearer X-Xiaoi-Token: 你也可以在请求体里传 did 指定本次目标音箱;不传时按默认优先级自动路由。
…如果你希望 Webhook 在服务器/电脑上长期后台运行(不需要挂着终端),使用内置 PM2 管理命令:
# 一键常驻启动(后台运行)
xiaoi pm2 start
# 一键部署(start + save)
xiaoi pm2 deploy
# 查看状态
xiaoi pm2 status
# 查看 pm2 进程日志(stdout/stderr)
xiaoi pm2 logs 200
# 查看 Webhook 日志文件(~/.xiaoi/log/webhook.log 等)
xiaoi pm2 webhook-log 200
# 开关公网访问(修改 webhook.host)
xiaoi pm2 public on
xiaoi pm2 public off
# 停止/删除
xiaoi pm2 stop
xiaoi pm2 delete
# 保存进程列表(配合 pm2 startup 可实现开机自启)
xiaoi pm2 save
# 生成开机自启命令(通常需要管理员/Root 权限)
xiaoi pm2 startup如果你的 Webhook 要对外网提供服务,请务必设置
webhook.token或配合防火墙/反向代理做鉴权,避免被任意调用。
将 xiaoi Webhook 封装到 Docker 容器运行,适合服务器/NAS/云主机。基础场景下不需要手动编辑配置文件,只需填写环境变量即可启动(多音箱场景见下文“多音箱配置”)。
# 拉取镜像
docker pull iusy/xiaoi:latest
# 一行启动
docker run -d \
--name xiaoi-webhook \
--restart unless-stopped \
-p 51666:51666 \
-e XIAOI_USER_ID=你的小米ID \
-e XIAOI_PASS_TOKEN=你的passToken \
-e XIAOI_DID=你的音箱名称 \
-e XIAOI_DEFAULT_DID=默认音箱did \
-e XIAOI_TOKEN=你的Webhook鉴权Token \
iusy/xiaoi:latest搞定! 不需要 clone 代码、不需要编辑配置文件。
# 1. 下载 docker-compose.yml 和 .env 模板
curl -O https://raw.githubusercontent.com/xvhuan/xiaoi/main/docker-compose.yml
curl -o .env https://raw.githubusercontent.com/xvhuan/xiaoi/main/.env.example
# 2. 编辑 .env,填入你的信息
# XIAOI_USER_ID、XIAOI_PASS_TOKEN、XIAOI_DID(可选 XIAOI_DEFAULT_DID)
# 3. 一键启动
docker-compose up -d.env 文件建议至少填 3 项(可选加默认音箱):
XIAOI_USER_ID=你的小米ID(数字)
XIAOI_PASS_TOKEN=你的passToken
XIAOI_DID=你的音箱名称
XIAOI_DEFAULT_DID=默认音箱did
XIAOI_TOKEN=你的Webhook鉴权TokenpassToken 获取方法:migpt-next/issues/4
当你有多个音箱时,推荐把目标设备都写进 speaker.speakers,并设置 speaker.defaultDid。
方式 1:进容器用 xiaoi 交互配置(适合手动运维)
# docker run 部署
docker exec -it xiaoi-webhook node /app/bin/xiaoi.js
# docker compose 部署
docker compose exec xiaoi-webhook node /app/bin/xiaoi.js然后在 TUI 里进入:账号设置 -> 音箱列表管理,完成“添加音箱/设置默认音箱”。
方式 2:直接编辑配置文件(适合批量/自动化)
容器内配置文件路径:/root/.xiaoi/config.json(前提是挂载了持久化卷)。
{
"speaker": {
"defaultDid": "客厅音箱did",
"speakers": [
{ "did": "客厅音箱did", "name": "客厅", "model": "oh2p", "enabled": true },
{ "did": "卧室音箱did", "name": "卧室", "model": "lx04", "enabled": true }
]
}
}修改后重启容器生效:
docker restart xiaoi-webhook
# 或
docker compose restart xiaoi-webhook调用规则:
did:走默认音箱(defaultDid > XIAOI_DEFAULT_DID > speaker.did)did:走指定音箱did 必须在 speaker.speakers 且 enabled=true# 构建镜像
docker build -t xiaoi-webhook .
# 运行(直接用 -e 传环境变量)
docker run -d \
--name xiaoi-webhook \
--restart unless-stopped \
-p 51666:51666 \
-e XIAOI_USER_ID=你的小米ID \
-e XIAOI_PASS_TOKEN=你的passToken \
-e XIAOI_DID=你的音箱名称 \
-e XIAOI_DEFAULT_DID=默认音箱did \
xiaoi-webhook| 变量 | 必填 | 说明 |
|---|---|---|
XIAOI_USER_ID |
✅ | 小米 ID(数字,在小米账号个人信息中查看) |
XIAOI_PASS_TOKEN |
✅ | passToken(推荐登录方式) |
XIAOI_DID |
✅ | 音箱在米家 App 中的名称(必须完全一致) |
XIAOI_DEFAULT_DID |
默认音箱 did(不填时回退 XIAOI_DID) |
|
XIAOI_PASSWORD |
密码登录(不推荐,可能被安全验证拦截) | |
XIAOI_TOKEN |
Webhook 鉴权 Token(留空自动生成) | |
XIAOI_PORT |
端口号(默认 51666) |
|
XIAOI_TTS_MODE |
TTS 模式:auto / command / default |
|
XIAOI_VERBOSE_LOG |
详细日志:true / false |
# 查看容器日志(看 Token 和启动状态)
docker-compose logs
# 状态检查
curl http://localhost:51666/
# 发送语音通知
curl -X POST http://localhost:51666/webhook/tts \
-H "Content-Type: application/json" \
-H "Authorization: Bearer " \
-d '{"text":"Docker 部署成功!"}'# 查看日志
docker-compose logs -f
# 重启
docker-compose restart
# 停止
docker-compose down
# 更新(拉取最新代码后)
git pull
docker-compose up -d --build…userId 是小米 ID(数字),不是手机号或邮箱passToken 代替密码登录did 与米家 App 中音箱名称完全一致基于 @mi-gpt/next 构建。
https://github.com/idootop/migpt-next
MIT,详见 LICENSE。
No open issues yet, or sync has not completed.