# Send SwitchBot OpenAPI to your agent Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually. ## Fast path - Download the package from Yavira. - Extract it into a folder your agent can access. - Paste one of the prompts below and point your agent at the extracted folder. ## Suggested prompts ### New install ```text I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete. ``` ### Upgrade existing ```text I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run. ``` ## Machine-readable fields ```json { "schemaVersion": "1.0", "item": { "slug": "switchbot-cloudapi", "name": "SwitchBot OpenAPI", "source": "tencent", "type": "skill", "category": "开发工具", "sourceUrl": "https://clawhub.ai/switchbot-dev/switchbot-cloudapi", "canonicalUrl": "https://clawhub.ai/switchbot-dev/switchbot-cloudapi", "targetPlatform": "OpenClaw" }, "install": { "downloadUrl": "/downloads/switchbot-cloudapi", "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=switchbot-cloudapi", "sourcePlatform": "tencent", "targetPlatform": "OpenClaw", "packageFormat": "ZIP package", "primaryDoc": "SKILL.md", "includedAssets": [ "README-CLAWHUB.md", "SKILL.md", "_meta.json", "scripts/execute_scene.sh", "scripts/get_status.sh", "scripts/list_devices.sh" ], "downloadMode": "redirect", "sourceHealth": { "source": "tencent", "slug": "switchbot-cloudapi", "status": "healthy", "reason": "direct_download_ok", "recommendedAction": "download", "checkedAt": "2026-05-09T15:05:42.006Z", "expiresAt": "2026-05-16T15:05:42.006Z", "httpStatus": 200, "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=switchbot-cloudapi", "contentType": "application/zip", "probeMethod": "head", "details": { "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=switchbot-cloudapi", "contentDisposition": "attachment; filename=\"switchbot-cloudapi-1.0.4.zip\"", "redirectLocation": null, "bodySnippet": null, "slug": "switchbot-cloudapi" }, "scope": "item", "summary": "Item download looks usable.", "detail": "Yavira can redirect you to the upstream package for this item.", "primaryActionLabel": "Download for OpenClaw", "primaryActionHref": "/downloads/switchbot-cloudapi" }, "validation": { "installChecklist": [ "Use the Yavira download entry.", "Review SKILL.md after the package is downloaded.", "Confirm the extracted package contains the expected setup assets." ], "postInstallChecks": [ "Confirm the extracted package includes the expected docs or setup files.", "Validate the skill or prompts are available in your target agent workspace.", "Capture any manual follow-up steps the agent could not complete." ] } }, "links": { "detailUrl": "https://openagent3.xyz/skills/switchbot-cloudapi", "downloadUrl": "https://openagent3.xyz/downloads/switchbot-cloudapi", "agentUrl": "https://openagent3.xyz/skills/switchbot-cloudapi/agent", "manifestUrl": "https://openagent3.xyz/skills/switchbot-cloudapi/agent.json", "briefUrl": "https://openagent3.xyz/skills/switchbot-cloudapi/agent.md" } } ``` ## Documentation ### 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) Set environment variables: SWITCHBOT_TOKEN: your OpenAPI token SWITCHBOT_SECRET: your OpenAPI secret Test (list devices): Bash: scripts/list_devices.sh Node: node scripts/switchbot_cli.js list Common tasks: Basic controls: List devices: node scripts/switchbot_cli.js list Get status: node scripts/switchbot_cli.js status Turn on/off: node scripts/switchbot_cli.js cmd turnOn / turnOff Toggle: node scripts/switchbot_cli.js cmd toggle Press (Bot): node scripts/switchbot_cli.js cmd press Curtain / Curtain 3: Set position: node scripts/switchbot_cli.js cmd setPosition --pos=50 (0=open, 100=closed; CLI auto-formats to 0,ff,50) Pause: node scripts/switchbot_cli.js cmd pause Lock / Lock Pro / Lock Ultra / Lock Lite: Lock/Unlock: node scripts/switchbot_cli.js cmd lock / unlock Deadbolt: node scripts/switchbot_cli.js cmd deadbolt Lights (Color Bulb / Strip Light / Floor Lamp / Strip Light 3 / RGBICWW etc.): Set color: node scripts/switchbot_cli.js cmd setColor --param="255:100:0" Set brightness: node scripts/switchbot_cli.js cmd setBrightness --param=80 Set color temp: node scripts/switchbot_cli.js cmd setColorTemperature --param=4000 Fans (Battery Circulator Fan / Circulator Fan / Standing Circulator Fan): Wind mode: node scripts/switchbot_cli.js cmd setWindMode --param=natural Wind speed: node scripts/switchbot_cli.js cmd setWindSpeed --param=50 Night light: node scripts/switchbot_cli.js cmd setNightLightMode --param=1 Auto-off timer: node scripts/switchbot_cli.js cmd closeDelay --param=3600 Robot Vacuum S1/S1 Plus/K10+/K10+ Pro: Start: node scripts/switchbot_cli.js cmd start Stop: node scripts/switchbot_cli.js cmd stop Dock: node scripts/switchbot_cli.js cmd dock Suction: node scripts/switchbot_cli.js cmd PowLevel --param=2 Robot Vacuum K10+ Pro Combo / K20+ Pro / S10 / S20 / K11+: Start clean: node scripts/switchbot_cli.js cmd startClean --param='{"action":"sweep_mop","param":{"fanLevel":2,"waterLevel":1,"times":1}}' Pause/Dock: node scripts/switchbot_cli.js cmd pause / dock Volume: node scripts/switchbot_cli.js cmd setVolume --param=50 Self clean (S10/S20): node scripts/switchbot_cli.js cmd selfClean --param=1 Blind Tilt: Set position: node scripts/switchbot_cli.js cmd setPosition --param="up;60" Fully open: node scripts/switchbot_cli.js cmd fullyOpen Close: node scripts/switchbot_cli.js cmd closeUp / closeDown Roller Shade: Set position: node scripts/switchbot_cli.js cmd setPosition --param=50 Humidifier (original): Set mode: node scripts/switchbot_cli.js cmd setMode --param=auto Evaporative Humidifier / Auto-refill: Set mode: node scripts/switchbot_cli.js cmd setMode --param='{"mode":7,"targetHumidify":60}' Child lock: node scripts/switchbot_cli.js cmd setChildLock --param=true Air Purifier (VOC/PM2.5/Table): Set mode: node scripts/switchbot_cli.js cmd setMode --param='{"mode":2,"fanGear":2}' Child lock: node scripts/switchbot_cli.js cmd setChildLock --param=1 Smart Radiator Thermostat: Set mode: node scripts/switchbot_cli.js cmd setMode --param=1 Set temp: node scripts/switchbot_cli.js cmd setManualModeTemperature --param=22 Relay Switch 1PM / 1 / 2PM: Toggle: node scripts/switchbot_cli.js cmd toggle Set mode: node scripts/switchbot_cli.js cmd setMode --param=0 2PM channel: node scripts/switchbot_cli.js cmd turnOn --param="1" (channel 1 or 2) Garage Door Opener: Open/Close: node scripts/switchbot_cli.js cmd turnOn / turnOff Video Doorbell: Motion detection: node scripts/switchbot_cli.js cmd enableMotionDetection / disableMotionDetection Candle Warmer Lamp: Brightness: node scripts/switchbot_cli.js cmd setBrightness --param=50 AI Art Frame: Next/Previous: node scripts/switchbot_cli.js cmd next / previous Keypad / Keypad Touch / Keypad Vision / Keypad Vision Pro: Create passcode: node scripts/switchbot_cli.js cmd createKey --param='{"name":"Guest","type":"permanent","password":"12345678"}' Delete passcode: node scripts/switchbot_cli.js cmd deleteKey --param='{"id":"11"}' ⚠️ Keypad commands are async — results come via webhook. IR Remote - Air Conditioner: Set all: node scripts/switchbot_cli.js cmd 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 SetChannel --param=5 Volume: node scripts/switchbot_cli.js cmd volumeAdd / volumeSub IR Remote - Others (DIY): Custom button: node scripts/switchbot_cli.js cmd --commandType=customize Scenes (fallback): List scenes: node scripts/switchbot_cli.js scenes Execute scene: node scripts/switchbot_cli.js scene ### API Reference Base URL: https://api.switch-bot.com Path prefix: /v1.1 Daily limit: 10,000 API calls Headers (all required): Authorization: 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: { "command": "", "parameter": "", "commandType": "command" } For IR "Others" (DIY) devices, use "commandType": "customize". ### 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 ## Trust - Source: tencent - Verification: Indexed source record - Publisher: switchbot-dev - Version: 1.0.2 ## Source health - Status: healthy - Item download looks usable. - Yavira can redirect you to the upstream package for this item. - Health scope: item - Reason: direct_download_ok - Checked at: 2026-05-09T15:05:42.006Z - Expires at: 2026-05-16T15:05:42.006Z - Recommended action: Download for OpenClaw ## Links - [Detail page](https://openagent3.xyz/skills/switchbot-cloudapi) - [Send to Agent page](https://openagent3.xyz/skills/switchbot-cloudapi/agent) - [JSON manifest](https://openagent3.xyz/skills/switchbot-cloudapi/agent.json) - [Markdown brief](https://openagent3.xyz/skills/switchbot-cloudapi/agent.md) - [Download page](https://openagent3.xyz/downloads/switchbot-cloudapi)