SwitchBot OpenAPI

概述

switchbot-openapi 是面向SwitchBot生态系统的官方API集成技能，基于HTTPS协议对接OpenAPI v1.1，提供完整的设备发现、状态监控与指令下发能力。该技能通过预置的Node CLI工具与Bash脚本，将复杂的HMAC-SHA256签名认证流程封装为开箱即用的命令行接口，显著降低开发者集成门槛。

核心用法

技能采用环境变量认证模式，用户需配置SWITCHBOT_TOKEN与SWITCHBOT_SECRET后，通过switchbot_cli.js执行操作：

• 设备发现: list 命令返回完整设备清单，含familyName、roomID等空间元数据
• 状态查询: status <deviceId> 获取设备实时状态（电量、开关状态、传感器读数等）
• 指令控制: cmd <deviceId> <command> 支持全品类设备操控，涵盖开关、亮度调节、风速设置、锁具控制等
• 场景执行: scenes与scene <sceneId> 支持自动化场景查询与触发

针对特殊设备类型提供精细化参数支持：窗帘百分比定位（0-100）、智能锁死锁控制、扫地机器人清洁模式JSON配置、空调IR遥控全参数集（温度/模式/风速/电源）等。IR DIY设备通过--commandType=customize支持自定义按键映射。

显著优点

1. 官方权威性: 直接对接SwitchBot官方API，非逆向破解方案，协议稳定性与向后兼容性有保障
2. 全品类覆盖: 支持20+设备类型，从基础开关(Bot)、窗帘(Curtain)、门锁(Lock)到扫地机器人、空气净化器、AI艺术相框等前沿品类
3. 工程化封装: 内置HMAC签名生成、nonce管理、timestamp校准，开发者无需关注认证细节
4. 空间感知: 通过设备列表自动推导家庭(Family)→房间(Room)→设备的层级关系，弥补API无独立空间端点的设计局限
5. 混合执行能力: 提供Node CLI（功能完整）与纯curl脚本（轻量部署）双轨方案，适配不同运行环境

潜在局限

1. 云端依赖: 所有设备控制需经SwitchBot云服务中转，局域网直连能力缺失，网络中断即失效
2. 速率限制: 日调用上限10,000次，高频自动化场景（如每秒状态轮询）可能触发限流
3. 异步延迟: Keypad密码管理操作采用异步webhook回调模式，无法同步获取执行结果
4. IR能力边界: 空调IR仅支持setAll全参数设置，不支持独立温度或模式调节；部分设备返回statusCode 160时需降级至场景执行
5. BLE预检要求: 蓝牙直连设备（Bot、Lock、Curtain等）需确保Hub设备在线且云服務启用，否则CLI预检将阻断操作

适合人群

• 智能家居自动化开发者，需程序化控制SwitchBot设备
• 家庭用户构建跨平台场景联动（如Home Assistant桥接）
• 企业级部署需批量设备管理的技术运维人员

常规风险

• 凭证泄露: Token/Secret具备完整设备控制权限，需严格环境变量隔离，避免提交至版本控制
• 物理安全: 门锁、车库门开启类指令需二次确认机制，防止误操作导致安全隐患
• API配额耗尽: 循环脚本或未优化的轮询逻辑可能导致服务中断
• IR信号冲突: 自定义IR指令可能与设备原生协议不兼容，建议先验证再生产部署

核心用法

SwitchBot OpenAPI Skill 是一款面向智能家居场景的代理工具技能，通过调用 SwitchBot 官方 OpenAPI v1.1 接口，实现对全屋智能设备的统一控制与状态查询。用户需预先配置 SWITCHBOT_TOKEN 和 SWITCHBOT_SECRET 环境变量完成身份认证。

该技能提供双模式操作路径：Node CLI 模式（推荐）与 Bash 脚本模式。Node CLI 封装了 HMAC-SHA256 签名生成逻辑，支持设备列表查询、状态获取、指令下发、场景执行等核心功能；Bash 脚本则适合快速测试与轻量级调用。覆盖设备类型极为丰富：从基础的 Bot 开关、Curtain 窗帘、Lock 系列门锁，到 Color Bulb 智能灯具、Robot Vacuum 扫地机器人、Air Purifier 空气净化器、Humidifier 加湿器，乃至 IR 红外遥控设备与 AI Art Frame 艺术相框等，均提供标准化指令集。

特色功能包括：支持 Curtain/Blind Tilt 精确位置调节（0-100%）、Keypad 密码锁动态密钥管理、扫地机器人多模式清洁调度、以及通过设备列表反向解析 Family/Room 层级结构的智能空间管理能力。所有通信基于 HTTPS 加密，采用 HMAC 签名验证机制，每日 API 调用限额 10,000 次。

显著优点

官方生态深度整合：直接对接 SwitchBot 官方 API，与原生 App 功能对齐，支持 30+ 设备类型与 200+ 具体指令，覆盖智能家居全场景需求。

零依赖轻量架构：Node.js 脚本仅使用内置模块（crypto、https），无第三方 npm 依赖，从根本上杜绝供应链投毒风险，部署简洁可靠。

安全凭证管理：强制通过环境变量注入 Token/Secret，无硬编码风险，符合最小权限原则与 GDPR/CCPA 合规要求。

智能空间感知：创新性地从设备元数据中提取 Family/Room 层级关系，弥补 OpenAPI 缺乏独立空间管理端点的局限，支持"查看客厅所有设备"类自然语言查询。

场景化指令封装：复杂指令如扫地机器人 startClean 的 JSON 参数、窗帘 setPosition 的格式转换均内置处理，用户无需记忆底层协议细节。

潜在缺点与局限性

凭证配置门槛：必须手动获取并配置 Token/Secret，对非技术用户存在学习成本；凭证泄露将导致设备控制权丧失。

API 速率限制：每日 10,000 次调用上限对高频自动化场景可能构成瓶颈，大规模部署需设计调用缓存与合并策略。

异步操作盲区：Keypad 密钥创建/删除等指令为异步执行，结果通过 Webhook 返回，Skill 本身不内置 Webhook 接收能力，需外部系统配合。

BLE 设备前置依赖：Bot、Lock、Curtain 等蓝牙设备需通过 Hub 桥接并开启 Cloud Services，否则 API 返回 160 错误码，增加硬件成本与配置复杂度。

IR 设备功能受限：空调 IR 遥控仅支持 setAll 聚合指令，无法单独调节温度/模式；DIY 自定义红外需预先在 App 中配置按钮映射。

适合的目标群体

• 智能家居重度用户：已部署 SwitchBot 多品类设备，追求跨平台自动化编排的进阶玩家
• 开发者与极客：希望将 SwitchBot 设备集成至自研 Home Assistant、Node-RED 或自定义 Agent 系统的技术人员
• 租房改造群体：需快速搭建可迁移的轻量级智能家居方案，避免传统智能家居的布线改造
• 小型办公空间运营者：需批量管理会议室窗帘、灯光、空调等设备，实现定时场景切换

使用风险

性能风险：高频轮询设备状态可能快速消耗 API 配额，建议实现本地状态缓存与增量更新机制。

依赖项风险：运行时依赖 Node.js 环境及系统工具链（curl、openssl、jq、uuidgen），容器化部署需确保基础镜像完整性。

误操作风险：门锁解锁、车库门开启等敏感指令无内置二次确认，脚本调用场景需额外防护逻辑。

时间同步风险：HMAC 签名依赖 13 位毫秒时间戳，系统时间漂移超过阈值将导致认证失败，需配置 NTP 服务。

供应链风险：尽管当前零依赖，若未来引入第三方库，需严格执行版本锁定与审计流程。