Tuya Smart Control CLI 技术文档：面向 AI Agent 的 IoT 设备命令行工具

概述

tuya-smart-control-cli 是涂鸦开源的 IoT 设备管理命令行工具，基于 Tuya Enduser API 封装，为开发者和 AI Agent 提供设备查询、控制、通知、数据统计等完整能力的命令行接口。

CLI 是 AI Agent 时代的基础设施形态——命令行是编程型 Agent 最成熟的交互方式，Agent 天生适合执行结构化的 CLI 指令。tuya-smart-control-cli 将涂鸦 3,000+ 设备品类的控制能力封装为标准命令行接口，使 AI Agent 操控 IoT 设备与调用 git、docker 等工具的方式完全一致。

维度	规格
设备品类	3,000+ 种智能硬件
全球覆盖	200+ 国家地区，7 大数据中心
运行环境	Node.js >= 18
开源协议	GitHub 开源
输出格式	人类可读表格 / JSON（--json）

一、架构设计

1.1 Enduser API 与 CLI 的关系

┌─────────────────────────────────────┐
│          AI Agent / 开发者           │
└──────────────┬──────────────────────┘
               │ 命令行调用
┌──────────────▼──────────────────────┐
│      tuya-smart-control-cli         │
│  ┌──────────────────────────────┐   │
│  │ 内置鉴权（签名/Token管理）      │   │
│  │ 参数格式化与校验                │   │
│  │ 输出格式化（Table/JSON）       │   │
│  │ 区域自动路由                   │   │
│  └──────────────────────────────┘   │
└──────────────┬──────────────────────┘
               │ HTTPS
┌──────────────▼──────────────────────┐
│        Tuya Enduser API             │
│  （设备管理/控制/通知/统计）            │
│        全球 7 大数据中心              │
└─────────────────────────────────────┘

分层职责：

层级	职责
Enduser API	底层能力层：设备列表、控制、数据查询、消息通知等完整 API
CLI	封装层：内置鉴权流程、参数格式化、区域路由，开箱即用

CLI 省去的是编写代码、处理签名和构造请求的步骤。身份验证和权限管理与直接调用 API 完全一致，API Key 等凭证仍需配置。

1.2 区域自动路由

API Key 格式为 sk-<PREFIX><rest>，前缀自动映射全球七大数据中心：

前缀	数据中心区域
cn	中国
us	美西
eu	欧洲
in	印度
…	其他区域

CLI 根据 Key 前缀自动识别所属区域并匹配对应服务端地址，无需手动配置。

二、安装与配置

2.1 环境要求

依赖	版本
Node.js	>= 18
API Key	中国区: tuyasmart.com / 海外区: tuya.ai

2.2 安装

git clone https://github.com/tuya/tuya-smart-control-cli.git
cd tuya-smart-control-cli
npm install
npm link

执行 npm link 后，tuya 命令全局可用。

2.3 配置

# 交互式配置（推荐）
tuya init

tuya init 引导输入 API Key，自动完成区域识别与服务端地址匹配。

2.4 连通性验证

tuya doctor

依次检查：配置文件 → API Key 有效性 → 网络连通性 → 账号家庭数据。

Tuya CLI Doctor
✔ Configuration file found
✔ API Key valid
✔ Network connectivity OK
✔ Home data accessible

全部 ✔ 即配置完成。

三、命令参考

3.1 设备管理（核心功能）

# 列出所有设备
tuya device list

# 查看设备详情（当前属性状态）
tuya device detail <device_id>

# 查看设备物模型（可操作属性定义）
tuya device model <device_id>

# 控制设备
tuya device control <device_id> --code <property> --value <value>

典型调试流程：

device list（定位设备）
  → device detail（确认当前状态）
  → device model（查看可操作属性）
  → device control（下发指令）

四步完成一轮设备调试，全程无需编写代码。

3.2 家庭与房间管理

# 列出所有家庭
tuya home list

# 查看家庭下的房间
tuya home rooms <home_id>

# 查看房间下的设备
tuya room devices <room_id>

3.3 天气查询

# 按经纬度查询天气
tuya weather --lat <latitude> --lon <longitude>

3.4 消息通知

支持四种通知通道，均发送给当前登录用户：

# 短信通知
tuya notify sms --content "设备离线告警"

# 语音电话
tuya notify voice --content "紧急告警"

# 邮件通知
tuya notify email --subject "日报" --content "..."

# App 推送
tuya notify push --content "设备状态变更"

3.5 数据统计

# 查看可用的统计配置
tuya stats list <device_id>

# 查询设备统计数据（如用电量）
tuya stats query <device_id> --code <stat_code> --start <date> --end <date>

3.6 JSON 输出

所有查询命令支持 --json 参数，输出结构化 JSON 数据：

# 导出设备列表为 JSON
tuya device list --json

# 配合 jq 使用
tuya device list --json | jq '.[] | select(.online == true)'

四、支持的控制类型

品类	支持的操作
照明	开关、亮度、色温、颜色模式
空调/暖通	开关、温度、模式、风速
插座/开关	开关、定时、功率统计
窗帘/电机	开关、位置百分比
传感器	状态查询、历史数据
清洁电器	开关、模式、状态
厨房电器	开关、温度、模式、定时
…	3,000+ 品类通过物模型统一抽象

当前不支持的操作： 门锁操作、图像处理、固件升级、设备配网/移除。这些操作需通过涂鸦 App 或完整 API 实现。

五、AI Agent 集成场景

5.1 Agent 直接调用

AI Agent（如 Claude Code、Cursor、OpenClaw 等）可在终端中直接执行 CLI 命令，与调用其他 CLI 工具的方式一致：

# Agent 查询设备状态后决策
tuya device detail <id> --json | agent_process

# Agent 执行控制指令
tuya device control <id> --code switch_1 --value true

5.2 批量运维脚本

配合 Shell 脚本和 cron 定时任务，实现轻量级自动化运维：

#!/bin/bash
# 每小时检查设备在线状态，离线设备发送告警
offline=$(tuya device list --json | jq '.[] | select(.online == false) | .name')
if [ -n "$offline" ]; then
  tuya notify sms --content "设备离线: $offline"
fi

5.3 典型应用场景

角色	场景	CLI 价值
硬件开发者	联调阶段设备调试	一条命令替代编写测试脚本
方案商	酒店/公寓设备批量管理	Shell 脚本替代管理后台开发
AI Agent 开发者	为 Agent 添加物理设备控制能力	命令行接口天然适配 Agent 执行方式
测试工程师	设备功能反复验证	终端批量运行测试用例

六、故障排查

运行 tuya doctor 自动检测大部分配置问题。常见错误码：

错误码	原因	处理方式
1000	API Key 无效或过期	重新获取 API Key
1001	签名验证失败	检查 Key 是否完整复制
1100	网络连接超时	检查网络环境及代理配置
2000	设备不存在	确认 device_id 是否正确
2001	设备离线	检查设备网络状态

七、技术竞争力分析

7.1 与传统 IoT 开发方式对比

维度	传统方式（直接调 API）	tuya-smart-control-cli
调试一台设备	编写脚本→引入SDK→处理签名→发请求→解析返回（~15min）	一条命令，几秒完成
鉴权处理	手动管理签名逻辑和 Token 生命周期	CLI 内置，透明处理
区域配置	手动查找并配置服务端地址	API Key 前缀自动路由
输出处理	自行解析 JSON 响应	内置 Table/JSON 双格式
AI Agent 集成	需封装 API 调用为可执行脚本	原生命令行，即装即用
批量运维	开发管理后台	Shell 脚本 + cron

7.2 设计优势

特性	技术价值
开源	可审计、可定制、可贡献
全球覆盖	7 大数据中心自动路由，无需手动切换
品类广度	3,000+ 品类通过物模型统一抽象，一套命令覆盖所有设备
Agent 友好	结构化 CLI 输出，天然适配 AI Agent 执行范式
JSON 输出	--json 参数支持管道处理与程序化集成
自诊断	tuya doctor 一键排查配置与连通性问题

八、资源链接

资源	地址
GitHub	https://github.com/tuya/tuya-smart-control-cli
API Key（中国大陆）	tuyasmart.com
API Key（海外）	tuya.ai