让 AI 硬控米家：xiaomi-home Skill 与安全警告
前言
米家设备控制，官方路子是 APP 或云 API——都要绕一圈云端，响应慢半拍，还依赖账号体系。 " ClawHub 上的 xiaomi-home skill 换了条路：让 AI Agent 直接在局域网里通过 miiocli 硬控设备。你说"打开热水器"，它翻译成一条 MIOT 协议指令直接打到设备的 IP 上。3.4k 下载量，纯本地通信，响应是毫秒级的。
但这个 skill 的安全扫描页上挂着一个显眼的 Suspicious 标记。它怎么工作的、token 从哪来、为什么被标记，这篇一起讲清楚。
一、项目身份
xiaomi-home 是一个 OpenClaw skill（作者 Pegasus02，v1.2.1，ClawHub 下载 3.4k+），让 Agent 在局域网内直接控制米家 WiFi 设备。
一句话说清楚：
基于 miiocli（python-miio）的米家局域网控制 skill——查状态、开关电源、调 MIOT 属性，覆盖智能插座、加湿器、电饭煲等设备
安装：npx clawhub@latest install xiaomi-home（依赖 miiocli，装 skill 时会自动 pipx 安装 python-miio 并顺手修掉 click 版本冲突）。
典型用法：
- 从 Claude 发起 Roborock 扫地机清扫并查状态
- 根据设备传感器读数调空气净化器风量
- 不开米家 APP 定时开关智能插座
- 查加湿器/净化器滤芯剩余寿命
二、核心思路：意图映射表 + 局域网直连
整个 skill 的核心其实就是两样东西：一张自然语言到 miiocli 命令的映射表，和本地直连的通信方式。
映射表长这样——这是 v1.2.0 引入的关键设计，把"AI 猜命令"变成"AI 查表"：
| 用户意图 | 设备类型 | 技术命令 |
|---|---|---|
| "打开热水器" | 智能插座 | miotdevice raw_command set_properties '[{"siid":2,"piid":1,"value":true}]' |
| "加湿器开最大" | 加湿器 | set_property_by 2 5 3 |
| "饭熟了吗" | 电饭煲 | cooker status |
为什么这张表重要？MIOT 协议里每个功能都是 siid/piid 这样的数字编号——"打开热水器"对应的是 siid 2、piid 1 的布尔属性，这不是 AI 能凭空猜对的。映射表把领域知识固化在 skill 里，Agent 只做两件事：听懂人话、查表执行。skill 的价值不在代码量，在这些查不到的知识。
三、核心模块架构
四个模块各有说法：
Token 提取器（v1.1.0 加的）：token_extractor.py 登录你的小米云账号，一次性同步所有设备的 IP 和 32 位 Token——Token 是每台设备的控制密钥，拿到它就拿到这台设备的控制权。
设备注册表：提取出来的设备信息填进 references/devices.md，Agent 执行时查表找 IP 和 Token。
依赖修复：python-miio 和新版 click 有兼容冲突，skill 安装时自动锁 click<8.1.0——把踩过的坑直接固化进安装流程。
版本轨迹：v1.0 到 v1.2.1 全部在 2026 年 2 月 4 日一天内完成——初始版、Token 提取器、意图映射表、双语化，一天迭代四版，是个典型的"个人自用工具顺手开源"项目。
四、数据与状态流
数据流里最敏感的节点是设备注册表：Token 从小米云提取后，以明文存在 skill 目录的 markdown 文件里。小米云只在提取时用一次，之后所有控制都是局域网内 miiocli --ip --token 直连，不经过任何云——这正是它响应快的原因，也是安全隐患的源头（下一节细说）。
五、跨端边界
- Agent 端：OpenClaw（ClawHub 安装），本质是任何能读 SKILL.md、能执行 shell 的 Agent 都可用
- 设备端：米家生态的 WiFi 设备，走 MIOT 协议的（插座、加湿器、电饭煲、扫地机等）；蓝牙 Mesh 设备不在覆盖范围
- 小米云：只在 Token 提取阶段出现一次，之后完全退出链路
- 网络边界：Agent 和设备必须在同一局域网——设备控不了不在家的米家电器，这是限制也是安全边界
六、配置边界
- 必须配：运行 token_extractor.py 拿设备 IP/Token，填入 devices.md
- 自动配：python-miio 经 pipx 隔离安装、click 版本自动锁定——环境问题开箱解决
- 建议配：私人设备信息放
my_private_devices.md（和示例清单分开），别把真实 Token 提交进任何公开仓库 - 不要配：把装有明文 Token 的 skill 目录同步到网盘/代码仓库；在不受信任的网络里用
七、扩展点
- 映射表横向扩充：意图映射表是开放结构，任何 MIOT 设备拿到 siid/piid 就能加一行——新设备接入是"加一行表"而不是"改代码"
- 同类 skill 组合：ClawHub 上有 Home Assistant skill（12.6k 下载）做双向控制与 webhook——HA 路线胜在生态完整、小米直连路线胜在轻量零中间层，两条路可以并存
- 定时与联动：不依赖米家 APP 的定时开关只是起步，Agent 级的联动（"PM2.5 超标就开净化器到三档"）靠的是 Agent 读传感器状态再决策，这是云规则引擎做不到的自由度
- 模式可复制："意图映射表 + 设备注册表 + CLI 直连"这个结构，换掉 miiocli 就能套到任何有本地 CLI 的设备生态上
八、风险点
- 官方安全扫描标了 Suspicious，理由要原样转述：skill 附带并鼓励明文存储小米设备凭证，且 Token 提取涉及大范围的云凭证使用、密钥处理方式不安全。扫描同时说明没有发现明确的数据外传或后门——是"不安全的做法"而非"恶意的代码"，但这两者的风险后果可能一样
- 32 位 Token = 设备的完全控制权。明文躺在 markdown 里，任何能读到这个文件的进程、插件、人，都能直接控制你的设备。skill 目录的可读边界就是你的安全边界
- Token 提取脚本要小米云账号凭证。运行它等于把账号权限交给一个第三方脚本——用之前值得读一遍源码（好在就一个脚本，读得动）
- 设备注册表是人工维护的。IP 变了（DHCP 重新分配）、设备换了，表就过期——建议路由器上给米家设备绑静态 IP，否则 Agent 会拿着旧 IP 乱打
- MIOT 数字编号无校验。映射表里 siid/piid 是硬编码的，不同固件版本的设备属性编号可能不同，指令打错轻则无效重则误动作——热水器这种设备，误动作是要烫人的
- 局域网边界是双刃剑。不出家门意味着安全，也意味着所有"出门前忘了关"的场景它救不了——无云链路，外面喊不动家里
记住
xiaomi-home 的核心是一张意图映射表：把 MIOT 协议的 siid/piid 知识固化下来，Agent 只负责听懂人话、查表、调 miiocli——局域网直连，毫秒级响应，云彻底退出链路。
但它身上那个 Suspicious 标记同样值得记住：明文 Token 是这个 skill 的一切便利的来源，也是它全部风险的来源。用它可以，把设备注册表当密码库一样对待。
给 AI 接管家里的设备之前，先问一句：它的钥匙放在哪，谁能读到。
参考资源
- Skill 页面：https://openclawvps.io/skills/xiaomi-home（含安全扫描报告链接）
- ClawHub：clawhub.ai/Pegasus02/xiaomi-home
- GitHub：github.com/Pegasus02/clawdbot-xiaomi-home
- 底层工具：python-miio（miiocli）