Homekit

homeclaw-cli device-map --format agent -o memory/homekit-device-map.json

# Discovery
homeclaw-cli device-map --format agent   # LLM-optimized flat list (default cache format)
homeclaw-cli device-map --format json      # Full detail with aliases, manufacturer
homeclaw-cli device-map --format md        # Markdown tables by room
homeclaw-cli device-map --home "<home>" --format agent  # Scope map to one home
homeclaw-cli search "<query>" --json       # Search by name/room/category
homeclaw-cli search "<query>" --home "<home>" --json
homeclaw-cli get "<name-or-uuid>" --json   # Full detail on one device
homeclaw-cli get "<name-or-uuid>" --home "<home>" --json
homeclaw-cli list --room "Kitchen" --json  # All devices in a room
homeclaw-cli list --home "<home>" --room "Kitchen" --json

# Control — always use UUID for reliability
homeclaw-cli set "<uuid>" power true                   # On/off
homeclaw-cli set "<uuid>" power true --home "<home>"   # Multi-home: pin the home
homeclaw-cli set "<uuid>" brightness 50                # Lights (0-100)
homeclaw-cli set "<uuid>" target_temperature 72        # Thermostat
homeclaw-cli set "<uuid>" target_heating_cooling auto  # HVAC: off/heat/cool/auto
homeclaw-cli set "<uuid>" lock_target_state locked     # Locks: locked/unlocked
homeclaw-cli set "<uuid>" target_position 100          # Blinds (0=closed, 100=open)

# Multi-gang switches — one accessory, several channels sharing a service type
homeclaw-cli set "<uuid>" power true --service-name "Pendentes"  # By service name
homeclaw-cli set "<uuid>" power true --service-id "<service-uuid>"  # By service UUID (names can repeat)
homeclaw-cli set "<uuid>" power true --service-index 2           # By channel number (ServiceLabelIndex)

# Scenes
homeclaw-cli scenes --json              # List all scenes
homeclaw-cli scenes --home "<home>" --json
homeclaw-cli get-scene "<name>" --json  # Full detail: all actions (accessory, room, characteristic, value)
homeclaw-cli trigger "<scene-name>"     # Run a scene
homeclaw-cli trigger "<scene-name>" --home "<home>"
homeclaw-cli import-scene scene.json --dry-run   # Preview scene import
homeclaw-cli import-scene scene.json              # Create scene from JSON
echo '{"name": "...", "actions": [...]}' | homeclaw-cli import-scene -   # Read JSON from stdin (works from any directory, sandbox-safe)
homeclaw-cli delete-scene "<name-or-uuid>" --dry-run   # Preview deletion
homeclaw-cli delete-scene "<name-or-uuid>"             # Delete a scene

# Room assignment — supports UUID for duplicate names
homeclaw-cli assign-rooms rooms.json --dry-run    # Preview room assignments
homeclaw-cli assign-rooms rooms.json              # Assign accessories to rooms
echo '[{"accessory": "...", "room": "..."}]' | homeclaw-cli assign-rooms -   # stdin also works here
# JSON format: bare array [{"uuid": "...", "room": "..."} or {"accessory": "...", "room": "..."}]
#              (or the same array wrapped as {"assignments": [...]})
# Use "uuid" when multiple accessories share the same name (e.g., ceiling fan + light)

# Management — rename, rooms, zones
homeclaw-cli rename "<name-or-uuid>" "<new-name>"           # Rename accessory
homeclaw-cli rename "<name-or-uuid>" "<new-name>" --dry-run # Preview rename
homeclaw-cli rename-room "<name-or-uuid>" "<new-name>"      # Rename room
homeclaw-cli create-room "<name>"                            # Create room
homeclaw-cli remove-room "<name-or-uuid>"                    # Remove room
homeclaw-cli remove-accessory "<name-or-uuid>"               # Remove accessory
homeclaw-cli create-zone "<name>"                            # Create zone
homeclaw-cli remove-zone "<name-or-uuid>"                    # Remove zone
homeclaw-cli add-room-to-zone "<room>" "<zone>"              # Add room to zone
homeclaw-cli remove-room-from-zone "<room>" "<zone>"         # Remove room from zone

# Automations (button programming)
homeclaw-cli automations list --json                          # List all automations
homeclaw-cli automations get "<name-or-uuid>" --json          # Detail view
homeclaw-cli automations delete "<name-or-uuid>" [--dry-run]
homeclaw-cli automations enable "<name-or-uuid>"
homeclaw-cli automations disable "<name-or-uuid>"

# Create with inline actions (creates a scene named after the automation)
# ALWAYS use UUIDs for target accessories to avoid name collisions
homeclaw-cli automations create --name "Sarah's Room Open" \
  --accessory "Office Button" \
  --action "BE21C139-413A-50F9-B97F-B9BDA06302A8:power:true" \
  --action "52195C6F-6FAA-5E52-AA56-840A6605EEAA:target_position:100" \
  --press single --service-index 1

# Create with a named scene
homeclaw-cli automations create --name "Movie Mode" \
  --accessory "Remote Button" \
  --scene "Movie Time" \
  --press single

# Press types: single (0), double (1), long (2)
# --action format: "UUID:property:value" (repeatable, UUID strongly preferred over names)
# --scene and --action are mutually exclusive
# Use --service-index for multi-button accessories (e.g., Aqara in fast mode)
# Note: inline actions create a visible scene (Apple uses a private API for hidden ones)

# Export to file (any format)
homeclaw-cli device-map --format agent -o memory/homekit-device-map.json
homeclaw-cli device-map --format md -o device-map.md

Ambiguous: 'power' exists on multiple services. Pass service_name, service_index, or service_id to pick one
(service_type is identical across channels on multi-gang accessories):
  - service_name: "Switch 1", service_index: 1, service_id: 5F2A..., service_type: 00000049-...
  - service_name: "Switch 2", service_index: 2, service_id: 91C7..., service_type: 00000049-...
  - service_name: "Pendentes", service_index: 3, service_id: B3E0..., service_type: 00000049-...

{ "characteristic": "power", "value": "true", "verified": true,
  "service": { "id": "B3E0...", "name": "Pendentes", "type": "00000049-...", "index": 3 } }

Write not applied: Wall Switch.Pendentes.power still reads false after writing true. Pass verify=false to accept unconfirmed writes.

# Recent events (default: last 50)
homeclaw-cli events --json

# Events from the last hour
homeclaw-cli events --since 1h --json

# Only characteristic changes (e.g. lights turning on/off)
homeclaw-cli events --type characteristic_change --json

# Last 200 events
homeclaw-cli events --limit 200 --json

Home app / physical switch / Siri / manufacturer app
        |
        v
HomeKit (HMAccessoryDelegate push notification)
        |
        v
HomeClaw event logger (writes to events.jsonl)
        |
        +-- Battery event? --> Logged to disk only (never sent via webhook)
        |
        +-- Trigger matches? --> POST /hooks/homeclaw
        |
        +-- No trigger --> Logged to disk only (no webhook sent)

        v  (trigger matched)
OpenClaw gateway validates Bearer token
        |
        v
hooks.mappings resolves "homeclaw"
        |
        v
HomeClaw Agent (dedicated)
        +-- Classifies: CRITICAL / NOTABLE / AMBIENT
        +-- If CRITICAL/NOTABLE: a2a message to main agent (Lobster)
        +-- If AMBIENT: log to agent memory only

openclaw agents install homeclaw /path/to/openclaw/agents/homeclaw

"hooks": {
  "enabled": true,
  "token": "${HOMECLAW_WEBHOOK_TOKEN}",
  "mappings": {
    "homeclaw": {
      "agentId": "homeclaw",
      "sessionKey": "hook:homeclaw",
      "deliver": true,
      "channel": "last",
      "allowUnsafeExternalContent": true
    }
  },
  "internal": {
    "enabled": true,
    "entries": {
      "audit-logger": { "enabled": true }
    }
  }
}

openclaw agents install homeclaw /path/to/openclaw/agents/homeclaw

openclaw agents list

# Generate a secure token
openssl rand -base64 24 | tr '+/' '-_' | tr -d '='

# Add to .env
echo 'HOMECLAW_WEBHOOK_TOKEN=<generated-token>' >> ~/.openclaw/.env

homeclaw-cli config --webhook-url "http://127.0.0.1:18789" \
                    --webhook-token "<same-token>" \
                    --webhook-enabled true

# List current triggers
homeclaw-cli triggers

# Add a trigger for all state changes on an accessory
homeclaw-cli triggers add --label "Garage Door" --accessory-id "<uuid>"

# Add a trigger for a specific characteristic only
homeclaw-cli triggers add --label "Mailbox Open" --accessory-id "<uuid>" --characteristic contact_state

# Update a trigger's delivery mode
homeclaw-cli triggers update "<trigger-id>" --wake-mode now

# Remove a trigger
homeclaw-cli triggers remove "<trigger-id>"