Xiaomi Cloud Tokens Extractor

这是什么

Xiaomi Cloud Tokens Extractor 解决的是米家玩家最卡的一个环节：拿到设备的 token。

小米生态里的设备（扫地机、净化器、风扇、插座、灯具、传感器……）走的是本地 miIO 协议，本地控制必须带一个 32 位十六进制的 token 做鉴权。这个 token 在米家 App 里看不到，官方也不提供任何获取途径——它只存在于你的云端账号里。

这个工具干的事很直白：用你的米家账号登录小米云，把账号下所有设备的名称、型号、IP、MAC、token，以及蓝牙设备的绑定密钥（BLE key），一次性全部打印出来。

没有它，接入 Home Assistant 的 xiaomi_miio、跑 Valetudo、用 python-miio 命令行控制设备，第一步就过不去。

四种跑法，按你的环境挑

1. Windows：直接双击

下载并运行 token_extractor.exe（release 里的独立打包版，约 19MB，不用装 Python）。
这个 exe 是 release 里下载量最高的资产（10 万+），绝大多数人走的就是这条路。

2. Linux / Home Assistant：一行命令

bash <(curl -L https://github.com/PiotrMachowski/Xiaomi-cloud-tokens-extractor/raw/master/run.sh)

在 HA 的 SSH & Web Terminal 插件里可以直接粘这一行。

3. Docker 版（脚本装不上的时候用）

bash <(curl -L https://github.com/PiotrMachowski/Xiaomi-cloud-tokens-extractor/raw/master/run_docker.sh)

在 Home Assistant 里跑这条，需要先在插件设置里关掉 protected mode 再重启插件。

4. 手动跑 Python

wget https://github.com/PiotrMachowski/Xiaomi-cloud-tokens-extractor/releases/latest/download/token_extractor.zip
unzip token_extractor.zip
cd token_extractor
pip3 install -r requirements.txt
python3 token_extractor.py

压缩包只有 9KB 左右，就是个纯脚本 + requirements.txt，想审计代码或者改点东西的话这个版本最合适。

用起来是这样

启动后先选认证方式，两种：

• 账号 + 密码：填米家账号（邮箱 / 小米云 ID）和密码，然后去邮箱取验证码（2FA）
• 二维码登录：新版加的，扫码授权，绕开密码和验证码那一套

接着选服务器区域：cn（中国）、de（德国）等，留空则会遍历所有区域——不确定账号注册在哪个区就留空。

然后就是结果列表，每台设备一行，包含：

• 设备名、型号
• 局域网 IP、MAC
• token（32 位十六进制）
• 蓝牙设备的 BLE key

拿到 IP + token 这两样，xiaomi_miio 就能直接接管了。

卡住了怎么办（官方 troubleshooting，基本覆盖 90% 的情况）

1. 账号密码确认没搞错——尤其是别用 Roborock App 的账号，必须用米家（Mi Home）的账号。这是最高频的坑。
2. 把 Cloudflare DNS 关掉（换成 8.8.8.8 / 223.5.5.5 之类），部分网络环境下 CF 解析会导致登录失败。
3. 关掉广告拦截和地域限制：AdGuard、Pi-hole、UniFi 的国家/地区限制都会拦掉小米云接口。
4. 验证码去找垃圾邮件箱，2FA 邮件常被判垃圾。
5. 改用二维码登录，直接跳过密码 + 验证码流程。
6. 验证码有额度限制：一天只能发 3～5 次（看区域）。试爆了就真的得等到第二天，别硬刷。

token 到手之后能干什么

• Home Assistant 原生接入：xiaomi_miio 集成本地控制扫地机、净化器、风扇、灯具、插座，不依赖云，响应快、断网也能用
• Valetudo / 第三方固件路线：刷机前基本都要先拿到 token 才能把设备从云端"解绑"到本地
• python-miio 命令行：miiocli device --ip <IP> --token <TOKEN> info，调试和批量操作都方便
• 蓝牙设备：BLE key 可以喂给 ESPHome / OpenMQTTGateway / HA 的 BLE 集成，解密小米蓝牙温湿度计、门磁之类的广播数据

作者自己维护的那套 HA 生态也很实用，通常和这个工具一起用：

• Xiaomi Cloud Map Extractor——扫地机实时地图
• Xiaomi Vacuum Map Card——Lovelace 里点地图选区清扫

安全提醒（重要）

• token 等于设备的控制权。局域网内拿到 IP + token 就能发指令，所以贴日志、发 issue、截图求助之前，先把 token 和 IP 打码。
• 工具本身是把你的账号密码交给小米官方云接口去登录（就是 App 走的那套），不经过任何第三方服务器；但它毕竟要处理你的账号凭据，建议在可信机器上跑，别用公共/共享环境。
• 长期不用云的话，拿完 token 可以考虑把设备的云连接关掉，减少一个外部攻击面。
• 项目用 MIT 协议，作者另有一堆 HA 组件，接受捐赠但代码完全开放，可以直接读源码确认它到底发了什么请求。

适用人群

• 想把米家设备本地接入 Home Assistant 的人（这个工具是前置步骤，绕不开）
• 准备给扫地机刷 Valetudo / 走第三方固件的折腾党
• 用 ESPHome、OpenMQTTGateway 解密小米蓝牙传感器数据的
• 单纯想搞清楚自己账号下到底挂了多少台设备、各自 IP 是多少的

一句话总结

米家设备本地化的第一把钥匙：一次登录，把账号下所有设备的 token 和 BLE key 全导出来——Windows 双击 exe，Linux/HA 一行 curl，剩下交给 Home Assistant。