home-assistant-control

# Home Assistant Control

Use Home Assistant REST API with a long-lived access token.

## Requirements

### For skill users (runtime)

- `bash`
- `curl`
- `jq`
- Home Assistant long-lived token (`HA_TOKEN`)
- Home Assistant public base URL (`HA_URL_PUBLIC`)

### For skill maintainers (packaging/validation)

- `python3`
- `pyyaml` (required by `skill-creator` validator/packager scripts)

## Required environment variables

- `HA_TOKEN` (required)
- `HA_URL_PUBLIC` (required; canonical target and fallback)
- Optional URL behavior:
  - if `HA_URL_LOCAL` is set (and no `HA_URL` override), local is tried first, then fallback to `HA_URL_PUBLIC`
  - `HA_URL` is an explicit override (if set, used directly)

## Secrets handling (publish-safe)

- Keep keys/URLs in an external file, not in the skill folder.
- Set `HA_ENV_FILE=/absolute/path/to/file.env` when you want file-based secret loading.
- If `HA_ENV_FILE` is not set, scripts only use environment variables already present in the shell.
- `scripts/ha_call.sh` and `scripts/self_check.sh` load env file only when `HA_ENV_FILE` is provided.

## Core workflow

1. Parse the user request into target entity/service + desired action.
2. Check `references/naming-context.md` for manual alias mappings first.
3. Verify entity exists before changing state.
4. Execute service call.
5. Re-check state and report outcome clearly.

## Useful endpoints

- List states: `GET /api/states`
- Single state: `GET /api/states/{entity_id}`
- Call service: `POST /api/services/{domain}/{service}`

Headers:

- `Authorization: Bearer $HA_TOKEN`
- `Content-Type: application/json`

## Scripts

- `scripts/ha_env.sh` — loads env file only when `HA_ENV_FILE` is explicitly set, using safe KEY=VALUE parsing (no `source`/`eval`).
- `scripts/ha_call.sh` — generic API caller for Home Assistant.
- `scripts/fill_entities_md.sh` — generate `references/entities.md` from `GET /api/states`.
  - Full map: `./scripts/fill_entities_md.sh`
  - Filter domains: `./scripts/fill...

# OpenClaw Skill: Home Assistant Control

OpenClaw skill for controlling and inspecting Home Assistant via REST API.

## Features

- Safe service execution (`ha_safe_action.sh`) with guardrails
- Local-first URL routing with public fallback
- Entity discovery/search (`ha_entity_find.sh`)
- Entity map generation (`fill_entities_md.sh`)
- Naming-context aliases for natural commands (`references/naming-context.md`)
- Environment self-check (`self_check.sh`)

## Runtime Requirements

- bash
- curl
- jq

## Configuration

Use a private env file by explicitly pointing to it:

- set `HA_ENV_FILE=/absolute/path/to/env`
- example path: `~/.openclaw/private/home-assistant.env`

Required:

- `HA_TOKEN`
- `HA_URL_PUBLIC` (canonical target and fallback)
- Optional URL strategy:
  - optional `HA_URL_LOCAL` (tried first when override not set)
  - optional `HA_URL` (explicit override)

### Example private env file

Create a private file (example `~/.openclaw/private/home-assistant.env`), then set:

```bash
export HA_ENV_FILE="$HOME/.openclaw/private/home-assistant.env"
```

Example file content:

```env
HA_TOKEN=YOUR_LONG_LIVED_ACCESS_TOKEN
HA_URL_PUBLIC=https://your-home.example.com
# Optional local URL (tried first when HA_URL is not set)
# HA_URL_LOCAL=http://homeassistant.local:8123
# Optional explicit override (no fallback)
# HA_URL=http://homeassistant.local:8123
```

## Security model

- The scripts only call Home Assistant API paths under `/api/...`.
- Base URLs must be `http://` or `https://`.
- For remote/public access, use HTTPS.
- Secrets are loaded only when `HA_ENV_FILE` is explicitly set, and should never be committed.
- Env files are parsed as plain `KEY=VALUE` data (no `source`/shell execution).

## Main Scripts

- `scripts/self_check.sh`
- `scripts/ha_call.sh`
- `scripts/ha_safe_action.sh`
- `scripts/ha_entity_find.sh`
- `scripts/fill_entities_md.sh`
- `scripts/save_naming_context.sh`

## Package Artifact

This repo includes `home-assistant-control.skill` for dire...