OpenClaw + Home Assistant: Control Your Smart Home with AI Agents

# In Home Assistant:
# 1. Click your profile (bottom-left)
# 2. Scroll to "Long-Lived Access Tokens"
# 3. Click "Create Token"
# 4. Name it "OpenClaw Agent"
# 5. Copy the token (you won't see it again)

# Test the token from your terminal:
curl -s -H "Authorization: Bearer YOUR_TOKEN" \
  http://YOUR_HA_IP:8123/api/ | jq .

# Expected output: {"message": "API running."}

# Set the Home Assistant URL and token
openclaw config set tools.homeassistant.url http://192.168.1.100:8123
openclaw config set tools.homeassistant.token YOUR_LONG_LIVED_TOKEN

# Enable the Home Assistant tool globally
openclaw config set tools.homeassistant.enabled true

# Verify the connection
openclaw tools test homeassistant

# Expected output:
# [OK] Connected to Home Assistant 2026.3
# [OK] Found 47 entities across 6 domains
# [OK] API response time: 23ms

# In your agent directory, edit SOUL.md to include:

## Tools
- home-assistant: control smart home devices, read sensor states,
  trigger automations via Home Assistant REST API

# Then restart the gateway
openclaw gateway restart

# Home Agent - Smart Home Controller

## Identity
You are Home Agent, an AI assistant that controls the smart home
through Home Assistant. You respond to natural language commands
and proactively monitor the house for anomalies.

## Personality
- Concise and helpful. Confirm actions briefly.
- Proactive: mention if something seems wrong (door left open,
  unusual temperature, high energy usage).
- Never ask for confirmation on safe actions (lights, music).
- Always ask for confirmation on security actions (locks, alarm).

## Home Layout
- Living Room: 3 overhead lights, TV, soundbar, thermostat
- Kitchen: 2 ceiling lights, under-cabinet LEDs, smart plug (coffee maker)
- Bedroom: 2 bedside lamps, ceiling fan, blackout blinds
- Office: desk lamp, monitor backlight, smart plug (PC)
- Front Door: smart lock, camera, motion sensor
- Garage: overhead light, door sensor, smart plug (EV charger)

## Device Mapping
- "lights" in a room = all light entities in that room
- "everything" = all controllable entities in that room
- "downstairs" = living room + kitchen
- "upstairs" = bedroom + office

## Routines
- "good morning": open bedroom blinds, kitchen lights 80%,
  start coffee maker, read weather and calendar
- "good night": all lights off, lock front door, arm security,
  thermostat to 68, bedroom fan on low
- "movie mode": living room lights 10%, TV on, soundbar on
- "work mode": office lamp on, monitor backlight warm, DND on
- "leaving": all lights off, lock all doors, arm security,
  thermostat to eco mode

## Safety Rules
- NEVER unlock doors without explicit confirmation
- NEVER disable security system without confirmation
- Thermostat bounds: minimum 60F, maximum 80F
- If garage door is open past 10pm, alert the user
- If front door unlocked past 11pm, alert and offer to lock

## Tools
- home-assistant: control devices, read sensors, trigger automations
- telegram: send alerts and receive commands (primary channel)

## Response Format
- Confirm completed actions: "Done. Living room lights set to 50%."
- For multi-step routines: list what was done
- For sensor queries: include the value and unit
- For alerts: use [ALERT] prefix

# What you say:
"Turn on the kitchen lights"
"Set living room lights to 30%"
"Make the bedroom warm white"
"Turn off all lights"

# What the agent calls:
# POST /api/services/light/turn_on
# {"entity_id": "light.kitchen_ceiling", "brightness_pct": 100}

# POST /api/services/light/turn_on
# {"entity_id": "light.living_room_overhead", "brightness_pct": 30}

# POST /api/services/light/turn_on
# {"entity_id": "light.bedroom_lamp", "color_temp_kelvin": 3000}

# POST /api/services/light/turn_off
# {"entity_id": "all"}

# What you say:
"Set the thermostat to 72"
"It's too cold in here"
"Switch to cooling mode"
"What's the temperature?"

# What the agent calls:
# POST /api/services/climate/set_temperature
# {"entity_id": "climate.living_room", "temperature": 72}

# Agent reads current temp, adjusts +3 degrees
# POST /api/services/climate/set_temperature
# {"entity_id": "climate.living_room", "temperature": 74}

# POST /api/services/climate/set_hvac_mode
# {"entity_id": "climate.living_room", "hvac_mode": "cool"}

# GET /api/states/sensor.living_room_temperature
# Agent responds: "Living room is 71.4F. Thermostat set to 72F."

# What you say:
"Start the coffee maker"
"Is the EV charger on?"
"Turn off the PC plug"

# What the agent calls:
# POST /api/services/switch/turn_on
# {"entity_id": "switch.kitchen_coffee_maker"}

# GET /api/states/switch.garage_ev_charger
# Agent responds: "EV charger is on. Current draw: 7.2kW."

# POST /api/services/switch/turn_off
# {"entity_id": "switch.office_pc_plug"}

# You: "Lock the front door"
# Agent: "Confirm: lock the front door? (yes/no)"
# You: "yes"
# Agent calls: POST /api/services/lock/lock
#   {"entity_id": "lock.front_door"}
# Agent: "Done. Front door is locked."

# You: "Is the garage door closed?"
# Agent calls: GET /api/states/cover.garage_door
# Agent: "Garage door is open. It's been open for 2 hours.
#          Want me to close it?"

# You: "close it"
# Agent: "Confirm: close the garage door? (yes/no)"
# You: "yes"
# Agent calls: POST /api/services/cover/close_cover
#   {"entity_id": "cover.garage_door"}
# Agent: "Done. Garage door is closing."

# Proactive alert (agent monitors state changes):
# Agent: "[ALERT] Front door was unlocked at 11:47pm.
#          No one is expected. Lock it?"

# You: "Show me the front door camera"
# Agent calls:
#   POST /api/services/camera/snapshot
#   {"entity_id": "camera.front_door", "filename": "/tmp/front_door.jpg"}
#
#   Then sends the image via Telegram:
#   Agent: "Here's the front door camera. Captured just now."
#   [Attaches /tmp/front_door.jpg]

# You: "good morning"
# Agent executes the "good morning" routine from SOUL.md:

# 1. Open bedroom blinds
POST /api/services/cover/open_cover
  {"entity_id": "cover.bedroom_blinds"}

# 2. Set kitchen lights to 80%
POST /api/services/light/turn_on
  {"entity_id": "light.kitchen_ceiling", "brightness_pct": 80}

# 3. Start coffee maker
POST /api/services/switch/turn_on
  {"entity_id": "switch.kitchen_coffee_maker"}

# 4. Read weather (from weather.home entity)
GET /api/states/weather.home

# 5. Read calendar (from calendar integration)
GET /api/calendars/calendar.personal?start=TODAY&end=TODAY

# Agent response:
# "Good morning! Blinds are open, kitchen lights on, coffee brewing.
#  Today: 68F and partly cloudy. You have a standup at 9:30am
#  and a dentist appointment at 2pm."

# You: "good night"
# Agent executes the "good night" routine:

# 1. Turn off all lights
POST /api/services/light/turn_off {"entity_id": "all"}

# 2. Lock front door (with state check)
GET /api/states/lock.front_door
# Already locked? Skip. Unlocked? Lock it.
POST /api/services/lock/lock {"entity_id": "lock.front_door"}

# 3. Arm security system
POST /api/services/alarm_control_panel/alarm_arm_night
  {"entity_id": "alarm_control_panel.home"}

# 4. Set thermostat to 68F
POST /api/services/climate/set_temperature
  {"entity_id": "climate.living_room", "temperature": 68}

# 5. Turn bedroom fan on low
POST /api/services/fan/turn_on
  {"entity_id": "fan.bedroom_ceiling", "percentage": 25}

# Agent response:
# "Good night! All lights off, front door locked, security armed,
#  thermostat set to 68F, bedroom fan on low. Sleep well."

# HEARTBEAT.md

## Schedule
- Every weekday at 6:30am: run "good morning" routine
- Every day at 11:00pm: run "good night" routine
- Every 30 minutes: check for anomalies (open doors, unusual temps)
- Every hour: log energy consumption to daily report

# Configure Telegram as the primary channel
openclaw config set channels.telegram.bottoken YOUR_TG_BOT_TOKEN
openclaw config set channels.telegram.allowedUsers '[YOUR_CHAT_ID]'

# Enable voice message transcription
openclaw config set channels.telegram.transcribeVoice true

# Now from your phone:
# - Type: "turn on the porch light"
# - Voice message: "what's the temperature in the house"
# - Both work. The agent processes and responds in seconds.

# For quick actions, the agent can send Telegram inline keyboards:
# Agent: "Which room?"
# [Living Room] [Kitchen] [Bedroom] [Office]
# You tap: [Living Room]
# Agent: "Living room lights are at 80%. Adjust?"
# [Off] [25%] [50%] [100%]

# Set up a Discord server for your household
# Create channels: #lights, #climate, #security, #general

# Configure the agent
openclaw config set channels.discord.bottoken YOUR_DISCORD_TOKEN
openclaw config set channels.discord.mentionOnly false

# Channel-specific behaviors (in SOUL.md):
# - Messages in #lights: only control light entities
# - Messages in #climate: only control climate entities
# - Messages in #security: require confirmation for all actions
# - Messages in #general: full access

# Family members can all use the bot:
# Mom: "set thermostat to 73"
# Kid: "turn on my bedroom light"
# Agent handles each request in context

# You: "How much energy did we use today?"
# Agent calls: GET /api/history/period/TODAY?filter_entity_id=sensor.home_energy
# Agent: "Today's consumption: 18.4 kWh ($2.21).
#          Biggest consumers: EV charger (8.2 kWh), HVAC (5.1 kWh),
#          dryer (2.8 kWh). You're 12% above your daily average."

# You: "What's using the most power right now?"
# Agent queries all power monitoring sensors
# Agent: "Current draw: 2.4 kW total.
#          - EV charger: 1.8 kW (charging, 67% complete)
#          - Office PC: 0.3 kW
#          - Kitchen appliances: 0.2 kW
#          - Other: 0.1 kW"

# Scheduled daily report (via HEARTBEAT.md):
# Agent sends to Telegram at 9pm:
# "Daily energy report:
#  Total: 22.1 kWh ($2.65)
#  vs yesterday: -8%
#  vs 7-day avg: -3%
#  Tip: The porch light was on for 14 hours today.
#  Consider a motion-activated schedule."

# Agent 1: Climate Controller
# ~/agents/climate-agent/SOUL.md
# Manages: thermostat, fans, blinds, humidity
# Channel: responds to @climate in Discord

# Agent 2: Security Guard
# ~/agents/security-agent/SOUL.md
# Manages: locks, cameras, alarm, motion sensors
# Channel: responds to @security in Discord + Telegram alerts

# Agent 3: Home Coordinator
# ~/agents/home-coordinator/SOUL.md
# Manages: routines, energy reports, scheduling
# Delegates to climate-agent and security-agent via @mentions
# Channel: responds to all messages in #home

# Start all agents:
openclaw gateway start --agents climate-agent,security-agent,home-coordinator

# The coordinator handles "good night":
# 1. Tells climate-agent: "set night mode"
# 2. Tells security-agent: "arm the house"
# 3. Turns off lights directly (simple action)
# 4. Reports summary to user

// tools/scan-home.cjs
// Returns a complete home status summary

const HA_URL = process.env.HA_URL || "http://192.168.1.100:8123";
const HA_TOKEN = process.env.HA_TOKEN;

async function getStates() {
  const res = await fetch(HA_URL + "/api/states", {
    headers: { Authorization: "Bearer " + HA_TOKEN }
  });
  return res.json();
}

async function main() {
  const states = await getStates();
  const summary = {
    lights: { on: 0, off: 0 },
    climate: {},
    locks: {},
    doors: {},
    energy: { current_draw: 0 }
  };

  for (const entity of states) {
    const [domain] = entity.entity_id.split(".");
    if (domain === "light") {
      summary.lights[entity.state] = (summary.lights[entity.state] || 0) + 1;
    }
    if (domain === "climate") {
      summary.climate[entity.attributes.friendly_name] = {
        current: entity.attributes.current_temperature,
        target: entity.attributes.temperature,
        mode: entity.state
      };
    }
    if (domain === "lock") {
      summary.locks[entity.attributes.friendly_name] = entity.state;
    }
    if (domain === "sensor" && entity.attributes.device_class === "power") {
      summary.energy.current_draw += parseFloat(entity.state) || 0;
    }
  }

  console.log(JSON.stringify(summary, null, 2));
}

main();