/switchbot

name: switchbot
description: Use when the user mentions SwitchBot devices, smart-home automation, or asks about controlling lights, locks, curtains, sensors, plugs, or IR appliances (TV/AC/fan). Teaches the agent how to drive the authoritative `switchbot` CLI safely, read user preferences from `policy.yaml`, and respect safety tiers.

SwitchBot skill

Drive the user's SwitchBot smart home through the `switchbot` CLI. Always query the CLI for ground truth — never guess commands, deviceIds, or parameter values.

---

Authority chain

| Question | Authoritative command | | --- | --- | | What can I do (cold start)? | `switchbot agent-bootstrap --compact --json` | | What commands exist? | `switchbot capabilities --json` | | What flags does this command take? | `switchbot <cmd> --help --json` | | What devices does the user have? | `switchbot devices list --json` | | What's this device doing right now? | `switchbot devices status <id> --json` | | What can I do with this specific device type? | `switchbot devices describe <id> --json` | | What scenes are configured? | `switchbot scenes list --json` | | What's on the user's AI MindClip (recordings, transcript, todos, summaries)? | `switchbot mindclip recordings/recording/transcript/summary/todos/daily/weekly/urgent-todos --json` | | What's in a Kata Friends diary? | `switchbot devices diary <id> --start <unix-ms> --end <unix-ms> --json` (up to 31 days) | | What's in the user's `policy.yaml`? | `cat ~/.config/openclaw/switchbot/policy.yaml` | | Is my quota OK? | `switchbot quota status --json` | | Is the setup healthy? | `switchbot doctor --json` | | What automation rules are configured? | `switchbot rules list --json` | | Are the rules valid? | `switchbot rules lint` | | Draft an execution plan from intent | `switchbot plan suggest --intent "..." --device <id>` | | Run a plan with per-step approval | `switchbot plan run <file> --require-approval` | | Draft an automation rule from intent | `switchbot rules suggest --intent "..." --device <id>` | | Inject a rule into policy.yaml | `switchbot policy add-rule [--dry-run] [--enable]` (reads YAML from stdin) |

---

Network requirements

`switchbot codex setup` requires outbound internet (npm registry + GitHub). If it fails with a network error, read `references/codex-network.md` for the `~/.codex/config.toml` fix.

---

Required bootstrap

Before any action, run:

switchbot agent-bootstrap --compact

The response contains: `cliVersion`, `safetyTiers`, `nameStrategies`, `profile`, `quota`, `devices[]` (cached, with `deviceId`/`type`/`name`/`category`/`roomName`), `catalog`, and `hints[]`.

If devices look stale (user just added one), refresh with `switchbot devices list --json`.

Then read the user's policy:

cat ~/.config/openclaw/switchbot/policy.yaml 2>/dev/null

If the file doesn't exist, proceed with default safety tiers and tell the user once they can create one with `switchbot policy new`.

---

Resolving a name to a device

When the user says "bedroom light", resolve in this order:

1. **alias** — `policy.yaml` alias map → `<deviceId>`. Most reliable. 2. **exact** — device `name == "bedroom light"` (case-insensitive). 3. **prefix** — name starts with the phrase. 4. **substring** — name contains the phrase. 5. **fuzzy** — Levenshtein distance ≤ 2. 6. **require-unique** — multiple matches at same tier → **stop and ask**. Never pick silently.

---

Safety gates

| Tier | Examples | Behaviour | | --- | --- | --- | | `read` | status, list, quota | Run freely. | | `ir-fire-forget` | IR power/AC/TV via Hub | Run; warn there is no device-side confirmation. | | `mutation` | turnOn/Off, setBrightness, setColor | Run. Append to audit log. | | `destructive` | lock, unlock, delete scenes/webhooks | **Refuse by default.** Confirm explicitly; prefer `--dry-run` first. | | `maintenance` | (reserved) | Always confirm. |

Policy overrides: `confirmations.always_confirm` forces confirmation; `confirmations.never_confirm` pre-approves (never add `destructive` actions). `quiet_hours` requires confirmation even for `mutation`.

---

Policy compliance

1. Run `switchbot policy validate --live --json` through the CLI once per device-control session. Use `policy_validate(live=true)` only when a separately configured MCP server exposes it; the default profile does not. 2. Honour `quiet_hours`, `always_confirm`, and `never_confirm` from the validated policy. 3. No policy file → proceed with default tiers.

Never write to `policy.yaml` without showing a diff and getting explicit approval.

---

Audit logging

The default MCP profile does not expose audit administration. Review past activity with `switchbot history show --json` through the CLI, or use `audit_query` / `audit_stats` only when a separately configured server exposes those tools. Enable CLI mutation logging explicitly with `switchbot --audit-log devices command <id> <cmd>`.

---

Output modes

Always use `--json` when parsing output. Use `--format=markdown` for user-facing summaries. Never parse markdown or human tables programmatically — re-run with `--json`.

---

Credentials

First-time login: `switchbot auth login` (opens browser). Headless: add `--no-open`. Inspect the active keychain backend: `switchbot auth keychain describe --json`. Reset cache without touching credentials: `switchbot reset [--all]`. Never run `auth login` or `auth keychain set` on the user's behalf.

---

Declarative automations (CLI ≥ 3.9.0)

When the user wants "when X, do Y", author a rule in `policy.yaml` instead of a shell loop. Validate the policy through `switchbot policy validate --json`; CLI 3.9.0 requires `"0.2"`. A legacy `"0.1"` file must be migrated with CLI ≤2.15 before returning to this CLI.

Start with `dry_run: true`:

automation:
  enabled: true
  rules:
    - name: "hallway motion at night"
      when: { source: mqtt, event: motion.detected, device: "hallway sensor" }
      conditions:
        -