Home Assistant

通过 Home Assistant 的 REST API 和 webhooks 控制您的智能家居。

设置

选项 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. 1. 打开 Home Assistant → 个人资料（左下角）
2. 滚动到长期访问令牌
3. 点击创建令牌，为其命名（例如：Clawdbot）
4. 立即复制令牌（仅显示一次）

快速参考

列出实体

bash
curl -s -H Authorization: Bearer $HATOKEN $HAURL/api/states | jq .[].entity_id

获取实体状态

bash
curl -s -H Authorization: Bearer $HATOKEN $HAURL/api/states/light.living_room

控制设备

bash

开启

curl -X POST -H Authorization: Bearer $HA_TOKEN -H Content-Type: application/json \
$HAURL/api/services/light/turnon -d {entityid: light.livingroom}

关闭

curl -X POST -H Authorization: Bearer $HA_TOKEN -H Content-Type: application/json \ $HAURL/api/services/light/turnoff -d {entityid: light.livingroom}

设置亮度（0-255）

curl -X POST -H Authorization: Bearer $HA_TOKEN -H Content-Type: application/json \ $HAURL/api/services/light/turnon -d {entityid: light.livingroom, brightness: 128}

运行脚本和自动化

bash

触发脚本

curl -X POST -H Authorization: Bearer $HATOKEN $HAURL/api/services/script/turn_on \
-H Content-Type: application/json -d {entity_id: script.goodnight}

触发自动化

curl -X POST -H Authorization: Bearer $HATOKEN $HAURL/api/services/automation/trigger \ -H Content-Type: application/json -d {entityid: automation.motionlights}

激活场景

bash
curl -X POST -H Authorization: Bearer $HATOKEN $HAURL/api/services/scene/turn_on \
-H Content-Type: application/json -d {entityid: scene.movienight}

常用服务

域	服务	示例 entityid
light	turnon, turnoff, toggle	light.kitchen
switch

turnon, turn_off, toggle | switch.fan | | climate | settemperature, sethvac_mode | climate.thermostat | | cover | opencover, closecover, stop_cover | cover.garage | | mediaplayer | playmedia, mediapause, volumeset | media_player.tv | | scene | turn_on | scene.relax | | script | turnon | script.welcomehome | | automation | trigger, turnon, turnoff | automation.sunrise |

入站 Webhooks（HA → Clawdbot）

从 Home Assistant 自动化接收事件：

1. 创建带 Webhook 动作的 HA 自动化

yaml

在 HA 自动化中

action:
- service: restcommand.notifyclawdbot
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

测试连接

ha.sh info

列出实体

ha.sh list all # 所有实体 ha.sh list lights # 仅灯光 ha.sh list switch # 仅开关

搜索实体

ha.sh search kitchen # 按名称查找实体

获取/设置状态

ha.sh state light.living_room ha.sh states light.living_room # 完整详情及属性 ha.sh on light.living_room ha.sh on light.living_room 200 # 带亮度（0-255） ha.sh off light.living_room ha.sh toggle switch.fan

场景和脚本

ha.sh scene movie_night ha.sh script goodnight

气候

ha.sh climate climate.thermostat 22

调用任意服务

ha.sh call light turnon {entityid:light.room,brightness:200}

故障排除

• - 401 未授权：令牌过期或无效。生成新令牌。
• 连接被拒绝：检查 HAURL，确保 HA 正在运行且可访问。
• 实体未找到：列出实体以找到正确的 entityid。

API 参考

有关高级用法，请参阅 references/api.md。