ZHA 配置教程
ZHA（Zigbee Home Automation）是 Home Assistant 官方出品的 Zigbee 集成。配合一个 Zigbee 协调器（USB 网关），它可以让你在 Home Assistant 中直接组建 Zigbee 网络，并接入各类 Zigbee 设备。本文演示在冬瓜 HAOS 上配置 ZHA 并添加 Zigbee 设备的完整流程。
| 名称 | OS | Core |
|---|---|---|
| 版本 | 17.0 | 2026.2.1 |
在开始之前，请确认：
- 你的 Home Assistant 已经正常运行，并能正常访问后台。
- 你已经准备好一个 Zigbee 协调器（USB 网关），并能将其插入 HA 盒子的 USB 口。
注意：ZHA 与 Zigbee2mqtt（简称 Z2M）不能同时使用，除非你有 2 个协调器！！！
选型说明：
- Z2M（推荐使用）：全球有众多开发者和 Zigbee 生产厂家持续更新设备库，支持的设备较 ZHA 更多。接入 Z2M 时需到 Z2M 官网获取设备型号、信息（图片、功能、供应商等）。
- ZHA：是 Home Assistant 官方出品的集成，只有少量开发者维护，随 Core 更新库文件，支持的设备库较少。
同一个设备在 ZHA 和 Z2M 中可使用的功能可能存在差异，请按需选择。
第 1 步：查询协调器串口
Section titled “第 1 步：查询协调器串口”将协调器接入盒子，依次点击 设置 > 系统 > 硬件 > 全部硬件 > 搜索 tty，会出现一个 ttyUSBx 的设备（在没有插其他 USB 设备的情况下），这个设备即为协调器。
第 2 步：添加 ZHA 集成
Section titled “第 2 步：添加 ZHA 集成”依次点击 设置 > 设备与服务 > 集成 > 添加集成 > 搜索 zha。
第 3 步：选择协调器端口
Section titled “第 3 步：选择协调器端口”选择刚刚查询到的 ttyUSBx，点击 提交。
第 4 步：选择自动设置
Section titled “第 4 步：选择自动设置”在设置方式中选择 自动设置。
第 5 步：等待组建新网络
Section titled “第 5 步：等待组建新网络”集成会开始形成新网络（大概需要 3-5 分钟，不用关闭页面），耐心等待即可。
第 6 步：完成集成安装
Section titled “第 6 步：完成集成安装”组建完成后，点击 跳过并完成。
第 7 步：添加 Zigbee 设备
Section titled “第 7 步：添加 Zigbee 设备”进入 Zigbee Home Automation，点击 添加设备。
第 8 步：让设备进入配对模式
Section titled “第 8 步：让设备进入配对模式”进入到配对状态后，将你的 Zigbee 设备开启配对模式。
第 9 步：等待初始化完成
Section titled “第 9 步：等待初始化完成”待页面出现 初始化完成 后，设备即添加成功。
| 问题 | 解决办法 |
|---|---|
| ZHA 和 Z2M 可以同时使用吗？ | 不能同时使用，除非你有 2 个协调器。 |
| ZHA 和 Z2M 怎么选？ | 推荐使用 Z2M，支持设备更多、更新更及时；ZHA 是官方集成、配置简单，但支持的设备库较少。 |
| 在硬件列表里找不到协调器 | 确认协调器已插好；在未插其他 USB 设备的情况下，列表中出现的 ttyUSBx 即为协调器。 |
| 组建网络一直转圈 | 形成新网络大概需要 3-5 分钟，不要关闭页面，耐心等待即可。 |
ZHA 的配置核心流程是：查询协调器串口 → 添加 ZHA 集成 → 选择端口并自动设置 → 等待组建网络 → 完成 → 添加并配对 Zigbee 设备。请注意 ZHA 与 Z2M 不能在同一个协调器上同时使用。