openclaw-homeassistant

# openclaw-homeassistant

OpenClaw plugin for Home Assistant integration. Control your entire smart home from chat.

## Tools (34)

### Core
- `ha_status` - HA config, version, location
- `ha_list_entities` - List entities (filter by domain/state)
- `ha_get_state` - Get single entity state + attributes
- `ha_search_entities` - Search entities by name pattern
- `ha_list_services` - Available services by domain

### Lights
- `ha_light_on` - Turn on (brightness, color_temp, rgb, transition)
- `ha_light_off` / `ha_light_toggle`
- `ha_light_list` - All lights with current state

### Switches
- `ha_switch_on` / `ha_switch_off` / `ha_switch_toggle`

### Climate
- `ha_climate_set_temp` - Set temperature + HVAC mode
- `ha_climate_set_mode` - heat/cool/auto/off
- `ha_climate_set_preset` - home/away/eco/boost
- `ha_climate_list` - All climate entities with temps

### Media Player
- `ha_media_play` / `ha_media_pause` / `ha_media_stop`
- `ha_media_volume` - Set volume (0.0-1.0)
- `ha_media_play_media` - Play specific media

### Covers
- `ha_cover_open` / `ha_cover_close`
- `ha_cover_position` - Set position (0-100)

### Scenes & Automations
- `ha_scene_activate` / `ha_script_run` / `ha_automation_trigger`

### Sensors & History
- `ha_sensor_list` - All sensors with values
- `ha_history` - Entity history over time
- `ha_logbook` - Recent logbook entries

### Generic
- `ha_call_service` - Any service call
- `ha_fire_event` - Fire custom events
- `ha_render_template` - Jinja2 templates

### Notifications
- `ha_notify` - Send notifications

## Configuration

```json
{
  "url": "http://your-ha-instance:8123",
  "token": "YOUR_LONG_LIVED_ACCESS_TOKEN",
  "allowedDomains": ["light", "switch", "climate"],
  "readOnly": false
}
```

## Safety
- `readOnly`: blocks all write operations
- `allowedDomains`: restricts to specific device domains
- Entity ID validation enforced on all calls

# @elvatis_com/openclaw-homeassistant

OpenClaw plugin for Home Assistant - control devices, read sensors, trigger automations via AI.

**34 tools** | **zero runtime dependencies** | **safety-first design**

## Prerequisites

- Node.js >= 18.0.0
- A running [Home Assistant](https://www.home-assistant.io/) instance (2023.1+)
- A Home Assistant Long-Lived Access Token

## Installation

```bash
npm install @elvatis_com/openclaw-homeassistant
```

## Quick Start

### 1. Create a Long-Lived Access Token

1. Open your Home Assistant UI
2. Navigate to your profile (click your name in the sidebar)
3. Scroll down to **Long-Lived Access Tokens**
4. Click **Create Token**, give it a name (e.g. "OpenClaw"), and copy the token

### 2. Configure the Plugin

Add the plugin to your OpenClaw configuration:

```json
{
  "plugins": {
    "openclaw-homeassistant": {
      "url": "http://homeassistant.local:8123",
      "token": "YOUR_LONG_LIVED_ACCESS_TOKEN"
    }
  }
}
```

### 3. (Optional) Add Safety Guards

Restrict which domains the AI can access and/or enable read-only mode:

```json
{
  "plugins": {
    "openclaw-homeassistant": {
      "url": "http://homeassistant.local:8123",
      "token": "YOUR_LONG_LIVED_ACCESS_TOKEN",
      "allowedDomains": ["light", "switch", "sensor", "climate"],
      "readOnly": true
    }
  }
}
```

## Configuration Reference

| Option | Type | Required | Default | Description |
|--------|------|----------|---------|-------------|
| `url` | `string` | Yes | - | Home Assistant base URL (e.g. `http://homeassistant.local:8123`) |
| `token` | `string` | Yes | - | Long-Lived Access Token from your HA profile |
| `allowedDomains` | `string[]` | No | `[]` (all) | Restrict tools to these HA domains only |
| `readOnly` | `boolean` | No | `false` | Block all write tools (service calls, events, notifications) |

## Safety Model

This plugin implements three layers of safety:

- **readOnly mode** - When enabled, all 22 write tools are blocked. Only read tools (s...