Ha

Name: Ha
Rating: 3.5 (1 reviews)
Author: daniel-luke

By daniel-luke 👁 92 views ▲ 0 votes

Home Assistant plugin for OpenClaw agents

GitHub

Configuration Example

{
  "plugins": {
    "load": {
      "paths": ["/path/to/custom-plugins"]
    },
    "entries": {
      "ha": {
        "enabled": true,
        "config": {
          "haUrl": "http://homeassistant.local:8123",
          "haToken": "your-long-lived-access-token",
          "reportingChannel": "telegram",
          "reportingEnabled": true
        }
      }
    }
  }
}

README

# openclaw-ha-plugin

Home Assistant integration for [OpenClaw](https://openclaw.ai). Lets the AI agent control your smart home devices, schedule future automations, and report back to you via any configured notification channel.

## Features

- **Control devices** — turn lights on/off, adjust brightness, set thermostat temperature, lock/unlock doors, control media players, and more
- **Natural language device resolution** — refer to devices by any name ("the lamp in the corner", "kitchen ceiling thing") and the agent will figure out which entity you mean
- **Schedule future actions** — "turn off the garden lights at 11pm" creates a cron job that fires at the right time
- **Notifications** — get a confirmation message in Telegram (or any other configured channel) after every action, immediate or scheduled
- **Auto-discovery** — on first run the plugin fetches all your HA entities and generates workspace config files so you don't have to type out entity IDs

## Requirements

- OpenClaw ≥ 2026.1.30
- Home Assistant with a [long-lived access token](https://developers.home-assistant.io/docs/auth_api/#long-lived-access-token)

## Installation

Add the plugin path to your OpenClaw configuration (`~/.openclaw/openclaw.json`):

```json
{
  "plugins": {
    "load": {
      "paths": ["/path/to/custom-plugins"]
    },
    "entries": {
      "ha": {
        "enabled": true,
        "config": {
          "haUrl": "http://homeassistant.local:8123",
          "haToken": "your-long-lived-access-token",
          "reportingChannel": "telegram",
          "reportingEnabled": true
        }
      }
    }
  }
}
```

Then run the initial setup to generate your device context files:

```
openclaw ha init
```

## Configuration

| Field | Required | Description |
|---|---|---|
| `haUrl` | ✅ | Base URL of your Home Assistant instance |
| `haToken` | ✅ | Long-lived access token from your HA profile |
| `reportingChannel` | | OpenClaw channel ID to send action confirmations to (e.g. `telegram`) |
| `reportingEnabled` | | Whether to send notifications after actions. Defaults to `true` |
| `workspaceHaDir` | | Path to the device context folder relative to the workspace. Defaults to `ha/` |

## Device context files

The plugin reads device definitions from `~/.openclaw/workspace/ha/`. These files tell the agent which devices exist, what they're called, which room they're in, and whether the agent is allowed to use them.

Files are grouped by HA domain and auto-generated by `openclaw ha init`:

```yaml
# ~/.openclaw/workspace/ha/light.yaml
room: Living Room        # default room for all devices in this file
devices:
  - entity_id: light.living_room_main
    name: Main Light
    enabled: true
  - entity_id: light.old_broken_lamp
    name: Broken Lamp
    enabled: false       # agent will not touch this device
```

**Fields:**
- `room` — set at file level to apply to all devices, or override per device
- `name` — the friendly name the agent uses in conversation
- `enabled` — set to `false` to hide a device from the agent entirely

After editing these files, reload without restarting OpenClaw:

```
openclaw ha reload
```

## CLI commands

| Command | Description |
|---|---|
| `openclaw ha init` | Fetch all entities from HA and generate missing workspace YAML files |
| `openclaw ha reload` | Reload the workspace YAML files into memory |

## Agent tools

The plugin exposes four tools to the agent:

| Tool | Description |
|---|---|
| `ha_get_states` | Get the current state and attributes of one or all entities |
| `ha_list_entities` | List all enabled devices with their live state |
| `ha_call_service` | Call a HA service to control a device |
| `ha_schedule_action` | Prepare a future action — returns parameters for `cron.add` |

## Example interactions

> "Turn on the kitchen light at 50% brightness"

> "Is the front door locked?"

> "Turn off all the lights in 20 minutes"

> "Set the thermostat to 21 degrees"

> "What's the living room temperature sensor reading?"

tools