什么是 SwitchBot OpenAPI 控制？

此技能通过官方 OpenAPI v1.1 实现了与 SwitchBot 生态系统的无缝交互。它提供了一套强大的脚本和 CLI 工具，用于管理 Bot、窗帘、网关和锁等设备，无需为每次请求手动计算复杂的 HMAC 签名。通过利用 Openclaw Skills，开发者和高级用户可以自动化他们的智能家居环境，查询实时设备状态，并通过统一且对开发者友好的界面执行复杂命令。

该技能旨在处理身份验证和协议管理等繁重工作，让代理能够专注于执行用户意图。无论您是管理单个设备还是复杂的智能家居硬件网络，此集成都能确保与全球多个地区的 SwitchBot 云基础设施进行可靠通信。

下载入口:https://github.com/openclaw/skills/tree/main/skills/switchbot-dev/switchbot-cloudapi

安装与下载

1. ClawHub CLI

从源直接安装技能的最快方式。

2. 手动安装

将技能文件夹复制到以下位置之一

优先级：工作区 > 本地 > 内置

3. 提示词安装

将此提示词复制到 OpenClaw 即可自动安装。

SwitchBot OpenAPI 控制 应用场景

• 根据日程安排自动化家庭日常任务，如开启窗帘或调节恒温器。
• 在 Openclaw Skills 工作流中检查智能锁和环境传感器的实时状态。
• 将 SwitchBot 设备集成到自定义仪表板或第三方自动化平台中。
• 执行在 SwitchBot 应用中创建的场景，以实现复杂的跨设备协同。
• 监控物联网设备的电池电量和连接状态，以确保系统健康。

1. 代理使用提供的 SWITCHBOT_TOKEN 和 SWITCHBOT_SECRET 环境变量向 SwitchBot 云进行身份验证。
2. 对于每个请求，技能会使用令牌、时间戳和随机 Nonce 动态生成所需的 HMAC-SHA256 签名。
3. 技能查询设备列表端点以识别可用硬件，并验证特定设备是否已启用云服务。
4. 通过 HTTPS POST 请求将 turnOn、turnOff 或 setPosition 等命令发送到区域 OpenAPI v1.1 端点。
5. 如果设备不支持通过 API 直接发送命令，技能将提供触发预定义场景的后备机制。

SwitchBot OpenAPI 控制 配置指南

要开始使用此技能，请确保您的 SwitchBot 设备已连接到网关，并且在移动应用中启用了“云服务”。然后，配置您的环境：

# 1. 设置您的 OpenAPI 凭据
export SWITCHBOT_TOKEN="your_openapi_token"
export SWITCHBOT_SECRET="your_openapi_secret"
export SWITCHBOT_REGION="global" # 选项：global, na, eu, jp

# 2. 通过列出设备来测试连接
./scripts/list_devices.sh

# 3. 通过 Node.js CLI 控制设备
node scripts/switchbot_cli.js cmd  turnOn

SwitchBot OpenAPI 控制 数据架构与分类体系

该技能通过一组结构化的脚本和参考文件组织其操作，以确保 Openclaw Skills 部署的一致性：

name: switchbot-openapi
description: Control and query SwitchBot devices using the official OpenAPI (v1.1). Use when the user asks to list SwitchBot devices, get device status, or send commands (turn on/off, press, set mode, lock/unlock, set temperature, curtain open %, etc.). Requires SWITCHBOT_TOKEN and SWITCHBOT_SECRET.

SwitchBot OpenAPI Skill

This skill equips the agent to operate SwitchBot devices via HTTPS requests to the official OpenAPI. It includes ready-to-run scripts and curl templates; use these instead of re-deriving the HMAC signature each time.

Quick Start (Operator)

1. Set environment variables in the OpenClaw Gateway/container:

• SWITCHBOT_TOKEN: your OpenAPI token
• SWITCHBOT_SECRET: your OpenAPI secret
• SWITCHBOT_REGION (optional): default global (api.switch-bot.com). Options: global, na, eu, jp.

2. Test a call (list devices):

• Bash: scripts/list_devices.sh
• Node: node scripts/switchbot_cli.js list

3. Common tasks:

• Get a device status: node scripts/switchbot_cli.js status
• Turn on: node scripts/switchbot_cli.js cmd turnOn
• Turn off: node scripts/switchbot_cli.js cmd turnOff
• Press (bot): node scripts/switchbot_cli.js cmd press
• Curtain 50%: node scripts/switchbot_cli.js cmd setPosition --pos=50
• Lock/Unlock (Lock): node scripts/switchbot_cli.js cmd lock / unlock

API Notes (concise)

Base URL by region:

• global: https://api.switch-bot.com
• na: https://api.switch-bot.com
• eu: https://api.switch-bot.com
• jp: https://api.switch-bot.com

Use path prefix /v1.1.

Headers (required):

• Authorization:
• sign: HMAC-SHA256 of (token + timestamp + nonce) using SECRET, Base64-encoded
• t: milliseconds epoch as string
• nonce: random UUID
• Content-Type: application/json

Key endpoints:

• GET /v1.1/devices
• GET /v1.1/devices/{deviceId}/status
• POST /v1.1/devices/{deviceId}/commands
  • body: { "command": "turnOn|turnOff|press|lock|unlock|setPosition|setTemperature|setMode|setVolume", "parameter": "", "commandType": "command" }
• Scenes (fallback when a model has no public commands):
  • GET /v1.1/scenes
  • POST /v1.1/scenes/{sceneId}/execute

Notes on limitations:

• Some models (e.g., certain Robot Vacuum lines) do NOT expose direct commands in OpenAPI v1.1. When a command returns {statusCode:160, message:"unknown command"}, create a Scene in the SwitchBot app (e.g., "Vacuum Start") and execute it via the Scenes API.

For command parameters, see references/commands.md. Scenes usage examples are in references/examples.md.

How the Agent Should Use This Skill

• Prefer running the provided scripts. They compute signatures and handle retries.
• Preflight guard: the CLI checks device capabilities before sending commands. For Bluetooth-class devices (e.g., Bot/Lock/Curtain), it requires enableCloudService=true and a non-empty hubDeviceId. If missing, it aborts with a clear fix (bind a Hub and enable Cloud Services in the SwitchBot app).
• If environment variables are missing, ask the user to provide/define them securely (do not log secrets).
• For sensitive actions (e.g., unlock), require explicit confirmation and optionally a one-time code if the user enables it.
• On errors with code 190/TokenInvalid or 100/Unauthorized: re-check token/secret, time drift, or signature composition.

Files

• scripts/switchbot_cli.js — Node CLI for list/status/commands
• scripts/list_devices.sh — curl listing
• scripts/get_status.sh — curl status
• scripts/send_command.sh — curl command
• references/commands.md — parameters for common devices
• references/examples.md — example invocations and JSON outputs

Keep this SKILL.md lean; consult references/ for details.