Home Assistant

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

配置

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

创建 ~/.config/home-assistant/config.json：

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

选项 2：环境变量

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. 立即复制该令牌（仅显示一次）

快速参考

列出所有实体

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

常用服务

入站 Webhook（Home Assistant → Clawdbot）

如需接收来自 Home Assistant 自动化的事件，请按以下步骤操作：

1. 在 Home Assistant 中创建带 Webhook 动作的自动化

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

2. 在 Home Assistant 中定义 REST Command

# 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 提供对所有 Home Assistant 功能的便捷访问：

# 测试连接
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 Unauthorized（未授权）：令牌已过期或无效，请重新生成。
• Connection refused（连接被拒绝）：检查 HA_URL 配置是否正确，并确认 Home Assistant 正在运行且可正常访问。
• Entity not found（实体未找到）：使用列表命令查看所有实体，确认正确的 entity_id。

API 参考文档

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