Tuya-Local 完整教程三步把涂鸦设备搬进 Home Assistant彻底脱离云端【免费下载链接】tuya-localLocal support for Tuya devices in Home Assistant项目地址: https://gitcode.com/GitHub_Trending/tu/tuya-local如果你的涂鸦设备还靠云端中转那么Tuya-Local值得装一个它是 Home Assistant 的第三方集成用局域网直连的方式控制运行涂鸦固件的 WiFi 设备命令毫秒级直达、断网也能照常工作还可能解锁云端 API 没开放的隐藏功能。本文覆盖安装、device_id / local_key / IP 三件套的获取、三阶段配置流程以及断连、协议版本选错、命令过载这些真实用户最常踩的坑。一、先划重点它能做什么又要注意什么装之前把预期对齐能省掉后面 90% 的疑惑。能做到的本地直连Home Assistant 和涂鸦设备在局域网内直接通信不再经过 Tuya 服务器响应更快、更稳定功能解锁不少设备的完整功能甚至整台设备只有本地协议才支持云端 API 根本碰不到多设备直连一次集成配置可以管理多台涂鸦设备覆盖 1000 种已支持机型从空调、除湿机到电暖器、智能插座、门锁、扫地机都有对应档案。必须知道的边界情况说明电池供电设备门窗传感器、烟雾报警等为了省电不支持本地常连无法通过本集成控制网关/子设备支持但有限制网关能维持的本地连接数通常只有 1~3 条子设备数量因此受限隐私本集成不阻断设备向涂鸦云上报状态它的价值是速度、可靠性与功能解锁不是安全隔离手段单一本地连接很多涂鸦设备只允许一个本地连接。SmartLife / Tuya app、其他本地类集成若占着设备本机就会连不上二、配置前的准备拿到三件套配置 Tuya-Local 只需要三样东西设备 IP或主机名、device_id、local_key。有两条路线可以拿到它们推荐新手走第一条。路线 A云端辅助获取推荐在集成的配置流程里直接登录你的 Tuya 或 SmartLife 账号集成会引导你完成认证并自动列出账号下所有设备选中目标设备后device_id 和 local_key 会预填好如果本地发现没有被其他集成或复杂网络挡住IP 也会自动填上接着直接进入设备类型选择见下文第三部分。这条路线免去了注册 Tuya IoT 开发者账号的麻烦——后者现在把密钥查询能力的试用权限限成了一个月、且每 6 个月才能续一次相当折腾。一个小技巧认证 token 只有几小时有效期集成不会保存它但只要不重启 Home Assistant你可以连续添加多台设备只在第一台时认证一次。路线 B手动获取适合想完全自主掌控、或路线 A 走不通的情况。完整步骤可参考仓库内文档DEVICE_DETAILS.md。核心路径如下device_id登录 Tuya 开发者门户 → Cloud → 设备列表即可看到每台设备的 Device ID注意确认页面顶部的服务器区域选对了。local_key仍在开发者门户 → API Explorer → Devices Management → 选择Query Device Details in Bulk把 device_id 用逗号分隔填入结果里就能看到 local_key。IP 地址两个来源路由器后台的 DHCP 客户端列表里找设备用底层库 tinytuya 的向导在 HA 主机上扫描局域网pip install tinytuya python -m tinytuya wizard向导会依次询问 API KeyAccess ID / Client ID、API Secret、任一已注册设备 ID、区域等之后把局域网内可本地连接的设备连同 IP 找出来写进devices.json——里面的id、key、node_id子设备用正好就是配置所需的信息。⚠️两个容易翻车的点重新配对 local_key 作废。任何一次用厂商 app 重新配网后旧 key 立即失效需要重新获取IP 一栏虽然可以填Auto让集成自己发现但只要有 localtuya 在跑、app 本地连着设备、或网络不是简单的单子网发现就会失败且重连性能明显差于固定 IP。能在路由器里给设备绑定静态 IP就尽量绑。三、HACS 安装 三阶段配置流程第 0 步装集成第三方集成统一走 HACS。装好 HACS 后添加本仓库为自定义集成仓库即可像普通集成一样安装。第 1 阶段填连接信息进入设置 → 设备与集成 → 添加集成 → 选择 Tuya Local按顺序填写四项配置项必填说明host是设备 IP 或主机名建议绑定静态 IPdevice_id是涂鸦设备唯一 IDlocal_key是本地通信密钥重新配对后会变protocol_version是协议版本auto、3.1、3.2、3.3、3.4、3.5、3.22不确定协议版本就选auto。但有一类设备是重灾区部分 3.2 / 3.22 / 个别 3.4 设备会被误判为 3.3或反过来表现为设备在线但指令时灵时不灵——此时手动在这几个版本间切换试试。3.22 是特殊值用于开启 device22 检测有些设备被识别为 3.3 却需要用 3.2 才能正常工作3.3 下可能变成只读。提交后会尝试实际连接并读取数据。注意一个隐蔽的坑3.1 协议设备里local_key 只在发送指令时才用到所以 key 填错也能通过这一步等你真正去控制设备才暴露问题——而较新的协议版本会用 key 解密数据错了当场报错。第 2 阶段选设备类型系统会根据设备实际返回的数据点dps筛选出至少部分匹配的机型清单已排除确定不匹配的项总池子有 1000 份配置档案存放在 custom_components/tuya_local/devices/完整清单见 DEVICES.md。选对类型决定了设备在 Home Assistant 里生成哪些实体灯光、空调、传感器……。两个提醒选错了就删掉重配。不同类型生成不同实体原地改类型不干净官方也不建议这么干预期中的机型没出现多半是固件版本不同可以按 devices 目录的 README 流程补一份配置。第 3 阶段命名给设备起一个唯一名称它会成为所有实体的名称前缀。同类设备多台时按房间 功能命名例如客厅_电暖器最省心。四、断连与不听话高频问题排查表症状先查这里时断时连① 设备与 HA 是否同一网段② 关掉局域网里所有连着该设备的 app③ 确认没有其他本地涂鸦集成在抢这条唯一连接能连但控制无响应 / 状态不更新协议版本被误判手动切换 3.2 / 3.3 / 3.4 / 3.22 逐一测试配网后配置突然失效重新配对过local_key 已变重新获取断网一段时间后设备变傻部分涂鸦设备长时间连不上 Tuya 服务器会停止响应属于固件行为有反馈称同时屏蔽 DNS 和 TCP 后离线表现更好自动化里连发指令导致设备重启/掉线几十秒见下方自动化调优自动化调优多数涂鸦设备扛不住快速连发多条指令——轻则丢状态重则重启或离线 30 秒到几分钟。集成内置的限流能合并/排队部分指令但跨实体的并发、以及不支持指令合并的机型仍会翻车。经验法则连续指令之间留0.5~2 秒延迟具体下限以自己的设备实测为准多设备自动化可以把 A 设备的第二条指令排到最后发利用处理其他设备的时间差冷却支持批量的平台如 climate 的set_temperature顺带写预设、light 的turn_on一次带多项会把多项合并成一条消息但个别设备只接受单条单 dp 的指令同样需要实测取舍。五、进阶方向与资源索引子设备经网关用网关的 device_id、IP、local_key再加子设备的node_id没有就用uuidnode_id 用 tinytuya 向导查。Tuya Zigbee 设备通常就是标准 Zigbee 设备用 ZHA / Zigbee2MQTT 接往往更省事部分新款网关还支持 Matter over WiFi可两条路都试试只用本集成兜底不工作的设备。红外 / 射频模块暴露为 remote 实体支持学习与发送指令还能通过send_learned_ir_command服务把学到的指令发给其他红外发射器。给社区提新设备设备未被识别时取消配置流程后去 HA 日志找LOCAL DPS记录——这是写新配置档案的核心素材提 issue 时请连同品牌型号一并附上。设备配置文件的格式规范见 devices 目录文档。版本同步设备偶尔会固件升级或同型号卖出不兼容版本在清单里不等于必然可用遇到不工作优先确认固件与协议版本。把三件套备齐、三个阶段走完你的涂鸦设备就已经跑在局域网里了。剩下的就是给自动化加上合适的延迟然后享受低延迟的本地控制。【免费下载链接】tuya-localLocal support for Tuya devices in Home Assistant项目地址: https://gitcode.com/GitHub_Trending/tu/tuya-local创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考