Home Assistant 中 xiaomi_aqara.add_device 操作实战：为 Aqara 网关开启 30 秒配对窗口-平芜编程栈

Home Assistant 中 xiaomi_aqara.add_device 操作实战：为 Aqara 网关开启 30 秒配对窗口

【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io

导读

本文围绕 Home Assistant 的Xiaomi Gateway (Aqara)集成（域名为xiaomi_aqara）提供的add_device操作展开。该操作可在自动化或脚本中远程开启网关的配对许可 30 秒，让你无需打开 Mi Home 手机 App 即可把新的传感器或开关接入网关。读完本文，你将掌握该操作在 UI 与 YAML 两种方式下的完整配置方法、gw_mac参数的使用要点，以及它与remove_device、play_ringtone、stop_ringtone等兄弟操作配合的实战套路。

操作概述：add_device 做什么

在 xiaomi_aqara.add_device 操作文档中定义：Add device操作会开启指定 Xiaomi Aqara 网关的"加入许可"（join permission），持续30 秒。在这段时间内，新设备只要按下一次配对按钮即可被网关识别并完成入网。

该操作的核心价值在于：

免 App 配网：传统方式下，给网关添加子设备通常要打开 Mi Home App 手动操作；通过 Home Assistant 自动化，你可以把"入网许可窗口"变成可编程、可触发的流程。
可自动化：例如先用自动化让网关进入配对状态，再去按设备配对键，完全不需要掏出手机。
脚本可编排：脚本中可先调用add_device，等待片刻后校验新设备是否出现，再配合remove_device完成设备迁移。

从操作行为看，它与 remove_device（移除已配对设备）、play_ringtone（播放铃声）、stop_ringtone（停止铃声）共同构成该集成在 Home Assistant 中的四个原生操作，均在操作文档头部通过related_actions字段互相引用。

前提条件：网关与集成

add_device操作依赖 Xiaomi Gateway (Aqara) 集成已成功配置。该集成（ha_integration_type: hub）支持以下设备控制面：binary_sensor、cover、light、lock、sensor、switch，IoT 类别为 Local Push，支持通过配置流（ha_config_flow: true）与 zeroconf 自动发现接入。

集成文档特别提示了两个网关版本的差异：

v1 网关：可直接配合 Home Assistant 使用，无特殊问题。
v2 网关：启用本地 API 可能较为曲折，甚至可能需要拆机操作；Xiaomi 官方曾表示该能力在规划中。若使用 Hub 2 遇到问题，可参考集成文档的 Troubleshooting 一节排查。

配置时可选参数包括interface（使用的网络接口，默认any）、key（网关密钥，仅使用传感器/二进制传感器时可省略）、name（网关名称）。

方式一：从用户界面（UI）触发

add_device操作不支持 targets——在 UI 中你不会被提示选择区域（area）、设备、实体或标签（label），只要求填写网关 MAC 地址。这是因为该操作作用于网关本身，而非具体实体。

在 UI 中从自动化或脚本调用该操作的步骤如下：

进入设置>自动化与场景（Settings > Automations & scenes）。
打开一个现有的自动化或脚本，或选择创建自动化>创建新自动化。
如果新建的是自动化，需要在当...时（When）部分添加触发器；脚本不需要触发器，脚本在被其他东西调用时才会运行。
在然后执行（Then do）部分，选择添加操作（Add action）。
在搜索框中搜索并选择Xiaomi Gateway (Aqara): Add device。
填写网关 MAC（Gateway MAC）。
点击保存（Save）。

UI 中的选项

选项	说明	必填
网关 MAC（Gateway MAC）	网关的 MAC 地址；只有一个网关时自动选中	是

方式二：在 YAML 中使用

在 YAML 中，该操作以xiaomi_aqara.add_device引用。最基本的示例如下（来自操作文档）：

action: xiaomi_aqara.add_device data: gw_mac: aa:bb:cc:dd:ee:ff

注意：在自动化中，该 YAML 通常作为actions列表中的一项：

- alias: "Pair new device to Aqara gateway" triggers: - trigger: state entity_id: input_boolean.pairing_mode to: "on" actions: - action: xiaomi_aqara.add_device data: gw_mac: aa:bb:cc:dd:ee:ff

YAML 选项说明

字段	类型	必填	说明
`gw_mac`	string	是	网关的 MAC 地址；只有一个网关时自动使用

参数深度解读：gw_mac

gw_mac是add_device操作的唯一参数，其语义在 remove_device 等兄弟操作中保持一致：MAC 地址用于在多网关环境下精确定位目标网关。

单网关场景：文档明确说明"当只有一个网关时，它会被自动选中/使用"。因此即便不显式指定gw_mac，Home Assistant 也会自动推断。
多网关场景：必须显式传入目标网关的 MAC，否则操作无法确定要开启哪个网关的配对许可。

MAC 地址的格式为小写十六进制、冒号分隔，如aa:bb:cc:dd:ee:ff。另外，从 Xiaomi Gateway (Aqara) 集成的 Troubleshooting 可以了解到：如果网关 MAC 以04:CF:8C或7C:49:EB开头，很可能其 9898 端口处于关闭状态，导致本地 API 方式不可用——这类网关需要额外的硬件级处理（文档提及需要焊接和电工操作），使用add_device前应先确认网关可被正常发现和控制。

实战场景一：配合 remove_device 迁移设备

add_device最常见的组合拳是与remove_device一起使用。根据 remove_device 操作文档：

Remove device操作从指定网关移除一个已配对设备。
当你想把设备配对到另一个网关时，必须先把它从当前网关移除。

因此迁移流程为：先调用xiaomi_aqara.remove_device移除旧网关上的设备，再对目标网关调用xiaomi_aqara.add_device开启 30 秒配对窗口，最后按下设备配对键。

remove_device的 YAML 示例：

action: xiaomi_aqara.remove_device data: gw_mac: aa:bb:cc:dd:ee:ff device_id: 158d000xxxxxc2

其中device_id是待移除设备的硬件地址（必填，string 类型）。可以看到两个操作的参数风格完全一致：gw_mac定位网关，设备级参数（如device_id）定位具体子设备。

实战场景二：配合 play_ringtone 实现配对提示

开启配对窗口后，用户往往需要走到设备旁按下配对键。为了让状态更直观，可以先调用 play_ringtone 播放提示音。该操作要求网关固件至少为1.4.1_145，支持的铃声 ID 分为几组：

警报类：0 警车1、1 警车2、2 事故、3 倒计时、4 幽灵、5 狙击枪、6 战斗、7 空袭、8 犬吠
门铃类：10 门铃、11 敲门、12 Amuse、13 闹钟
闹钟类：20 MiMix、21 Enthusiastic、22 GuitarClassic、23 IceWorldPiano、24 LeisureTime、25 ChildHood、26 MorningStreamLiet、27 MusicBox、28 Orange、29 Thinker
自定义铃声：通过 Mi Home App 上传的自定义铃声，ID 从 10001 起

对应 YAML：

action: xiaomi_aqara.play_ringtone data: gw_mac: aa:bb:cc:dd:ee:ff ringtone_id: 8 ringtone_vol: 8

铃声播放后可用 stop_ringtone 立即停止（如报警被确认后静音），其 YAML 只需gw_mac一个参数。

实战场景三：完整自动化示例

将上述能力组合成一个"一键配对新设备"的自动化：当开关被打开时，先播放提示音，再开启 30 秒配对窗口，并给手机推送通知。

- alias: "Open Aqara gateway for pairing" triggers: - trigger: state entity_id: input_boolean.pairing_mode to: "on" actions: - action: xiaomi_aqara.play_ringtone data: gw_mac: aa:bb:cc:dd:ee:ff ringtone_id: 10 ringtone_vol: 50 - action: xiaomi_aqara.add_device data: gw_mac: aa:bb:cc:dd:ee:ff - action: notify.notify_person data: message: "配对窗口已开启，请在 30 秒内按下设备配对键"

快速验证：在 Actions 工具中试运行

不想写 YAML 也可以直接验证该操作：打开设置>工具>操作（Actions），搜索xiaomi_aqara.add_device，填写网关 MAC 后点击执行操作（Perform action），即可在真实网关上看效果。这也是排查参数是否正确的最快路径。

常见问题与排查思路

操作执行后设备仍未入网：确认已在 30 秒窗口内按下设备配对键；若超时，需重新触发操作。
多网关环境下不指定gw_mac：操作可能无法确定目标网关，建议始终显式传入 MAC。
网关无法被发现/控制：参考 Xiaomi Gateway (Aqara) 集成的 Troubleshooting——检查 LAN 访问是否已启用、系统防火墙是否拦截、路由器是否支持组播（multicast，网关的硬性要求），Docker 部署需使用--net=host；若日志出现{"error":"Invalid key"}，可尝试用 Android 手机或模拟器重新生成密钥（某些 iOS 生成的密钥存在兼容问题）。
MAC 以04:CF:8C或7C:49:EB开头：这类网关的 9898 端口很可能被关闭，本地 API 方案不可用，需要硬件级处理。

小结

xiaomi_aqara.add_device是 Home Assistant 操作xiaomi_aqara域下实现"免 App 配网"的关键操作：通过gw_mac定位网关，一次调用即可开启 30 秒配对窗口。结合remove_device可完成设备跨网关迁移，结合play_ringtone/stop_ringtone可构建带声音反馈的完整配网流程。无论是 UI 可视化配置还是纯 YAML 编写，掌握这一操作都能显著提升 Aqara 设备的接入效率。

【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考