smartpi-plugin-setup

intent

this skill handles the full lifecycle of smartpi device management in openclaw: binding new devices via qr code, listing connected devices, removing devices, and troubleshooting the most common error (9002 timeout). use this when a user wants to pair a smartpi device, check device status, remove a device, or debug why the ai isn't responding to smartpi input. the skill assumes openclaw gateway is running locally with the openclaw-smartpi plugin installed.

inputs

external connections:

• openclaw gateway (local http/ws on default port, env var: OPENCLAW_GATEWAY_URL, defaults to http://localhost:8080)
• openclaw-smartpi plugin (must be installed via openclaw plugins install openclaw-smartpi)
• smartpi device with qr code scanning capability (physical device or emulator)
• local ai model or remote llm service (checked for response latency in 9002 troubleshooting)

required context:

• user has openclaw cli installed and in PATH
• user can execute openclaw commands in shell
• user has permission to modify gateway config and restart gateway
• python or node.js available for qr code generation (pick one, not required if using external qr service)

optional:

• qrcode python package: pip install qrcode pillow
• qrcode npm package: npm install qrcode (for node.js approach)

procedure

1. install plugin (first time only)

   • input: none (assumes openclaw not yet have smartpi plugin)
   • execute: openclaw plugins install openclaw-smartpi
   • execute: openclaw gateway restart
   • output: gateway logs show plugin loaded, openclaw plugins list includes openclaw-smartpi: enabled
   • move to step 2

2. validate gateway config before binding

   • input: current gateway config (fetched via next sub-step)
   • execute: openclaw gateway action=config.get
   • extract from output: current plugins.allow array and channels object
   • output: json config object in memory
   • move to step 3

3. patch config to enable smartpi plugin (if not already enabled)

   • input: config object from step 2, smartpi plugin name
   • check: is openclaw-smartpi in plugins.allow array? if yes, skip to step 4. if no, continue.
   • action: construct new plugins.allow array that includes all existing plugins plus openclaw-smartpi
   • execute: openclaw gateway action=config.patch plugins.allow=[...full array...]
   • output: config patched, no error in response
   • move to step 4

4. patch config to add smartpi channel (if not already present)

   • input: config object from step 2, smartpi channel config
   • check: does channels.openclaw-smartpi already exist? if yes, skip to step 5. if no, continue.
   • action: construct new channels object that preserves all existing channels (discord, telegram, etc.) and adds channels.openclaw-smartpi with enabled: true and defaultAgentId: main
   • execute: openclaw gateway action=config.patch channels={...full channels object...}
   • output: config patched, all existing channels still present, no error in response
   • move to step 5

5. restart gateway after config changes

   • input: none
   • execute: openclaw gateway restart
   • wait: 3-5 seconds for gateway to come online
   • output: gateway responds to status check, no startup errors in logs
   • move to step 6

6. initiate device binding

   • input: none (assuming user ready to scan qr with smartpi device)
   • execute: openclaw smartpi accounts bind
   • extract from output: bindingId value (appears after "绑定ID:" or similar label)
   • output: bindingId string (alphanumeric, typically 16-32 chars)
   • move to step 7

7. generate qr code png

   • input: bindingId from step 6
   • action: choose one method below
     • python: python3 -c "import qrcode; qrcode.make('BINDING_ID_HERE').save('smartpi_qr.png')"
     • node.js: node -e "const qr=require('qrcode'); qr.toFile('smartpi_qr.png','BINDING_ID_HERE',(e)=>e&&console.error(e))"
   • output: smartpi_qr.png written to disk (verify file exists and >1kb)
   • move to step 8

8. send qr to user and wait for device connection

   • input: smartpi_qr.png file path
   • action: display qr image to user, instruct "scan this with your smartpi device"
   • wait: 30-120 seconds for device to connect via websocket
   • check logs: tail gateway logs for line containing WebSocket connected: followed by a deviceKey
   • if found: move to step 9. if timeout after 120s: move to decision point "device did not connect"
   • output: WebSocket connected log entry with deviceKey

9. confirm device is online to user

   • input: deviceKey from step 8 logs
   • action: tell user "device is now connected and ready, you can speak to smartpi"
   • execute: openclaw smartpi accounts list to show user their new device in the list
   • output: user acknowledges, binding flow complete

decision points

if user wants to list existing devices (instead of bind new one):

• execute: openclaw smartpi accounts list
• output: table of deviceKey, name, status (online/offline)
• skip binding flow (steps 1-9), go directly to outcome signal

if user wants to delete a device:

• execute: openclaw smartpi accounts remove <deviceKey>
• confirm deletion in response
• device is removed locally and from cloud backend
• skip binding flow, go directly to outcome signal

if device did not connect within 120 seconds (timeout during step 8):

• check: are you in smartpi range (within 10-20 meters, no physical obstacles)?
• check: is the smartpi device powered on and wifi connected?
• check: did you scan the entire qr code clearly?
• action: regenerate qr code (repeat steps 6-7) and retry
• if still fails: move to troubleshooting (see 9002 error section below)

if gateway startup fails during step 5:

• check: openclaw plugins list, is openclaw-smartpi listed?
• check: review gateway logs for parsing errors in config (json syntax, missing brackets)
• action: fetch config again (step 2), manually verify channels and plugins.allow are valid json
• action: if syntax error found, fix and patch again
• if still fails: reinstall plugin (openclaw plugins uninstall openclaw-smartpi, then step 1)

if user reports error 9002 (ai response timeout when talking to smartpi):

• check point 1: openclaw plugins list → confirm openclaw-smartpi: enabled
• check point 2: openclaw smartpi accounts list → confirm device exists
• check point 3: tail gateway logs → confirm WebSocket connected: <deviceKey> line is recent (within last 60s)
• check point 4: send a plain text message to openclaw via another channel (discord, telegram, or cli) → confirm ai responds normally (if slow, model or llm latency is bottleneck, not smartpi)
• check point 5: tail gateway logs → search for cannot resolve agentId → if found, re-run step 4 (channels config missing or misconfigured)
• check point 6: check gateway logs for AI response timeout or gateway timeout messages → if found, increase timeout setting in config (beyond scope of this skill, escalate)
• outcome: one of the above will identify root cause (most common: slow local model, missing channel config, or device disconnected)

if config.patch operation fails with "array is immutable" or similar:

• cause: you tried to patch plugins.allow or channels without the full array/object
• action: go back to step 2, fetch full config again, ensure you're sending complete arrays/objects in patch request, not just deltas

if qr code generation command fails (python/node not installed):

• fallback: use an online qr generator tool (qr-server.com, goqr.me, etc.) and paste bindingId string
• or: ask user to manually enter bindingId into smartpi app if ui supports it
• outcome: qr code exists, binding can proceed

output contract

success state:

• device appears in openclaw smartpi accounts list output with status "online"
• gateway logs contain line: WebSocket connected: <deviceKey>
• no cannot resolve agentId errors in gateway logs
• user can speak to smartpi device and receive ai responses within 10 seconds (normal latency)

file locations:

• smartpi_qr.png: created in current working directory (or specify path in qr code command)
• gateway logs: typically in openclaw data directory under logs/gateway.log (location varies by os/install)
• config: stored in openclaw gateway state, queryable via openclaw gateway action=config.get

data format:

• bindingId: alphanumeric string, 16-32 characters
• deviceKey: alphanumeric string, auto-generated by device on first connection
• qr code: png image, scannable by smartpi device camera, contains bindingId as payload

outcome signal

binding successful:

• user sees qr code displayed
• user scans with smartpi device
• within 30-120 seconds, gateway logs show WebSocket connected: <deviceKey>
• user receives message "device is connected and ready"
• device appears in device list with online status

list operation successful:

• user runs list command, sees table of existing devices with keys and status

delete operation successful:

• user runs remove command with deviceKey, sees "device removed" confirmation
• device no longer appears in next list output
• device goes offline