什么是 Home Assistant？

Home Assistant 技能允许您的 AI 代理与您的智能家居生态系统直接交互。通过利用 Home Assistant REST API，此技能能够查询设备状态并在照明、气候控制和媒体播放等广泛领域执行服务调用。它专为希望将 Openclaw Skills 的能力引入物理环境以增强自动化的用户而设计。

除了简单的出站命令，该技能还支持入站 Webhooks，允许 Home Assistant 触发代理工作流中的操作。这创建了一个真正响应迅速的智能环境，物理事件（如运动检测或门传感器）可以通知代理的逻辑和决策过程。

下载入口:https://github.com/openclaw/skills/tree/main/skills/patrykszczypkowski/home-assistant-patryk

安装与下载

1. ClawHub CLI

从源直接安装技能的最快方式。

2. 手动安装

将技能文件夹复制到以下位置之一

优先级：工作区 > 本地 > 内置

3. 提示词安装

将此提示词复制到 OpenClaw 即可自动安装。

Home Assistant 应用场景

• 根据您的工作安排自动化家庭办公室的照明和温度。
• 创建“专注模式”场景，通过单个命令调整灯光和切换开关。
• 通过入站 Webhooks 接收来自 Home Assistant 传感器的实时通知。
• 直接从您的开发终端监控能源使用情况或设备状态。

1. 该技能使用长效访问令牌（Long-Lived Access Token）连接到您的 Home Assistant 实例，以进行安全身份验证。
2. 它利用 curl 和 jq 与 REST API 端点通信，用于获取实体状态和列出可用设备。
3. 命令作为 POST 请求发送到 Home Assistant 服务，以更改状态或触发自动化。
4. 对于入站通信，Home Assistant 向指定的 Webhook URL 发送 POST 请求，允许代理对家庭事件做出反应。
5. 专用 CLI 封装程序将复杂的 API 调用简化为对用户而言简短、可操作的命令。

Home Assistant 配置指南

首先，确保您的系统上安装了 jq 和 curl。然后，您必须从 Home Assistant 配置文件设置中获取长效访问令牌。您可以使用位于 ~/.config/home-assistant/config.json 的配置文件来配置该技能：

{
  "url": "http://:8123",
  "token": ""
}

或者，在 shell 中设置环境变量：

export HA_URL="http://:8123"
export HA_TOKEN=""

Home Assistant 数据架构与分类体系

该技能根据 Home Assistant 实体模型和服务注册表组织交互数据。它主要处理表示设备状态的 JSON 负载。

name: home-assistant
description: Control Home Assistant smart home devices, run automations, and receive webhook events. Use when controlling lights, switches, climate, scenes, scripts, or any HA entity. Supports bidirectional communication via REST API (outbound) and webhooks (inbound triggers from HA automations).
metadata: {"clawdbot":{"emoji":"??","requires":{"bins":["jq","curl"]}}}

Home Assistant

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

Setup

Option 1: Config File (Recommended)

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

{
  "url": "http://192.168.1.32:8123",
  "token": ""
}

Option 2: Environment Variables

export HA_URL="http://192.168.1.32:8123"
export HA_TOKEN=""

Getting a Long-Lived Access Token

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

Quick Reference

List Entities

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

Get Entity State

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

Control Devices

# Turn on
curl -X POST -H "Authorization: Bearer $HA_TOKEN" -H "Content-Type: application/json" r
  "$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" r
  "$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" r
  "$HA_URL/api/services/light/turn_on" -d '{"entity_id": "light.living_room", "brightness": 128}'

Run Scripts & Automations

# Trigger script
curl -X POST -H "Authorization: Bearer $HA_TOKEN" "$HA_URL/api/services/script/turn_on" r
  -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" r
  -H "Content-Type: application/json" -d '{"entity_id": "automation.motion_lights"}'

Activate Scenes

curl -X POST -H "Authorization: Bearer $HA_TOKEN" "$HA_URL/api/services/scene/turn_on" r
  -H "Content-Type: application/json" -d '{"entity_id": "scene.movie_night"}'

Common Services

Inbound Webhooks (HA → Clawdbot)

To receive events from Home Assistant automations:

1. Create HA Automation with Webhook Action

# In HA automation
action:
  - service: rest_command.notify_clawdbot
    data:
      event: motion_detected
      area: living_room

2. Define REST Command in HA

# 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. Handle in Clawdbot

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

CLI Wrapper

The scripts/ha.sh CLI provides easy access to all HA functions:

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

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.

Local Entity Map

For this setup, also use references/local-entities.md for friendly-name mappings (e.g., desk lamp, ceiling light).

API Reference

For advanced usage, see references/api.md.