一个基于 xiaomi_gateway3 集成之上的 Home Assistant 自定义集成。 它专门解决一个常被忽略的问题：
多模网关在 HA 里显示「已连接」，但下挂设备（如开关控灯）的自动化指令实际执行不了。
xiaomi_gateway3 判断「在线」只依赖 MQTT 心跳 / Telnet 端口，并不验证「指令到底有没有真正下发到设备」。 当网关的 Zigbee / BLE 控制通路假死（射频卡住、openmiio 代理挂掉），HA 仍以为一切正常，于是自动化静默失效。
本集成用一个探针来检测「能不能执行」，并在连续失败时硬重启物理网关根治问题。 探针提供两种模式——默认「被动」模式完全不操作设备，零闪烁，详见下文。
你指定一个「探针实体」——网关下挂的任意一个开关或灯（甚至一个平时不用、但接在网关下的设备即可）。 看门狗按所选模式检测：
- 看门狗不发任何指令，只观察该设备是否仍被 xiaomi_gateway3 报为
available。 - 当网关的 Zigbee / BLE 控制通路假死（最常见是 openmiio 代理崩溃）时，xiaomi_gateway3 会把下挂设备标成
unavailable。 - 一旦探针变成
unavailable→ 判定控制通路断了 → 触发重启。 - 设备全程不会被切换，所以没有闪烁、没有误操作。
被动模式覆盖了你描述的绝大多数故障（网关在线但控制失效）。它的盲点极其罕见： 「设备还能回报自身状态、但网关收得到回报却发不出指令」这种「又聋又瞎的反面」状态——真遇到再切到主动模式。
- 每隔
检测间隔秒，看门狗向探针发一条反向指令（homeassistant.turn_on/off）， 在指令超时内回读实体状态是否真的翻转。- xiaomi_gateway3 的实体是非乐观的：状态只来自网关的真实回报。所以「发了指令但状态没变」= 控制通路已断。
- 验证翻转后，看门狗立即把设备切回原始状态，因此不会像旧版那样被长期卡在翻转后的状态。 （每个检测周期仍会有一次极短的闪烁，但检测完即复位。）
连续 失败 N 次 仍不通 → 通过网关 23 端口 Telnet 发送 reboot 硬重启物理网关
（重置射频 + openmiio 代理，这才是治本；单纯重启 HA 集成没用），然后进入 冷却 期等它重新上线。
单个探针设备自身出问题（电池没电、被拔掉、出范围、坏了）也可能变成 unavailable，但那不是网关的锅。
若只看一台设备，会把健康网关无辜重启，甚至因坏设备一直 unavailable 而陷入「重启→仍失败→再重启」的死循环。
因此本集成支持多个探针实体（建议 ≥2，且尽量用常电设备）：
- 只有全部探针同时失败，才判定为网关控制通路故障并重启；
- 只要还有任意一台探针正常，就认为网关是好的——单台设备的故障会被忽略并记日志，绝不会重启网关。
此外内置重启防抖（loop guard）：若 1 小时内自动重启 ≥3 次仍失败，判定为「非瞬时故障」（坏探针或网关硬件本身不可恢复），自动停止重启并显式报警，避免雪上加霜。
- HACS → 集成 → 右上角「自定义仓库」→ 类别选「集成」→ 填入本仓库 URL（
https://github.com/lenlanF/xiaomi_gateway3_watchdog）→ 添加。 - 在 HACS 里找到 Xiaomi Gateway3 Automation Watchdog → 下载 → 重启 Home Assistant。
- 「设置 → 设备与服务 → 添加集成」→ 搜索 Xiaomi Gateway3 Automation Watchdog。
把本仓库的 custom_components/xiaomi_gateway3_watchdog/ 整个文件夹复制到你的 HA 配置目录
（即和 configuration.yaml 同级的 custom_components/ 下），重启 HA 即可。
前置依赖：需先安装并配置好 xiaomi_gateway3，且网关的 Telnet 已开启（该集成运行时会自动保持 23 端口 Telnet 开启）。
添加集成时分两步：
第 1 步 · 选择网关
- 若已装 xiaomi_gateway3，会自动列出它配置里的网关 IP（直接选 / 也可手填）。
- 网关 IP 即 Telnet 重启的目标地址（xiaomi_gateway3 默认已在该 IP 的 23 端口开启 Telnet）。
第 2 步 · 探针与阈值
| 字段 | 说明 | 默认 |
|---|---|---|
| 探针实体 (switch/light) | 用于检测的设备 entity_id，多个用逗号或换行分隔（建议 ≥2 台常电设备） | 必填（≥1） |
| 探针模式 | 被动（不操作设备，靠在线状态判断）/ 主动（真实发指令并回读） |
被动 |
| 检测间隔（秒） | 多久做一次健康检查 | 600 |
| 指令超时（秒） | 等待状态翻转的最长时间（仅主动模式用） | 12 |
| 连续失败几次后重启 | 触发硬重启的阈值 | 3 |
| 重启后冷却（秒） | 重启后静默等待网关上线 | 240 |
| 失败时自动重启 | 是否开启自动硬重启 | 开 |
表决规则：只有所有探针同时失败才重启；任一探针正常即判健康，单台设备自身故障不会误重启。 重启防抖：1 小时内自动重启 ≥3 次仍失败 → 停止自动重启并报警（检查探针/网关硬件）。
| 实体 | 类型 | 作用 |
|---|---|---|
binary_sensor.<网关>_自动化健康 |
二元传感器 | on=网关能执行指令；off=不能执行。属性含连续失败次数、上次错误、上次重启时间、各探针明细、loop_guard |
button.<网关>_立即检测 |
按钮 | 立刻跑一次健康检查 |
button.<网关>_重启网关 |
按钮 | 立刻硬重启物理网关 |
switch.<网关>_自动重启 |
开关 | 开/关「连续失败自动重启」 |
这些实体都挂在名为「网关看门狗 」的设备下，可直接在仪表盘用，也可在自动化里用 button.press 调用。
Q：支持哪些网关？ A：所有被 xiaomi_gateway3 支持的型号——小米多模网关（Gateway 3，lumi.gateway.mgl03）、 小米多模网关 2 / Smart Home Hub（Mijia_Hub_V2）。 注意：老款「小米智能网关」（DGNWG02LM）不在 xiaomi_gateway3 支持列表，本集成也无法覆盖。
Q：重启靠什么？需要 token 吗？
A：走 xiaomi_gateway3 同款 Telnet reboot，按登录横幅自动识别型号
（MGW=admin/admin，MGW2/Hub=root/空密码），不需要单独提供 token，只要网关 IP 可达且 23 端口 Telnet 已开启
（xiaomi_gateway3 运行时会自动保持开启）。
Q：探针设备会被频繁开关，很烦？
A：默认就是「被动」模式，完全不操作设备，靠设备是否 available 判断，零闪烁零误操作。只有切到「主动」模式才会短暂切换（且检测完立即复位）。被动模式下甚至可以直接用一盏正常在用的灯当探针。
Q：会不会因为「探针设备自己坏了」导致健康网关被重启？ A：老版本会。现在已修复——支持多个探针 + 多数表决：只有全部探针同时失败才重启；只要有一台正常就判健康，单台设备自身故障（电池没电/被拔/出范围/坏掉）会被忽略并记日志，绝不误重启。 另外还有重启防抖：1 小时内自动重启 ≥3 次仍失败会停止自动重启并报警，杜绝「坏设备→无限重启健康网关」的死循环。建议至少配 2 台常电探针。
Q：只想监控、不想自动重启？
A：把「失败时自动重启」开关关掉即可。看门狗仍会标记 binary_sensor 为 off 并记日志，你手动点「重启网关」按钮。
Q：重启会不会影响其它正常设备？ A：会短暂断网（网关重启约 1 分钟），期间该网关下所有 Zigbee/BLE 设备暂时不可用，重启后自动恢复。这是修复「假死」的必要代价。
xiaomi_gateway3_watchdog/ # 仓库根（即 HACS 自定义仓库）
├── hacs.json # HACS 元数据
├── README.md # 本文件
├── LICENSE
├── .gitignore
└── custom_components/
└── xiaomi_gateway3_watchdog/ # HA 集成本体（整个文件夹复制到 config/custom_components/）
├── __init__.py
├── manifest.json
├── const.py
├── config_flow.py
├── coordinator.py # 看门狗核心：探针回环检测 + 失败计数 + 触发重启 + 防抖
├── shell.py # Telnet 硬重启（复刻 xiaomi_gateway3 源码，按横幅自动识别型号）
├── binary_sensor.py # 健康状态
├── button.py # 立即检测 / 重启网关
├── switch.py # 自动重启开关
└── translations/
├── en.json
└── zh-Hans.json