Home Assistant

# 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" ```

### 获取长期访问令牌 (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

# 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}' ```

## 故障排除

- **401 Unauthorized**: 令牌过期或无效。请生成一个新的。 - **Connection refused**: 检查 HA_URL，确保 HA 正在运行且可访问。 - **Entity not found**: 列出实体以查找正确的 entity_id。

## API 参考

如需高级用法，请参阅 [references/api.md](references/api.md)。