home-assistant

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Home Assistant

Control your smart home via Home Assistant's REST API and webhooks.

通过Home Assistant的REST API和webhook控制你的智能家居。

Setup

安装配置

Option 1: Config File (Recommended)

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

Create

~/.config/home-assistant/config.json

json

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

创建

~/.config/home-assistant/config.json

：

json

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

Option 2: Environment Variables

选项2：环境变量

bash

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

bash

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

Getting a Long-Lived Access Token

获取长期访问令牌

Open Home Assistant → Profile (bottom left)
Scroll to "Long-Lived Access Tokens"
Click "Create Token", name it (e.g., "Clawdbot")
Copy the token immediately (shown only once)

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

Quick Reference

快速参考

List Entities

列出所有实体

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" | jq '.[].entity_id'

Get Entity State

获取实体状态

bash

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

bash

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

Control Devices

控制设备

bash

undefined

bash

undefined

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)

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

undefined

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

undefined

Run Scripts & Automations

运行脚本与自动化任务

bash

undefined

bash

undefined

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

undefined

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

undefined

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

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`

领域	服务	示例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)

入站Webhook（HA → Clawdbot）

To receive events from Home Assistant automations:

要接收来自Home Assistant自动化的事件：

1. Create HA Automation with Webhook Action

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

yaml

undefined

yaml

undefined

In HA automation

在HA自动化中

action:

service: rest_command.notify_clawdbot data: event: motion_detected area: living_room

undefined

action:

service: rest_command.notify_clawdbot data: event: motion_detected area: living_room

undefined

2. Define REST Command in HA

2. 在HA中定义REST命令

yaml

undefined

yaml

undefined

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

undefined

undefined

3. Handle in Clawdbot

3. 在Clawdbot中处理事件

Clawdbot receives the webhook and can notify you or take action based on the event.

Clawdbot会接收webhook，并可根据事件向你发送通知或执行相应操作。

CLI Wrapper

CLI封装工具

The

scripts/ha.sh

CLI provides easy access to all HA functions:

bash

undefined

scripts/ha.sh

CLI工具可让你便捷访问所有HA功能：

bash

undefined

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

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

Search entities

搜索实体

ha.sh search kitchen # find entities by name

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

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

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

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

undefined

ha.sh call light turn_on '{"entity_id":"light.room","brightness":200}'

undefined

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.

401 Unauthorized：令牌过期或无效。重新生成新令牌。
Connection refused：检查HA_URL，确保HA正在运行且可访问。
Entity not found：列出所有实体以找到正确的entity_id。

API Reference

API参考

For advanced usage, see references/api.md.

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