Home Assistant

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

设置

选项一：配置文件（推荐）

创建文件~/.config/home-assistant/config.json，内容如下：

{
  "url": "https://your-ha-instance.duckdns.org",
  "token": "your-long-lived-access-token"
}

选项二：环境变量

export HA_URL="http://homeassistant.local:8123"
export HA_TOKEN="your-long-lived-access-token"

获取长期访问令牌

1. 打开 Home Assistant → 点击左下角个人资料
2. 滚动到"长期访问令牌"部分
3. 点击"创建令牌"，为其命名（例如，"Clawdbot"）
4. 立即复制令牌（仅显示一次）

快速参考

列出所有实体

curl -s -H "Authorization: Bearer $HA_TOKEN" "$HA_URL/api/states" | jq '.[].entity_id'

获取实体状态

curl -s -H "Authorization: Bearer $HA_TOKEN" "$HA_URL/api/states/light.living_room"

控制设备

# 打开
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"}'

# 关闭
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"}'

# 设置亮度 (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}'

运行脚本与自动化

# 触发脚本
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"}'

# 触发自动化
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"}'

激活场景

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"}'

常用服务

入站 Webhooks (HA → Clawdbot)

要从 Home Assistant 自动化接收事件：

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

# 在 HA 自动化中
action:
  - service: rest_command.notify_clawdbot
    data:
      event: motion_detected
      area: living_room

2. 在 HA 中定义 REST 命令

# 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.shCLI 提供对所有 HA 功能的便捷访问：# 测试连接 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 turn_on '{"entity_id":"light.room","brightness":200}'

故障排除

401 未授权

• ：令牌过期或无效。请生成一个新的。连接被拒绝
• ：检查 HA_URL，确保 HA 正在运行且可访问。未找到实体
• ：列出实体以找到正确的 entity_id。API 参考

对于高级用法，请参阅

references/api.md。.