核心用法
SwitchBot OpenAPI Skill 是官方认证的智能家居控制接口，通过 HTTPS 调用 SwitchBot 云服务实现对全系列设备的远程操控。核心功能覆盖四大维度：
1. 设备发现与状态监控
- 调用
GET /v1.1/devices获取完整设备清单，自动解析家庭(family)、房间(room)层级关系 - 实时查询设备状态（电量、温度、湿度、开关状态、窗帘位置等）
- 支持 30+ 种设备类型：从基础开关(Bot)到复杂系统（扫地机器人、空气净化器、可视门铃）
2. 精细化设备控制
- 照明系统：色彩/色温/亮度三联调节，支持 RGBICWW 全彩设备
- 环境控制：窗帘精准定位(0-100%)、加湿器模式设定、空调全参数控制(温度/模式/风速)
- 安防设备：智能门锁上锁/解锁/保险舌控制，键盘密码管理（支持临时/永久密码）
- 清洁机器人：S10/S20 系列支持扫拖一体调度、自清洁、吸力/水量分级设定
3. 家庭结构查询（独家功能）
- 唯一支持查询家庭/房间信息的官方途径
- 通过设备列表逆向解析
familyName+roomName，构建家庭→房间→设备三级视图 - 自动处理 IR 红外设备的归属推断（通过 hubDeviceId 关联）
4. 场景自动化
- 列出并执行预设场景(scene)，作为复杂指令的降级方案（statusCode 160 时自动 fallback）
显著优点
- 官方背书：直接对接 SwitchBot 官方云 API，非逆向/破解方案，稳定性与兼容性最佳
- 设备覆盖极广：从 2018 年初代 Bot 到 2024 年 S20 扫地机器人、AI 艺术相框全系支持
- 安全认证完善：HMAC-SHA256 签名机制，Token + Secret 双因子，无明文传输
- CLI 工具成熟：内置 Node.js CLI 自动处理签名、时戳、nonce，开发者零摩擦接入
- 房间管理独特：竞品多忽略空间维度，此技能原生支持家庭/房间层级可视化
潜在局限
- 网络依赖：纯云端 API，设备需通过 SwitchBot Hub 联网，局域网直连能力缺失
- IR 设备限制：红外遥控器仅支持
setAll聚合指令，无法单参数调节；部分 DIY 按钮需自定义 commandType - Keypad 异步性：创建/删除密码操作结果通过 webhook 回调，非即时响应
- 图片上传限制：AI 艺术相框最多存储 10 张，超量返回 402 错误需用户自行清理
- 日调用限额：10,000 次/天，高频自动化场景可能触顶
- BLE 设备预检：Bot/Lock/Curtain 等蓝牙设备需确认 Hub 云服务功能开启，否则指令失败
适合人群
- SwitchBot 生态深度用户，拥有 5+ 设备需统一管理
- 多家庭/多房间场景的房东、民宿运营者
- 开发者构建跨平台智能家居中枢（Home Assistant 等）
- 需远程监控家中温湿度、门锁状态的安全敏感用户
常规风险
- 凭证泄露：Token/Secret 一旦泄露，攻击者可远程控制所有设备，须严格环境变量隔离
- 门锁误操作：unlock/deadbolt 指令无二次确认，自动化脚本需加条件判断
- 窗帘/卷帘夹伤：
setPosition指令执行时未检测障碍物，需确保安装合规 - 扫地机器人误启动：
startClean可能在工作时间自动运行，需配合时间窗口限制 - API 限流突发：自动化高频 polling 可能耗尽日配额，建议状态变更用 webhook 替代轮询