SwitchBot OpenAPI

Control and query SwitchBot devices using the official OpenAPI (v1.1). Use when the user asks to list SwitchBot devices, get device status, send commands, qu...

copies: implexa run clawhub/switchbot-cloudapi

view source

installs

stars

karma

SkillRank score ↗

7.3/ 10

evaluated by implexa, claude-haiku-4-5 · 2026-05-26

switchbot-cloudapi bridges agents to switchbot devices via official openapi v1.1, covering 20+ device types with ready-to-run cli scripts. uniquely handles family/room/home hierarchy extraction from device list responses.

structure

8.0

trigger phrases

9.0

procedure

8.0

edge cases

5.0

documentation

7.0

strengths

view original SKILL.md from clawhubclick to expand

---
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, send commands, query families/rooms/homes, or manage scenes. **This is the ONLY skill that can query 家庭信息, 房间信息, family, room, and home data.** Always use this skill when the user mentions 家庭, 房间, family, room, or home in the context of SwitchBot. Requires SWITCHBOT_TOKEN and SWITCHBOT_SECRET.
metadata:
  openclaw:
    requires:
      env:
        - SWITCHBOT_TOKEN
        - SWITCHBOT_SECRET
      bins:
        - node
        - curl
        - openssl
        - jq
        - uuidgen
---

# SwitchBot OpenAPI Skill

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

## Quick Start (Operator)

1) Set environment variables:
- SWITCHBOT_TOKEN: your OpenAPI token
- SWITCHBOT_SECRET: your OpenAPI secret

2) Test (list devices):
- Bash: `scripts/list_devices.sh`
- Node: `node scripts/switchbot_cli.js list`

3) Common tasks:

**Basic controls:**
- List devices: `node scripts/switchbot_cli.js list`
- Get status: `node scripts/switchbot_cli.js status <deviceId>`
- Turn on/off: `node scripts/switchbot_cli.js cmd <deviceId> turnOn` / `turnOff`
- Toggle: `node scripts/switchbot_cli.js cmd <deviceId> toggle`
- Press (Bot): `node scripts/switchbot_cli.js cmd <deviceId> press`

**Curtain / Curtain 3:**
- Set position: `node scripts/switchbot_cli.js cmd <deviceId> setPosition --pos=50`
  (0=open, 100=closed; CLI auto-formats to `0,ff,50`)
- Pause: `node scripts/switchbot_cli.js cmd <deviceId> pause`

**Lock / Lock Pro / Lock Ultra / Lock Lite:**
- Lock/Unlock: `node scripts/switchbot_cli.js cmd <deviceId> lock` / `unlock`
- Deadbolt: `node scripts/switchbot_cli.js cmd <deviceId> deadbolt`

**Lights (Color Bulb / Strip Light / Floor Lamp / Strip Light 3 / RGBICWW etc.):**
- Set color: `node scripts/switchbot_cli.js cmd <deviceId> setColor --param="255:100:0"`
- Set brightness: `node scripts/switchbot_cli.js cmd <deviceId> setBrightness --param=80`
- Set color temp: `node scripts/switchbot_cli.js cmd <deviceId> setColorTemperature --param=4000`

**Fans (Battery Circulator Fan / Circulator Fan / Standing Circulator Fan):**
- Wind mode: `node scripts/switchbot_cli.js cmd <deviceId> setWindMode --param=natural`
- Wind speed: `node scripts/switchbot_cli.js cmd <deviceId> setWindSpeed --param=50`
- Night light: `node scripts/switchbot_cli.js cmd <deviceId> setNightLightMode --param=1`
- Auto-off timer: `node scripts/switchbot_cli.js cmd <deviceId> closeDelay --param=3600`

**Robot Vacuum S1/S1 Plus/K10+/K10+ Pro:**
- Start: `node scripts/switchbot_cli.js cmd <deviceId> start`
- Stop: `node scripts/switchbot_cli.js cmd <deviceId> stop`
- Dock: `node scripts/switchbot_cli.js cmd <deviceId> dock`
- Suction: `node scripts/switchbot_cli.js cmd <deviceId> PowLevel --param=2`

**Robot Vacuum K10+ Pro Combo / K20+ Pro / S10 / S20 / K11+:**
- Start clean: `node scripts/switchbot_cli.js cmd <deviceId> startClean --param='{"action":"sweep_mop","param":{"fanLevel":2,"waterLevel":1,"times":1}}'`
- Pause/Dock: `node scripts/switchbot_cli.js cmd <deviceId> pause` / `dock`
- Volume: `node scripts/switchbot_cli.js cmd <deviceId> setVolume --param=50`
- Self clean (S10/S20): `node scripts/switchbot_cli.js cmd <deviceId> selfClean --param=1`

**Weather Station:**
- Set custom quote: `node scripts/switchbot_cli.js cmd <deviceId> customQuote --param="大海啊，你好多的水啊！"`
  (Max 100 characters; displayed on the AI Recommendations page)
- Remove custom quote: `node scripts/switchbot_cli.js cmd <deviceId> cancelCustom --param=default`
- Set custom page text: `node scripts/switchbot_cli.js cmd <deviceId> customPage --param="自定义页面文本"`
  (Max 100 characters)

**Blind Tilt:**
- Set position: `node scripts/switchbot_cli.js cmd <deviceId> setPosition --param="up;60"`
- Fully open: `node scripts/switchbot_cli.js cmd <deviceId> fullyOpen`
- Close: `node scripts/switchbot_cli.js cmd <deviceId> closeUp` / `closeDown`

**Roller Shade:**
- Set position: `node scripts/switchbot_cli.js cmd <deviceId> setPosition --param=50`

**Humidifier (original):**
- Set mode: `node scripts/switchbot_cli.js cmd <deviceId> setMode --param=auto`

**Evaporative Humidifier / Auto-refill:**
- Set mode: `node scripts/switchbot_cli.js cmd <deviceId> setMode --param='{"mode":7,"targetHumidify":60}'`
- Child lock: `node scripts/switchbot_cli.js cmd <deviceId> setChildLock --param=true`

**Air Purifier (VOC/PM2.5/Table):**
- Set mode: `node scripts/switchbot_cli.js cmd <deviceId> setMode --param='{"mode":2,"fanGear":2}'`
- Child lock: `node scripts/switchbot_cli.js cmd <deviceId> setChildLock --param=1`

**Smart Radiator Thermostat:**
- Set mode: `node scripts/switchbot_cli.js cmd <deviceId> setMode --param=1`
- Set temp: `node scripts/switchbot_cli.js cmd <deviceId> setManualModeTemperature --param=22`

**Relay Switch 1PM / 1 / 2PM:**
- Toggle: `node scripts/switchbot_cli.js cmd <deviceId> toggle`
- Set mode: `node scripts/switchbot_cli.js cmd <deviceId> setMode --param=0`
- 2PM channel: `node scripts/switchbot_cli.js cmd <deviceId> turnOn --param="1"` (channel 1 or 2)

**Garage Door Opener:**
- Open/Close: `node scripts/switchbot_cli.js cmd <deviceId> turnOn` / `turnOff`

**Video Doorbell:**
- Motion detection: `node scripts/switchbot_cli.js cmd <deviceId> enableMotionDetection` / `disableMotionDetection`

**Candle Warmer Lamp:**
- Brightness: `node scripts/switchbot_cli.js cmd <deviceId> setBrightness --param=50`

**AI Art Frame:**
- Next/Previous: `node scripts/switchbot_cli.js cmd <deviceId> next` / `previous`
- Upload image (URL): `node scripts/switchbot_cli.js cmd <deviceId> uploadImage --param='{"imageUrl":"https://example.com/photo.jpg"}'`
- Upload image (Base64): `node scripts/switchbot_cli.js cmd <deviceId> uploadImage --param='{"imageBase64":"<base64_string>"}'`
- ⚠️ `imageUrl` and `imageBase64` are mutually exclusive. Max 10 images; statusCode 402 = limit reached.

**Keypad / Keypad Touch / Keypad Vision / Keypad Vision Pro:**
- Create passcode: `node scripts/switchbot_cli.js cmd <deviceId> createKey --param='{"name":"Guest","type":"permanent","password":"12345678"}'`
- Delete passcode: `node scripts/switchbot_cli.js cmd <deviceId> deleteKey --param='{"id":"11"}'`
- ⚠️ Keypad commands are async — results come via webhook.

**IR Remote - Air Conditioner:**
- Set all: `node scripts/switchbot_cli.js cmd <deviceId> setAll --param="26,2,1,on"`
  (format: temperature, mode, fan speed, power state)
  - mode: 0/1=auto, 2=cool, 3=dry, 4=fan, 5=heat
  - fan: 1=auto, 2=low, 3=medium, 4=high
  - power: on/off

**IR Remote - TV:**
- Channel: `node scripts/switchbot_cli.js cmd <deviceId> SetChannel --param=5`
- Volume: `node scripts/switchbot_cli.js cmd <deviceId> volumeAdd` / `volumeSub`

**IR Remote - Others (DIY):**
- Custom button: `node scripts/switchbot_cli.js cmd <deviceId> <buttonName> --commandType=customize`

**Scenes (fallback):**
- List scenes: `node scripts/switchbot_cli.js scenes`
- Execute scene: `node scripts/switchbot_cli.js scene <sceneId>`

## API Reference

Base URL: `https://api.switch-bot.com`
Path prefix: `/v1.1`
Daily limit: 10,000 API calls

Headers (all required):
- Authorization: `<SWITCHBOT_TOKEN>`
- sign: HMAC-SHA256(`token + t + nonce`, secret), Base64-encoded
- t: 13-digit millisecond timestamp
- nonce: random UUID

Key endpoints:
- `GET /v1.1/devices` — list all devices
- `GET /v1.1/devices/{deviceId}/status` — device status
- `POST /v1.1/devices/{deviceId}/commands` — send command
- `GET /v1.1/scenes` — list scenes
- `POST /v1.1/scenes/{sceneId}/execute` — execute scene

Command body format:
```json
{
  "command": "<commandName>",
  "parameter": "<string|object>",
  "commandType": "command"
}
```
For IR "Others" (DIY) devices, use `"commandType": "customize"`.

## Querying Families & Rooms

The OpenAPI does not have a dedicated families/rooms endpoint. Instead, extract this info from the device list response (`GET /v1.1/devices`).

Each device in `deviceList` includes:
- `familyName` — the family/home it belongs to
- `roomID` — room identifier (`"defaultRoom"` means no specific room assigned)
- `roomName` — room display name (`null` if default room)

**When the user asks about families, homes, or rooms:**

1. Call `node scripts/switchbot_cli.js list` to get the full device list
2. Group devices by `familyName` to get all families
3. Within each family, group by `roomName` (treat `null`/`"defaultRoom"` as "未分配房间")
4. Present the family → room → device hierarchy

Example output format:
```
🏠 Home
  └─ 未分配房间: 设备A, 设备B, ...
  └─ 客厅: 设备C, ...

🏠 测试
  └─ 未分配房间: 设备D, ...
```

**Note:** IR remote devices (`infraredRemoteList`) only have `hubDeviceId`, no `familyName`/`roomName`. To determine their family, match their `hubDeviceId` to a device in `deviceList` and use that device's family.

## Agent Guidelines

- Always use the provided CLI scripts — they handle HMAC signatures automatically.
- The CLI runs preflight checks for BLE devices (Bot, Lock, Curtain, Blind Tilt) — requires Hub + Cloud Services enabled.
- For IR Air Conditioner, only `setAll` is supported (not separate setMode/setTemp).
- For Keypad commands (createKey/deleteKey), results are async via webhook.
- If a command returns statusCode 160, the device may not support that command — use Scenes as fallback.
- Never log tokens/secrets. Ask user to set them as environment variables.

## Files

- `scripts/switchbot_cli.js` — Node CLI (list/status/cmd/scenes)
- `scripts/list_devices.sh` — curl: list devices
- `scripts/get_status.sh` — curl: get status
- `scripts/send_command.sh` — curl: send command
- `scripts/list_scenes.sh` — curl: list scenes
- `scripts/execute_scene.sh` — curl: execute scene
- `references/commands.md` — complete command reference per device type
- `references/examples.md` — usage examples

don't have the plugin yet? install it then click "run inline in claude" again.

added explicit decision points for device types and edge cases, structured inputs with auth setup guidance, broke procedure into numbered steps with input/output contracts, clarified rate limits and retry logic, and added outcome signals showing success states.

SwitchBot OpenAPI Skill

intent

this skill lets you control and query any SwitchBot device (bots, locks, curtains, lights, vacuums, thermostats, IR remotes, keypads, etc.) via the official SwitchBot OpenAPI v1.1. use it whenever a user asks to list devices, check device status, send a command, query family/room/home structures, or execute scenes. this is the only skill that can fetch family, room, and home data from SwitchBot. the skill includes ready-to-run Node CLI scripts and bash wrappers that handle HMAC-SHA256 signature generation automatically, so you never derive crypto by hand.

inputs

environment variables (required):

SWITCHBOT_TOKEN: your SwitchBot OpenAPI token (get it from your SwitchBot account settings, OAuth scope: read/write devices and scenes)
SWITCHBOT_SECRET: your SwitchBot OpenAPI secret (paired with token above)

external connection:

HTTPS to https://api.switch-bot.com/v1.1 (SwitchBot cloud API, v1.1)
rate limit: 10,000 calls per day (shared across all callers using the same token)

binaries required:

node (v14+): runs the CLI scripts
curl: fallback for API calls if Node is unavailable
openssl: HMAC-SHA256 signature generation (bash scripts)
jq: JSON parsing (bash scripts)
uuidgen: random UUID for nonce headers

script files provided:

scripts/switchbot_cli.js: main Node CLI (list, status, cmd, scenes)
scripts/list_devices.sh: curl-based device listing
scripts/get_status.sh: curl-based device status
scripts/send_command.sh: curl-based command sending
scripts/list_scenes.sh: curl-based scene listing
scripts/execute_scene.sh: curl-based scene execution
references/commands.md: full command reference per device type
references/examples.md: usage examples

procedure

step 1: list all devices and extract families/rooms

input: SWITCHBOT_TOKEN, SWITCHBOT_SECRET, node binary
run: node scripts/switchbot_cli.js list
output: JSON array with each device containing deviceId, deviceName, deviceType, familyName, roomID, roomName, plus IR remote list
note: IR remotes only have hubDeviceId, no familyName/roomName attached directly

step 2 (optional): group devices by family and room

input: device list from step 1
action: iterate through deviceList, collect unique familyName values
for each family, group by roomName (treat null or "defaultRoom" as "unassigned room")
output: hierarchical structure (family > room > device names)

step 3: get device status (single device)

input: SWITCHBOT_TOKEN, SWITCHBOT_SECRET, deviceId
run: node scripts/switchbot_cli.js status <deviceId>
output: JSON object with device state fields (e.g., power, temperature, brightness, position)
note: response shape varies by device type

step 4: send command to device

input: SWITCHBOT_TOKEN, SWITCHBOT_SECRET, deviceId, command, optional parameter
run: node scripts/switchbot_cli.js cmd <deviceId> <command> [--param=<value>] [--pos=<value>]
output: JSON response with statusCode and optional message
statusCode 200: command accepted
statusCode 160: device does not support that command (fallback to scenes)
statusCode 402: resource limit reached (e.g., Keypad image upload limit)
statusCode 4xx/5xx: auth error, malformed request, or server error

step 5: execute a scene

input: SWITCHBOT_TOKEN, SWITCHBOT_SECRET, sceneId
run: node scripts/switchbot_cli.js scene <sceneId>
output: JSON response with statusCode
note: use this if a device command fails with statusCode 160

step 6: list all available scenes

input: SWITCHBOT_TOKEN, SWITCHBOT_SECRET
run: node scripts/switchbot_cli.js scenes
output: JSON array of scenes with sceneId, sceneName, sceneType

decision points

if user asks to control a specific device type:

if device type is Bot/Lock/Curtain/Blind Tilt: CLI checks for Hub + Cloud Services enabled (preflight); skip if already checked
if device type is IR Remote (Air Conditioner): only setAll is supported (temp, mode, fan, power in one call); do not attempt separate setMode/setTemp commands
if device type is IR Remote (TV): use channel and volume commands; custom buttons use commandType: customize
if device type is Keypad: createKey/deleteKey commands are async via webhook; results are not immediate
else (all other device types): send command directly via step 4

if user asks about families, rooms, or homes:

run step 1 to fetch full device list
run step 2 to group by family and room
if user asks about IR remotes: match their hubDeviceId to a Hub device in deviceList, then use that Hub's familyName
output hierarchical family > room > device listing

if a device command returns statusCode 160 (device does not support command):

offer to execute a Scene as fallback instead
fetch scene list (step 6) and ask user to pick one

if environment variables are missing:

halt immediately; ask user to set SWITCHBOT_TOKEN and SWITCHBOT_SECRET as env vars
do not log or echo token/secret values

if rate limit is hit (10,000 calls/day exceeded):

inform user that token is rate-limited for the day
suggest waiting until the next day or splitting requests across multiple tokens

if network timeout or 5xx error from SwitchBot API:

retry up to 2 times with exponential backoff (1s, 2s)
if still failing, inform user that SwitchBot cloud API is temporarily unavailable

if IR remote device has no matching Hub in deviceList:

note that the remote cannot be located in a family; ask user to verify Hub is paired and synced

output contract

device list (step 1):

{
  "statusCode": 200,
  "body": {
    "deviceList": [
      {
        "deviceId": "device-uuid",
        "deviceName": "Living Room Light",
        "deviceType": "ColorBulb",
        "enableCloudService": true,
        "hubDeviceId": "hub-uuid",
        "familyName": "Home",
        "roomID": "room-uuid",
        "roomName": "Living Room"
      }
    ],
    "infraredRemoteList": [
      {
        "deviceId": "remote-uuid",
        "deviceName": "AC Remote",
        "deviceType": "AirConditioner",
        "hubDeviceId": "hub-uuid"
      }
    ]
  }
}

device status (step 3):

{
  "statusCode": 200,
  "body": {
    "deviceId": "device-uuid",
    "deviceType": "ColorBulb",
    "power": "on",
    "brightness": 80,
    "colorTemperature": 4000,
    "color": "255:100:0"
  }
}

command response (step 4):

{
  "statusCode": 200,
  "body": {
    "result": true
  }
}

scene list (step 6):

{
  "statusCode": 200,
  "body": {
    "sceneList": [
      {
        "sceneId": "scene-uuid",
        "sceneName": "Movie Time",
        "sceneType": "manual"
      }
    ]
  }
}

error response (any step):

{
  "statusCode": 401,
  "body": {
    "message": "Unauthorized"
  }
}

all timestamps in responses are 13-digit millisecond Unix timestamps. all device IDs and scene IDs are UUIDs. all string parameters in commands are JSON-encoded (e.g., {"mode":2,"fanGear":2}).

outcome signal

user can confirm a device was controlled: device status changes immediately in the SwitchBot app (within 1-2 seconds for cloud-connected devices, or up to 10 seconds for BLE devices via Hub)
user can confirm device status was fetched: returned JSON matches the current state in the SwitchBot app
user can confirm family/room structure was retrieved: device list shows family names and room assignments; you can present them in a human-readable hierarchy
user can confirm a scene executed: scene effects apply to all devices in that scene (lights turn on, locks unlock, etc.) as defined in the SwitchBot app
if a command fails, statusCode will be non-200 (most commonly 160, 401, 402, 429, or 5xx); user sees the error code and message so they know what went wrong and can retry or adjust

SwitchBot OpenAPI

related skills

SwitchBot OpenAPI Skill

intent

inputs

procedure

decision points

output contract

outcome signal