Tuya Smart Home Device Control Skill

Basic Information

Official Website: https://www.tuya.com/
Source Code: https://github.com/tuya/tuya-openclaw-skills
Authentication: Via Header Authorization: Bearer {Api-key}
Credentials: Read from environment variable TUYA_API_KEY. The base URL is auto-detected from the API key prefix (e.g. sk-AY... → China, sk-EU... → Europe). You can override by setting TUYA_BASE_URL.
API Reference: See individual files under references/
Python SDK: See scripts/tuya_api.py, which provides a TuyaAPI class for calling all APIs directly

Environment Variable Configuration

Set the following environment variable before use:

export TUYA_API_KEY="your-tuya-api-key"
# TUYA_BASE_URL is optional — auto-detected from API key prefix
# Override only if needed: export TUYA_BASE_URL="https://openapi.tuyaus.com"

API Key Prefix → Data Center Mapping

The base URL is automatically resolved from the first two characters after sk- in the API key:

| Prefix | Region | Base URL | |--------|--------|----------| | AY | China Data Center | https://openapi.tuyacn.com | | AZ | US West Data Center | https://openapi.tuyaus.com | | EU | Central Europe Data Center | https://openapi.tuyaeu.com | | IN | India Data Center | https://openapi.tuyain.com | | UE | US East Data Center | https://openapi-ueaz.tuyaus.com | | WE | Western Europe Data Center | https://openapi-weaz.tuyaeu.com | | SG | Singapore Data Center | https://openapi-sg.iotbing.com |

How to obtain an API key:

China Mainland users: Get from https://tuyasmart.com/
International users: Get from https://tuya.ai/
Different regions use different API service domains, which must match your account registration region

The skill will not load if the TUYA_API_KEY environment variable is missing.

Usage

Method 1: Via Python SDK (Recommended)

The skill provides scripts/tuya_api.py, containing a TuyaAPI class that encapsulates all API call logic. Usage:

import sys
sys.path.insert(0, "{baseDir}/scripts")
from tuya_api import TuyaAPI

# Initialize from environment variables (recommended)
api = TuyaAPI()

# Query all homes
homes = api.get_homes()

# Query all devices
devices = api.get_all_devices()

# Query device detail
detail = api.get_device_detail("0620068884f3eb414579")

# Control device
result = api.issue_properties("0620068884f3eb414579", {"switch_led": True, "bright_value": 500})

# Query weather
weather = api.get_weather(lat="39.9042", lon="116.4074")

Method 2: Via Command Line

With the environment variable set, simply pass the command:

python3 {baseDir}/scripts/tuya_api.py <command> [params...]

# Examples
python3 {baseDir}/scripts/tuya_api.py homes
python3 {baseDir}/scripts/tuya_api.py devices
python3 {baseDir}/scripts/tuya_api.py device_detail 0620068884f3eb414579
python3 {baseDir}/scripts/tuya_api.py control 0620068884f3eb414579 '{"switch_led":true}'

Method 3: Via curl

curl -s -H "Authorization: Bearer $TUYA_API_KEY" "$TUYA_BASE_URL/v1.0/end-user/homes/all"

Feature Overview

| Module | Capabilities | Reference | |--------|-------------|-----------| | Home Management | List all homes, list rooms in a home | references/home-and-space.md | | Device Query | All devices, devices by home, devices by room, single device detail (including current property states) | references/device-query.md | | Device Control | Query device Thing Model, issue property commands | references/device-control.md | | Device Management | Rename device | references/device-management.md | | Weather Service | Current and forecast weather | references/weather.md | | Notifications | SMS, voice call, email, App push | references/notifications.md | | Data Statistics | Hourly statistics config query, statistics value query | references/statistics.md |

Core Workflows

Workflow 1: Device Control

When the user says things like "turn on the living room light" or "set the AC temperature to 26 degrees":

Locate the device — Find the target device based on the device name or location mentioned by the user
- User only mentions device name (e.g. "AC") -> Call the "List All Devices" API, fuzzy-match by device name
- User mentions location + device name (e.g. "living room AC") -> First query the home list, then query room list to match "living room", then list devices in that room
- If multiple devices match, list all candidates and ask the user to choose
Get current state — Call the "Get Single Device Detail" API. The properties field in the response contains the current values of each functional property (e.g. switch state, brightness level, temperature setting), which can be used to determine the device's current state
Query capabilities — With the device_id, call the "Query Device Thing Model" API to get the device's supported property list and understand each property's type and value range
Map the command — Map the user's intent to Thing Model properties:
- Turn on/off -> Find a bool-type switch property (e.g. switch_led, switch)
- Adjust brightness -> Find a value-type brightness property
- Adjust temperature -> Find a value-type temp property
- If the device does not support the requested function, inform the user
Issue the command — Call the "Issue Properties" API, assembling the property code and target value as a JSON string
Return the result — Inform the user whether the operation succeeded

Workflow 2: Rename Device

Locate the device using Workflow 1 Step 1 to obtain the device_id
Call the "Rename Device" API with the new name
Return the result

Workflow 3: Notifications

Identify the message type: SMS / Voice / Email / App Push
Extract required parameters (message content; email also needs a subject)
Call the corresponding API (all notification APIs are self-send — messages can only be sent to the current logged-in user)
Return the send result

Workflow 4: Weather Query

Obtain the user's latitude and longitude (ask the user or infer from context)
Determine which weather attributes to query (default: temperature, humidity, weather condition)
Call the weather query API
Translate the returned data into a human-readable description

Workflow 5: Data Statistics

Locate the device (same as Workflow 1 Step 1)
Call the "Statistics Config Query" API to confirm whether the device has the corresponding statistics capability
If available, call the "Statistics Value Query" API to get data for the specified time range
Aggregate and return the results

API Calling Convention

Request Format

All APIs use the configured Base URL concatenated with the path. Examples:

GET {base_url}/v1.0/end-user/homes/all
POST {base_url}/v1.0/end-user/devices/{device_id}/shadow/properties/issue

Response Format

APIs return a unified structure:

Success response:

{
  "success": true,
  "t": 1710234567890,
  "result": { ... }
}

Error response:

{
  "success": false,
  "code": 1108,
  "msg": "uri path invalid"
}

When success is true, the result is in the result field
When success is false, error details are in the code and msg fields

Error Handling

| Scenario | How to Handle | |----------|--------------| | Device not found | Tell the user: "Cannot find a device named XX, please verify the device name" | | Device does not support the function | Tell the user: "Device XX does not support XX function", and list the device's supported functions | | Home/room not found | Tell the user: "Cannot find a home/room named XX" | | Multiple devices match | List all matching devices and ask the user to choose | | Notification send failure | Return the specific error code explanation (rate limit, format error, etc.) | | token invalid (code: 1010) | Tell the user the Api-key has expired and needs to be updated | | uri path invalid (code: 1108) | Check whether the API path is correct | | API call failure | Tell the user: "Service is temporarily unavailable, please try again later" | | Other unresolvable issues | Guide the user to visit the GitHub repository for announcements and troubleshooting: https://github.com/tuya/tuya-openclaw-skills |

Supported and Unsupported Operations

Supported Property Types for Control

Only basic data type properties are currently supported for device control:

| Type | Description | Example | |------|-------------|---------| | bool | Boolean on/off | Turn light on/off, turn AC on/off, turn plug on/off | | enum | Enumeration selection | Switch AC mode (auto/cold/hot), set fan speed (low/mid/high) | | value (Integer) | Numeric value | Adjust brightness (0-1000), set temperature (16-30) | | string | String value | Set device display text |

Unsupported Operations

The following operations involve sensitive actions or complex data types and are NOT supported:

Lock control — Unlock doors, lock/unlock smart locks (security-sensitive)
Video/camera operations — Pull live video streams, view camera footage, capture screenshots
Image operations — Retrieve or push images from/to devices
Complex data type control — Properties with raw, bitmap, struct, or array typeSpec are not supported for issuing commands
Firmware upgrades — OTA firmware update operations
Device pairing/removal — Adding new devices or removing existing devices

If the user requests any of these unsupported operations, clearly inform them that the operation is not available through this skill and suggest using the Tuya App directly.

Data Egress Statement

This skill sends data to the Tuya Open Platform:

| Data Type | Sent To | Purpose | Required | |-----------|---------|---------|----------| | Api-key | User-configured base_url | API authentication | Required | | Device ID | User-configured base_url | Device query and control | Required | | Control commands | User-configured base_url | Device property issuance | Required |

Important Notes

Device name matching uses fuzzy matching; when multiple results are found, ask the user to confirm
When issuing properties, the properties field value is a JSON string (requires escaping), not a JSON object
The statistics API time format is yyyyMMddHH, and the time range cannot exceed 24 hours
All four notification APIs are self-send only — messages can only be sent to the currently logged-in user
The weather query requires latitude and longitude parameters; if the user does not provide them, ask for their city and convert to coordinates
Different regions use different base_url values — these are auto-detected from the API key prefix, but can be overridden with TUYA_BASE_URL if needed
If you encounter any issues during use, please visit the GitHub repository for the latest announcements and usage guides: https://github.com/tuya/tuya-openclaw-skills