Tuya 本地控制

安装指南

1. ClawHub CLI 从源直接安装技能的最快方式。
   npx clawhub@latest install tuya-local-control
2. 手动安装 将技能文件夹复制到以下位置之一
   全局模式
   ~/.openclaw/skills/
   工作区
   /skills/
   优先级：工作区 > 本地 > 内置
3. 提示词安装 将此提示词复制到 OpenClaw 即可自动安装。
   请帮我使用 Clawhub 安装 tuya-local-control。如果尚未安装 Clawhub，请先安装（npm i -g clawhub）。
   更倾向于下载？
   获取包含原生技能文件的ZIP压缩包。
   下载技能 (.zip)

什么是

Tuya 本地控制可帮助你从脚本或本地仪表板读取设备状态，并切换 Tuya 或 Smart Life 插座、灯泡、传感器、恒温器和窗帘电机。它使用 tinytuya 通过本地网络与设备通信，在日常读取和写入期间避免依赖云端。
此技能会引导你通过 Tuya cloud API 获取每台设备的本地密钥（仅需一次），之后使用设备 ID、密钥、LAN IP 和协议版本进行本地控制。请妥善保密本地密钥，勿将其提交到版本控制中；每台设备都有各自的凭据。

应用场景

从本地脚本或仪表板读取 Tuya 或 Smart Life 设备状态。
在运行时不依赖云端，切换插座、灯泡、恒温器或其他受支持设备。
在局域网中发现设备 IP 地址并检查其 DPS 值。
确定控制设备功能的 DPS 键及其值类型。
基于经验证的读取和写入调用，构建本地 CLI、轮询循环或 Web 仪表板。
设备重新配对或固件重置后，通过获取更新后的密钥恢复本地访问。

工作原理

安装 tinytuya，并确认 Python 可以导入该库。
使用 tinytuya 扫描或路由器 DHCP 租约查找设备的 LAN IP。
创建并配置 Tuya IoT Platform 项目，启用 IoT Core，并关联 Tuya 或 Smart Life 应用账号。
将项目凭据和区域提供给随附的密钥获取脚本；该脚本会获取设备 ID 和本地密钥，并写入 tuya_devices.json。
运行本地状态脚本，使用已存储的设备详情连接并检查返回的 DPS 值。
如果设备没有响应，请验证其 IP，并尝试合适的协议版本，通常为 3.3 或 3.4。
使用 Tuya Device Debugging，或观察在应用中切换设备时的变化，确定 DPS 键及其预期值类型。
使用本地设置脚本写入一个或多个 DPS 值，然后通过读取状态以及（如适用）检查实体设备来验证更改。
将已验证的调用封装到所需的本地应用中；适当情况下复用设备连接，并在启动时加载设备配置。

配置指南

安装 tinytuya 并确认 Python 可以使用它：
pip install tinytuya
python -c "import tinytuya; print(tinytuya.version)"
扫描本地网络中的设备，或检查路由器的 DHCP 租约：
python -m tinytuya scan
在 Tuya IoT Platform 中创建项目、启用 IoT Core、关联应用账号，并记下 Access ID、Access Secret 和项目区域（eu、us、cn 或 in）。将凭据设置为 scripts/fetch_keys.py 所需的环境变量；此技能未指定这些变量的确切名称。
获取本地设备详情，然后通过设备名称或 ID 测试设备：
python scripts/fetch_keys.py
python scripts/local_status.py
确定 DPS 键及其预期类型后，设置一个 DPS 值：
python scripts/local_set.py
如需设置多个 DPS 值，请查看 local_set.py 脚本头部，了解其 JSON 参数格式。主机必须与设备位于同一 LAN 中；由于 tuya_devices.json 包含本地密钥，应将其排除在版本控制之外。

数据架构

此技能通过 scripts/fetch_keys.py 写入 tuya_devices.json。该文件包含本地控制所需详情的设备记录；文档说明的工作流程需要设备 ID、本地密钥和 LAN IP，并使用设备名称或 ID 选择记录。此技能未指定确切的 JSON 字段名称和完整架构。
数据 用途
设备 ID 标识用于本地通信的 Tuya 设备。
本地密钥 用于验证本地请求的设备专属凭据；请将其视为机密。
LAN IP 用于连接设备的网络地址。该地址可能因 DHCP 而变化。
协议版本 设备通信设置；此技能提及支持的版本包括 3.1、3.3 和 3.4。
DPS 值 由 status() 返回、以数字键标识的设备状态和控制值；根据设备不同，值可能为布尔值、整数或字符串。
随附脚本包括用于配置密钥的 scripts/fetch_keys.py、用于读取 DPS 状态的 scripts/local_status.py，以及用于写入一个或多个 DPS 值的 scripts/local_set.py。请妥善保管设备文件；如果重新配对或固件重置导致密钥失效，请重新获取密钥。

高级特性

初次通过云端配置密钥后即可在本地运行；日常设备读取和写入无需互联网连接。
检查原始 DPS 状态，并使用
set_value(dps, value)
写入单个值，或使用
set_multiple_values({...})
写入多个值。
排查空响应或负载错误时，可选择设备协议版本；文档指出 3.3 是常见默认版本。
构建轮询循环、CLI 和仪表板等更高级的本地工具，并在适当情况下复用设备连接。
考虑 LAN 限制、变化的 DHCP 地址、本地密钥轮换，以及只允许一个活动本地 TCP 写入方的设备。

name: "tuya-local-control" description: "Control Tuya / Smart Life devices locally over LAN: fetch local keys once via the Tuya cloud API, then read and write DPS with tinytuya."

Tuya local control

Use when the user wants to read state or switch Tuya / Smart Life devices (plugs, bulbs, sensors, thermostats, curtain motors) from a script or local dashboard — without depending on the Tuya/Smart Life app or the cloud at runtime.

Tuya devices answer a local protocol on TCP port 6668. To talk to them you need three things per device: its device id, its local key, and its LAN IP. The app keeps the local key, so you fetch it once from the Tuya cloud API and then everything runs locally.

Only control devices you own. Local keys are per-device secrets — keep tuya_devices.json out of git and never paste keys into chat.

Steps

Install the library. pip install tinytuya. Completion: python -c "import tinytuya; print(tinytuya.version)" prints a version.

Find the device on the LAN. Optional but the fastest way to learn the IP and the protocol version. Run python -m tinytuya scan (or tinytuya.deviceScan()), or read the device list from your router's DHCP leases. Completion: you have an IP for the device. Devices are often at a fixed DHCP lease, but the IP can change — re-check before blaming the code.

Fetch device ids + local keys from the cloud (one time). Create a free Tuya IoT Platform project, enable IoT Core, and link your Smart Life / Tuya app account to it (Devices → Link App Account). Note the project's Access ID / Client ID and Access Secret / Client Secret, plus the region (eu, us, cn, in). Put them in environment variables and run the bundled scripts/fetch_keys.py. Completion: tuya_devices.json exists and lists at least one device with a local key.

Probe the device locally. Run scripts/local_status.py . It opens a tinytuya.Device with the stored id + key + IP and calls status(). If it fails, try the other protocol version (3.3 vs 3.4) — this is the single most common cause of an empty or refused response. Completion: you get a JSON blob of DPS values.

Map the DPS you care about. The status() JSON is a dict of numeric DPS keys to values (e.g. "1": true, "20": 210). Read the device's DPS meaning from the Tuya IoT Platform "Device Debugging" tab or by toggling the device in the app and watching which key changes. Completion: you can name the exact DPS key and value type for the function you want to drive.

Write a value. Run scripts/local_set.py (see the script header for the JSON form used to set several DPS at once). Completion: local_status.py shows the new value, and if it is a physical output the device actually switched.

Wrap it. Once the read + write calls are proven, put them behind whatever the user asked for: a CLI, a poll loop, a local web dashboard. Cache the device object and reuse the connection; re-read the device JSON on startup, not on every call.

Notes and pitfalls

version matters. Tuya devices speak protocol 3.1, 3.3, or 3.4. Passing the wrong one gives an empty response or payload error, not a helpful message. Try each; 3.3 is the usual default.
Local keys rotate. Re-pairing a device in the app, or a firmware reset, invalidates the stored key. If local calls suddenly fail while the device is online in the app, re-run the key fetch.
The cloud is only needed for provisioning. After tuya_devices.json exists, all reads and writes are LAN-local — no internet required.
LAN only. The host running the script must be on the same network as the device (no VPN isolation, no guest-network client isolation).
One writer at a time. Some Tuya devices tolerate only a single local TCP session; a second client can make the first one time out.
Cloud API free tier. The IoT Core free trial ties a project to one app account and expires; when it does, only the cloud key fetch stops working. Local control keeps working with the keys you already saved.
Use set_value(dps, value) for a single DPS and set_multiple_values({...}) for several at once; values must match the type the device expects (bool / int / str).

Bundled scripts

scripts/fetch_keys.py — read Access ID/Secret from the environment, call the cloud API, write tuya_devices.json.
scripts/local_status.py — connect locally by device name or id and print the DPS status.
scripts/local_set.py — connect locally and write one DPS (or several via a JSON argument).
AI-HIVE 客户跟进助手
AI-HIVE 办公任务交付