SwitchBot OpenAPI

SwitchBot OpenAPI Skill 是专为 SwitchBot 智能家居生态设计的官方 API 控制工具，基于 OpenAPI v1.1 实现全品类设备的远程操控与状态查询。

核心用法：本技能提供完整的 HTTPS API 封装，包含 Bash 脚本和 Node.js CLI 两种调用方式。用户需配置 SWITCHBOT_TOKEN 和 SWITCHBOT_SECRET 环境变量后，即可通过简洁的命令行指令完成设备发现、状态获取和指令下发。CLI 工具内置 HMAC-SHA256 签名自动生成机制，无需手动处理加密逻辑，显著降低使用门槛。

覆盖设备：支持 SwitchBot 全系列产品线，包括但不限于：Bot（按压开关）、Curtain/Curtain 3（窗帘电机，支持百分比开合）、Lock 系列（智能门锁，含反锁控制）、Color Bulb/Strip Light（照明设备，支持色温/亮度/色彩调节）、各类风扇（含自然风模式、定时关闭）、Robot Vacuum 全系列扫地机器人（支持清扫模式、吸力档位、自清洁）、Blind Tilt（百叶窗调节）、Humidifier 加湿器、Air Purifier 空气净化器、Smart Radiator Thermostat 温控器、Relay Switch 继电器、Garage Door Opener 车库门、Video Doorbell 可视门铃、Candle Warmer Lamp 融蜡灯、AI Art Frame 艺术相框，以及 Keypad 系列智能门锁键盘和全品类 IR 红外遥控设备（空调、电视、DIY 自定义）。

显著优点：① 官方 API 背书，协议稳定可靠，与硬件同步更新；② 签名机制自动处理，CLI 开箱即用；③ 设备支持度极高，覆盖消费级全品类；④ 提供 Scene 场景执行能力，支持复杂自动化；⑤ 日调用额度 10,000 次，满足家庭级高频使用。

潜在局限：① 需要硬件配合云端服务（Hub + Cloud Services），纯 BLE 设备需通过 Hub 中转；② Keypad 系列指令为异步执行，结果需通过 webhook 接收，增加集成复杂度；③ 部分设备指令受限（如 IR 空调仅支持 setAll 完整参数模式，不支持单独调节）；④ 状态码 160 表示设备不支持特定指令，需降级至 Scene 方案；⑤ 依赖网络环境，API 故障时将完全失联。

适合人群：SwitchBot 生态深度用户、智能家居自动化开发者、需要将 SwitchBot 设备接入第三方平台（如 Home Assistant、Node-RED）的技术爱好者，以及追求官方稳定性的企业级 IoT 集成场景。

常规风险：Token 与 Secret 属于高敏感凭证，泄露将导致设备被恶意操控；建议严格通过环境变量注入，禁止硬编码或日志输出。API 调用频次受限于 10,000 次/日，大规模自动化需合理规划轮询策略。

核心用法

SwitchBot OpenAPI Skill 是一套面向智能家居场景的官方设备控制能力封装。用户配置 SWITCHBOT_TOKEN 和 SWITCHBOT_SECRET 环境变量后，即可通过 Node CLI 或 Bash 脚本执行全品类设备操作。核心能力覆盖三大层级：

设备发现与状态监控：支持列举所有已绑定设备、查询实时状态（电量、开关状态、亮度、温度等传感器数据）。

精细化设备控制：涵盖 Bot（按压开关）、Curtain（窗帘百分比开合）、Lock 系列（门锁/反锁）、Light（色温/亮度/色彩调节）、Fan（风速/模式/夜灯）、Robot Vacuum（清扫/回充/吸力等级）、Blind Tilt（百叶窗角度）、Humidifier/Purifier（模式设定）、以及 IR 红外遥控（空调/电视/自定义）等 20+ 设备类型。

场景自动化：支持列举和执行预定义场景（Scenes），实现一键触发多设备联动。

显著优点

安全架构规范：零第三方依赖，仅使用 Node.js 原生 https 模块与系统工具；凭证严格通过环境变量隔离，代码内无硬编码密钥；采用 HMAC-SHA256 签名认证，符合官方 API 安全标准。

协议透明可控：所有请求仅发往 SwitchBot 官方域名（api.switch-bot.com），HTTPS/TLS 1.2+ 全程加密，无数据外泄风险。

功能覆盖全面：支持 v1.1 版本全部设备类型与指令集，从基础开关到复杂的 Keypad 密码管理、Robot Vacuum Pro 组合清洁模式均可调用。

CLI 即拿即用：预置脚本自动处理签名生成、时间戳与 nonce 管理，开发者无需重复实现加密逻辑；Bash 与 Node 双版本适配不同运行环境。

隐私保护到位：不采集用户个人信息，日志脱敏处理，符合 GDPR 数据最小化原则。

潜在缺点与局限性

异步操作限制：Keypad 密码创建/删除等指令为异步执行，结果需通过 Webhook 接收，CLI 无法直接返回操作成功状态。

IR 设备约束：红外空调仅支持 setAll 综合指令，不支持单独调节温度或模式；自定义 IR 设备需用户预先在 App 中配置按钮名称。

网络与配额依赖：完全依赖云端 API，设备离线或网络中断时无法本地控制；每日 10,000 次调用限额对高频自动化场景可能构成瓶颈。

BLE 设备前置条件：Bot、Lock、Curtain 等蓝牙设备需配合 Hub 并开启 Cloud Services 才能实现远程控制。

错误处理粒度：设备 ID 本地无格式预验证，无效 ID 将导致服务端返回错误；部分设备返回 160 状态码表示指令不支持，需降级使用 Scenes。

适合的目标群体

智能家居进阶用户：已部署 SwitchBot 生态，追求跨平台自动化脚本与语音助手集成的技术型用户。

IoT 开发与运维工程师：需要批量管理设备、构建自定义监控面板或集成至 Home Assistant 等第三方平台的开发者。

小型办公空间管理员：希望通过定时任务统一控制会议室窗帘、灯光、空调等设备，实现节能与场景化办公。

隐私敏感型用户：排斥第三方云服务中转，要求数据直连官方且本地无敏感信息残留的安全意识用户。

使用风险与注意事项

凭证泄露风险：Token 与 Secret 一旦泄露，攻击者可远程操控全部设备。建议定期轮换凭证，使用 .env 文件或专用密钥管理服务，避免提交至 Git 仓库或暴露在进程列表中。

权限隔离建议：避免以 root 权限运行 CLI，推荐创建专用低权限账户或容器化部署，降低潜在漏洞影响面。

API 限额监控：高频轮询状态或自动化脚本可能快速消耗日限额，建议实施本地缓存策略并监控异常调用模式（401/403 认证失败、160 设备不支持错误）。

设备兼容性验证：部分新型设备或固件版本可能存在指令差异，生产环境使用前建议在沙箱环境验证指令兼容性。

Webhook 可靠性：依赖异步回调的功能需确保接收端稳定可用，否则无法确认操作最终状态。