home-assistant
控制 Home Assistant 智能家居设备、运行自动化并接收 Webhook 事件。在控制灯光、开关、气候、场景、脚本或任何 HA 实体时使用。支持通过 REST API（出站）和 Webhooks（HA 自动化的入站触发器）进行双向通信。
安装 / 下载方式
TotalClaw CLI推荐
totalclaw skills install shop:totalclaw:totalclaw~home-assistantcURL直接下载，无需登录
curl -fsSL https://skills.taituai.com/api/skills/totalclaw%3Atotalclaw~home-assistant/file -o home-assistant.md# Home Assistant
Control your smart home via Home Assistant's REST API and webhooks.
## Setup
### Option 1: Config File (Recommended)
Create `~/.config/home-assistant/config.json`:
```json
{
"url": "https://your-ha-instance.duckdns.org",
"token": "your-long-lived-access-token"
}
```
### Option 2: Environment Variables
```bash
export HA_URL="http://homeassistant.local:8123"
export HA_TOKEN="your-long-lived-access-token"
```
### Getting a Long-Lived Access Token
1. Open Home Assistant → Profile (bottom left)
2. Scroll to "Long-Lived Access Tokens"
3. Click "Create Token", name it (e.g., "Clawdbot")
4. Copy the token immediately (shown only once)
## Quick Reference
### List Entities
```bash
curl -s -H "Authorization: Bearer $HA_TOKEN" "$HA_URL/api/states" | jq '.[].entity_id'
```
### Get Entity State
```bash
curl -s -H "Authorization: Bearer $HA_TOKEN" "$HA_URL/api/states/light.living_room"
```
### Control Devices
```bash
# Turn on
curl -X POST -H "Authorization: Bearer $HA_TOKEN" -H "Content-Type: application/json" \
"$HA_URL/api/services/light/turn_on" -d '{"entity_id": "light.living_room"}'
# Turn off
curl -X POST -H "Authorization: Bearer $HA_TOKEN" -H "Content-Type: application/json" \
"$HA_URL/api/services/light/turn_off" -d '{"entity_id": "light.living_room"}'
# Set brightness (0-255)
curl -X POST -H "Authorization: Bearer $HA_TOKEN" -H "Content-Type: application/json" \
"$HA_URL/api/services/light/turn_on" -d '{"entity_id": "light.living_room", "brightness": 128}'
```
### Run Scripts & Automations
```bash
# Trigger script
curl -X POST -H "Authorization: Bearer $HA_TOKEN" "$HA_URL/api/services/script/turn_on" \
-H "Content-Type: application/json" -d '{"entity_id": "script.goodnight"}'
# Trigger automation
curl -X POST -H "Authorization: Bearer $HA_TOKEN" "$HA_URL/api/services/automation/trigger" \
-H "Content-Type: application/json" -d '{"entity_id": "automation.motion_lights"}'
```
### Activate Scenes
```bash
curl -X POST -H "Authorization: Bearer $HA_TOKEN" "$HA_URL/api/services/scene/turn_on" \
-H "Content-Type: application/json" -d '{"entity_id": "scene.movie_night"}'
```
## Common Services
| Domain | Service | Example entity_id |
|--------|---------|-------------------|
| `light` | `turn_on`, `turn_off`, `toggle` | `light.kitchen` |
| `switch` | `turn_on`, `turn_off`, `toggle` | `switch.fan` |
| `climate` | `set_temperature`, `set_hvac_mode` | `climate.thermostat` |
| `cover` | `open_cover`, `close_cover`, `stop_cover` | `cover.garage` |
| `media_player` | `play_media`, `media_pause`, `volume_set` | `media_player.tv` |
| `scene` | `turn_on` | `scene.relax` |
| `script` | `turn_on` | `script.welcome_home` |
| `automation` | `trigger`, `turn_on`, `turn_off` | `automation.sunrise` |
## Inbound Webhooks (HA → Clawdbot)
To receive events from Home Assistant automations:
### 1. Create HA Automation with Webhook Action
```yaml
# In HA automation
action:
- service: rest_command.notify_clawdbot
data:
event: motion_detected
area: living_room
```
### 2. Define REST Command in HA
```yaml
# configuration.yaml
rest_command:
notify_clawdbot:
url: "https://your-clawdbot-url/webhook/home-assistant"
method: POST
headers:
Authorization: "Bearer {{ webhook_secret }}"
Content-Type: "application/json"
payload: '{"event": "{{ event }}", "area": "{{ area }}"}'
```
### 3. Handle in Clawdbot
Clawdbot receives the webhook and can notify you or take action based on the event.
## CLI Wrapper
The `scripts/ha.sh` CLI provides easy access to all HA functions:
```bash
# Test connection
ha.sh info
# List entities
ha.sh list all # all entities
ha.sh list lights # just lights
ha.sh list switch # just switches
# Search entities
ha.sh search kitchen # find entities by name
# Get/set state
ha.sh state light.living_room
ha.sh states light.living_room # full details with attributes
ha.sh on light.living_room
ha.sh on light.living_room 200 # with brightness (0-255)
ha.sh off light.living_room
ha.sh toggle switch.fan
# Scenes & scripts
ha.sh scene movie_night
ha.sh script goodnight
# Climate
ha.sh climate climate.thermostat 22
# Call any service
ha.sh call light turn_on '{"entity_id":"light.room","brightness":200}'
```
## Troubleshooting
- **401 Unauthorized**: Token expired or invalid. Generate a new one.
- **Connection refused**: Check HA_URL, ensure HA is running and accessible.
- **Entity not found**: List entities to find the correct entity_id.
## API Reference
For advanced usage, see [references/api.md](references/api.md).
---
## 中文说明
# Home Assistant
通过 Home Assistant 的 REST API 和 webhook 控制你的智能家居。
## 设置
### 选项 1：配置文件（推荐）
创建 `~/.config/home-assistant/config.json`：
```json
{
"url": "https://your-ha-instance.duckdns.org",
"token": "your-long-lived-access-token"
}
```
### 选项 2：环境变量
```bash
export HA_URL="http://homeassistant.local:8123"
export HA_TOKEN="your-long-lived-access-token"
```
### 获取长期访问令牌
1. 打开 Home Assistant → Profile（左下角）
2. 滚动到 "Long-Lived Access Tokens"
3. 点击 "Create Token"，为其命名（例如 "Clawdbot"）
4. 立即复制令牌（仅显示一次）
## 快速参考
### 列出实体
```bash
curl -s -H "Authorization: Bearer $HA_TOKEN" "$HA_URL/api/states" | jq '.[].entity_id'
```
### 获取实体状态
```bash
curl -s -H "Authorization: Bearer $HA_TOKEN" "$HA_URL/api/states/light.living_room"
```
### 控制设备
```bash
# Turn on
curl -X POST -H "Authorization: Bearer $HA_TOKEN" -H "Content-Type: application/json" \
"$HA_URL/api/services/light/turn_on" -d '{"entity_id": "light.living_room"}'
# Turn off
curl -X POST -H "Authorization: Bearer $HA_TOKEN" -H "Content-Type: application/json" \
"$HA_URL/api/services/light/turn_off" -d '{"entity_id": "light.living_room"}'
# Set brightness (0-255)
curl -X POST -H "Authorization: Bearer $HA_TOKEN" -H "Content-Type: application/json" \
"$HA_URL/api/services/light/turn_on" -d '{"entity_id": "light.living_room", "brightness": 128}'
```
### 运行脚本与自动化
```bash
# Trigger script
curl -X POST -H "Authorization: Bearer $HA_TOKEN" "$HA_URL/api/services/script/turn_on" \
-H "Content-Type: application/json" -d '{"entity_id": "script.goodnight"}'
# Trigger automation
curl -X POST -H "Authorization: Bearer $HA_TOKEN" "$HA_URL/api/services/automation/trigger" \
-H "Content-Type: application/json" -d '{"entity_id": "automation.motion_lights"}'
```
### 激活场景
```bash
curl -X POST -H "Authorization: Bearer $HA_TOKEN" "$HA_URL/api/services/scene/turn_on" \
-H "Content-Type: application/json" -d '{"entity_id": "scene.movie_night"}'
```
## 常用服务
| 域 | 服务 | 示例 entity_id |
|--------|---------|-------------------|
| `light` | `turn_on`、`turn_off`、`toggle` | `light.kitchen` |
| `switch` | `turn_on`、`turn_off`、`toggle` | `switch.fan` |
| `climate` | `set_temperature`、`set_hvac_mode` | `climate.thermostat` |
| `cover` | `open_cover`、`close_cover`、`stop_cover` | `cover.garage` |
| `media_player` | `play_media`、`media_pause`、`volume_set` | `media_player.tv` |
| `scene` | `turn_on` | `scene.relax` |
| `script` | `turn_on` | `script.welcome_home` |
| `automation` | `trigger`、`turn_on`、`turn_off` | `automation.sunrise` |
## 入站 Webhook（HA → Clawdbot）
要从 Home Assistant 自动化接收事件：
### 1. 创建带 Webhook 动作的 HA 自动化
```yaml
# In HA automation
action:
- service: rest_command.notify_clawdbot
data:
event: motion_detected
area: living_room
```
### 2. 在 HA 中定义 REST 命令
```yaml
# configuration.yaml
rest_command:
notify_clawdbot:
url: "https://your-clawdbot-url/webhook/home-assistant"
method: POST
headers:
Authorization: "Bearer {{ webhook_secret }}"
Content-Type: "application/json"
payload: '{"event": "{{ event }}", "area": "{{ area }}"}'
```
### 3. 在 Clawdbot 中处理
Clawdbot 接收 webhook，并可以根据事件通知你或采取行动。
## CLI 封装
`scripts/ha.sh` CLI 提供了对所有 HA 功能的便捷访问：
```bash
# Test connection
ha.sh info
# List entities
ha.sh list all # all entities
ha.sh list lights # just lights
ha.sh list switch # just switches