homeassistant-assist

# Home Assistant Assist

Control smart home devices by passing natural language to Home Assistant's Assist (Conversation) API. **Fire and forget** — trust Assist to handle intent parsing, entity resolution, and execution.

## When to Use This Skill

Use this skill when the user wants to **control or query any smart home device**. If it's in Home Assistant, Assist can handle it.

## How It Works

Pass the user's request directly to Assist:

```bash
curl -s -X POST "$HASS_SERVER/api/conversation/process" \
  -H "Authorization: Bearer $HASS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text": "USER REQUEST HERE", "language": "en"}'
```

**Trust Assist.** It handles:
- Intent parsing
- Fuzzy entity name matching
- Area-aware commands
- Execution
- Error responses

## Handling Responses

**Just relay what Assist says.** The `response.speech.plain.speech` field contains the human-readable result.

- `"Turned on the light"` → Success, tell the user
- `"Sorry, I couldn't understand that"` → Assist couldn't parse it
- `"Sorry, there are multiple devices called X"` → Ambiguous name

**Don't over-interpret.** If Assist says it worked, it worked. Trust the response.

## When Assist Returns an Error

Only if Assist returns an error (`response_type: "error"`), you can **suggest HA-side improvements**:

| Error | Suggestion |
|-------|------------|
| `no_intent_match` | "HA didn't recognize that command" |
| `no_valid_targets` | "Try checking the entity name in HA, or add an alias" |
| Multiple devices | "There may be duplicate names — consider adding unique aliases in HA" |

These are **suggestions for improving HA config**, not skill failures. The skill did its job — it passed the request to Assist.

## Setup

Set environment variables in OpenClaw config:

```json
{
  "env": {
    "HASS_SERVER": "https://your-homeassistant-url",
    "HASS_TOKEN": "your-long-lived-access-token"
  }
}
```

Generate a token: Home Assistant → Profile → Long-Lived Access Tokens → Create To...

# Home Assistant Assist

[![ClawHub](https://img.shields.io/badge/ClawHub-homeassistant--assist-blue?logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCI+PHBhdGggZmlsbD0id2hpdGUiIGQ9Ik0xMiAyQzYuNDggMiAyIDYuNDggMiAxMnM0LjQ4IDEwIDEwIDEwIDEwLTQuNDggMTAtMTBTMTcuNTIgMiAxMiAyem0wIDE4Yy00LjQxIDAtOC0zLjU5LTgtOHMzLjU5LTggOC04IDggMy41OSA4IDgtMy41OSA4LTggOHoiLz48L3N2Zz4=)](https://clawhub.com/skills/homeassistant-assist)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![OpenClaw](https://img.shields.io/badge/OpenClaw-Skill-purple)](https://github.com/openclaw/openclaw)

An [OpenClaw](https://github.com/openclaw/openclaw) skill for controlling Home Assistant smart home devices using the **Assist (Conversation) API**.

> [!IMPORTANT]
> This is an OpenClaw skill, not a HACS integration. It runs inside OpenClaw and communicates with your Home Assistant instance via its API.

## Why This Skill?

Instead of the AI manually looking up entity IDs and building verbose service calls, this skill passes natural language directly to Home Assistant's built-in NLU.

| Approach | Tokens | API Calls | Reliability |
|----------|--------|-----------|-------------|
| Entity Lookup Method | High | Multiple | Fragile |
| **Assist API** | **Low** | **One** | **Robust** |

**Benefits:**
- Faster — Single API call instead of multiple lookups
- Cheaper — Fewer tokens spent on entity resolution
- More reliable — Home Assistant knows your home better than any AI

## Requirements

- [OpenClaw](https://github.com/openclaw/openclaw) installed and running
- Home Assistant instance with API access
- A [Long-Lived Access Token](https://developers.home-assistant.io/docs/auth_api/#long-lived-access-token) from Home Assistant

## Installation

### From ClawHub (Recommended)

```bash
clawhub install homeassistant-assist
```

Or ask your OpenClaw agent:

> "Install the homeassistant-assist skill"...