Tuya Smart Control

tuya-smart-control is an official AI Agent skill for the OpenClaw platform, built on Tuya's 2C end-user APIs. It brings developers the industry's broadest AI...

Security Scan

The skill's code, runtime instructions, and requested environment variable are coherent with a Tuya end‑user control integration; nothing appears disproportionate or unrelated to its stated purpose.

Purpose & Capability

Name, description, SKILL.md, and the included Python SDK all align with a Tuya 2C end‑user API integration. The only minor inconsistency: the registry metadata lists no homepage/source while SKILL.md claims an official repo (https://github.com/tuya/tuya-openclaw-skills) and Tuya domains — this is a provenance/attribution note but does not change capability alignment.

Instruction Scope

Runtime instructions and the SDK only read TUYA_API_KEY (and optional TUYA_BASE_URL) and call Tuya API endpoints described in the references. The skill does not instruct reading unrelated files, system credentials, or exfiltrating data to third‑party endpoints beyond the Tuya base URLs.

Install Mechanism

This is instruction‑only with an embedded script file and no install spec; SKILL.md lists a pip dependency on 'requests' which is proportionate. Nothing is downloaded from arbitrary URLs or written to unexpected system locations.

Credentials

Only TUYA_API_KEY (primary credential) is required, which is appropriate for controlling a user's Tuya devices. The skill optionally accepts TUYA_BASE_URL to override the data center — reasonable for multi‑region support.

Persistence & Privilege

Skill is not force‑included (always:false) and uses standard autonomous invocation defaults. It does not request system or cross‑skill configuration changes.

Assessment

This skill appears to do what it says: control Tuya devices using a TUYA_API_KEY. Before installing, verify the skill's provenance (confirm the claimed GitHub repo or official Tuya origin) and only provide an API key scoped to your end‑user account. Be aware the skill can send notifications (SMS/voice/email/push) to the account's bound contacts — ensure you trust the skill to avoid unwanted messages. If you need stronger assurance, inspect the included scripts (scripts/tuya_api.py) yourself or obtain the skill directly from Tuya/OpenClaw official sources.

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":

1. 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
2. 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
3. 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
4. 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
5. Issue the command — Call the "Issue Properties" API, assembling the property code and target value as a JSON string
6. Return the result — Inform the user whether the operation succeeded

Workflow 2: Rename Device

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

Workflow 3: Notifications

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

Workflow 4: Weather Query

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

Workflow 5: Data Statistics

1. Locate the device (same as Workflow 1 Step 1)
2. Call the "Statistics Config Query" API to confirm whether the device has the corresponding statistics capability
3. If available, call the "Statistics Value Query" API to get data for the specified time range
4. 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

1. Device name matching uses fuzzy matching; when multiple results are found, ask the user to confirm
2. When issuing properties, the properties field value is a JSON string (requires escaping), not a JSON object
3. The statistics API time format is yyyyMMddHH, and the time range cannot exceed 24 hours
4. All four notification APIs are self-send only — messages can only be sent to the currently logged-in user
5. The weather query requires latitude and longitude parameters; if the user does not provide them, ask for their city and convert to coordinates
6. 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
7. 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