小米米家云接入
小米米家云协议（xiaomiCloud）把米家 App 中已有的设备同步到联犀。完成接入后，可以在联犀查看设备和物模型，并对受支持的属性或服务进行调试。
接入前准备
| 准备项 | 怎么确认 |
|---|---|
| 小米米家云网关 | 在物联网应用「设备接入 → 协议网关」查看运行状态。自建环境若已启动网关但没有企业／项目入口，请管理员检查协议配置通道是否已启用，以及网关是否声明了对应能力。 |
| 联犀账号与权限 | 能进入目标企业或项目的「协议配置」并新增、编辑配置。仅可查看时，请由有配置权限的成员操作。 |
| 小米账号和测试设备 | 在米家 App 登录准备授权的账号，确认能看到目标设备。记录设备所属云区域，先选一台便于核对的设备。 |
| 小米应用及设备接口权限 | 准备允许联犀使用米家设备接口的 OAuth AppID，并确认应用可登记当前联犀地址。小米的通用账号服务只提供账号授权能力，米家设备接口权限需另向小米或部署管理员确认。 |
| 稳定的联犀访问地址 | 正式环境使用浏览器可访问的 HTTPS 地址。用这个地址打开联犀、发起授权并完成回调。 |
小米开发者账号用于管理应用和回调；米家账号用于授权读取设备。小米官方 Home Assistant 集成使用它自己的应用标识和回调，联犀接入应使用经小米确认的应用。小米账号服务说明
1. 选择配置范围
进入「设备接入 → 协议配置」，选择范围，在小米米家云一行点击「配置详情」。项目级需要先选择具体项目。
| 选择 | 适用场景 | 新同步设备的归属 |
|---|---|---|
| 企业级 | 由企业统一维护小米账号 | 归入当前企业 |
| 项目级 | 由具体项目单独维护小米账号 | 归入所选项目 |
每个账号分别建配置并授权。用有意义的名称区分账号和用途，例如「园区 A · 米家演示」。首次接入时，先用一个账号和一个范围验证。已有设备的归属不会随新增配置自动改变。
2. 保存账号配置并登记回调
在配置详情点击「新增配置」，或在已有行点击「配置」。
| 字段 | 怎么填 |
|---|---|
| 配置名称 | 填写易于识别的名称。默认配置和新增实例都可修改名称。 |
| OAuth AppID | 填小米侧对应应用的标识。该字段与小米登录账号、手机号、设备编号分别独立。 |
| 授权回调地址 | 复制联犀页面生成的完整地址。前缀来自当前访问联犀的协议、域名及端口，路径固定。 |
| 云区域 | 与米家 App 中设备所在区域一致。留空默认 cn（中国大陆）；其他区域可按需填写 de（欧洲）、i2（印度）、ru（俄罗斯）、sg（新加坡）、us（美国）。 |
例如，用 https://iot.example.com 打开联犀时，登记以下完整地址。实际使用请替换示例域名。
https://iot.example.com/api/v1/things/protocol/web/product/xiaomiCloud请核对协议、域名、端口和路径，回调地址不带查询参数或片段。小米账号密码只在小米账号页面填写，令牌由授权流程处理。
小米侧登记回调
- 打开小米澎湃 OS 开发者平台，登录后进入「管理中心」。首次使用时按提示选择「开发者注册」；已有开发者账号时选择「绑定开发者账号」。
- 在「应用服务 → 账号服务」中选择对应应用，按控制台提示启用账号服务并填写上面复制的完整回调地址。
- 确认登记的应用与联犀表单中的 AppID 对应，并向小米确认米家设备接口权限。两边配置都准备好后再发起授权。
小米控制台操作以小米账号服务的发布流程为准。上图记录的是开发者入口和注册步骤，具体回调设置在应用的账号服务里完成。
3. 授权并验证设备同步
- 在联犀保存配置，回到同一行点击「授权账号」。首次保存后显示「未授权」时，继续完成小米侧登录。
- 在打开的小米页面登录能在米家 App 看到目标设备的账号。如果显示英文，可从登录页语言菜单选择「中文（简体）」。
- 小米显示授权确认页时，核对应用名称和权限，再点击「确认授权」。使用同一浏览器完成回调，回到发起授权的配置行。
- 点击「检查连通」，确认页面提示「连通检查通过」，再按下一节核对设备是否同步。
小米账号中文登录界面
下图是小米账号的简体中文登录表单，可对照账号、密码和「登录」按钮。实际应用名称以从联犀发起授权后的小米页面为准。
登录后的授权确认页
这是 2026 年 10 月 28 日真机测试时的小米侧简体中文页面，图片仅展示权限和按钮区域。当时的测试应用是 Home Assistant 集成；使用联犀时，请核对当前小米页面显示的应用和权限。
怎么判断授权成功
| 页面结果 | 表示什么 | 下一步 |
|---|---|---|
| 未配置 | 配置尚未保存 | 填写并保存 |
| 未授权 | 配置已保存，尚缺可用的授权记录 | 点「授权账号」完成回调 |
| 已配置 | 页面检测到已保存的授权信息 | 点「检查连通」确认当前仍可访问 |
| 连通检查通过 | 网关成功读取一页小米设备列表 | 到产品和设备列表核对同步结果 |
| 保存成功，连通检查未通过 | 配置已经保存，小米接口检查未通过 | 先看失败提示，再按文末排查 |
连通检查仅读取一页设备列表。它不下发控制，也无法单独证明设备已全部同步。
4. 核对产品、设备和控制结果
- 检查归属。 在联犀「设备接入 → 产品管理」和「设备接入 → 设备管理」切换到授权对应的企业；项目级同时切到选定项目。网关会尝试初次同步，正常情况下之后约每 10 分钟对账一次。首次没看到设备时，可以刷新列表，等一个同步周期后再检查。
- 检查型号。 同步会按米家型号归组创建或更新产品，并同步设备。通常不必手工建产品和设备。进入产品详情「设备接入」，核对「米家型号」和型号编码。部分型号可显示中文类别名，精确核对时使用型号编码。
- 检查上行。 打开测试设备详情，核对设备归属、在线状态和物模型。用米家 App 改变一个可安全测试的状态，例如测试灯的开关，再看联犀属性值或设备日志是否更新。
- 检查下行。 在允许测试且有人能核对实体状态的设备上，选择已映射的可写属性或服务，用设备调试发出操作。分别核对联犀回执、小米侧读回状态和实际设备动作。测试结束后恢复原状态。
此前的项目级真机测试确认了产品和物模型创建、设备归属项目，以及控制回执和云端读回。验收现场设备时，仍需核对真实设备动作及上报。
查看此前真机测试的英文登录页
图中的 Home Assistant 名称属于当时的测试应用。
5. 多账号、重新授权与旧版迁移
- 增加账号时新建具名配置，在目标企业或项目单独授权，并核对新同步设备归属。
- 账号过期或被撤销时在原配置行重新发起授权，随后再做连通检查。若要主动撤销，可在米家 App 的小米账号「应用授权」中找到对应应用并取消授权。
- 更换账号、区域或归属前先记录原配置与关联设备。若设备已有归属或关联冲突，请部署管理员先核对迁移和产品绑定，再切换账号。
- 从旧版平台级账号升级时，先清点原账号、产品和设备，明确目标企业或项目，由管理员手工迁移并验证。历史配置和设备不会自动迁移；小米刷新令牌可能轮转，应避免新旧链路同时使用同一令牌。多协议接入及旧版升级说明
常见问题
| 现象 | 先检查什么 |
|---|---|
| 找不到小米米家云或无法新增 | 核对是否选对企业／项目、当前用户权限、网关在线状态和协议配置能力。自建环境请部署管理员确认受信配置通道。 |
| 没有可用的 OAuth AppID | 向小米或部署管理员确认能用于联犀回调及米家设备接口的应用。仅开通通用账号登录服务还需要确认设备接口权限。 |
| 回调不匹配或确认后没有返回 | 核对小米登记的完整回调与联犀表单逐项一致；使用登记过的地址重新打开联犀，并在同一浏览器重新发起授权。 |
| 连通检查通过，列表没看到设备 | 在米家 App 核对授权账号、设备及区域，再核对联犀企业／项目筛选。等一个同步周期后仍没有，记录配置名称和时间请管理员检查网关同步日志。 |
| 部分设备缺失，或没有所需属性和控制项 | 核对型号是否能通过小米云接口读取、是否有对应物模型和可写属性或服务。用米家 App 可操作的设备做对照，管理员可检查同步是否部分失败。 |
| 有成功回执，设备未实际动作 | 查看设备在线状态和读回属性，并到现场核对。保存设备调试的时间和回执，便于排查下行及小米侧状态。 |
更新日志
2026/11/10 12:52
查看所有更新日志
b002a-于36c4c-于84f34-于ae9e0-于