---
name: xiaomi-home-ha
description: "Control Xiaomi/Mi Home smart devices via Home Assistant REST API (curl+jq). Use for lights, switches, sensors, AC, fans, media players, scenes — query state or call any HA service. 通过 HA REST API 控制小米智能家居设备。"
homepage: https://www.home-assistant.io/integrations/rest/
metadata: { "openclaw": { "emoji": "🏠", "requires": { "bins": ["curl", "jq"], "env": ["HA_URL", "HA_TOKEN"] }, "primaryEnv": "HA_TOKEN" } }
---

# 小米智能家居 (Xiao Mi Home for HA)

通过 Home Assistant REST API，用自然语言控制任意小米/米家智能设备。  
Control any Xiaomi/Mi Home smart device via Home Assistant REST API using natural language.

---

## 适用场景 / When to Use

✅ **适用 / USE when:**

- 控制灯光（开关、调光、色温、RGB）/ Control lights (on/off, brightness, color temp, RGB)
- 控制开关、插座、风扇 / Control switches, smart plugs, fans
- 控制空调、温控器 / Control air conditioners, thermostats
- 控制小米音箱、媒体播放器 / Control Xiaomi speakers, media players
- 查询任意设备状态 / Query any device state
- 读取温湿度、空气质量等传感器值 / Read temperature, humidity, air quality sensors
- 调用任意 HA 服务（脚本、场景、自动化）/ Call any HA service (scripts, scenes, automations)

❌ **不适用 / DON'T use when:**

- 未接入 Home Assistant 的设备 / Devices not connected to Home Assistant
- 纯云端米家 App（无本地 HA 实例）/ Cloud-only Mi Home App without local HA
- 非智能家居相关的任务 / Non-smart-home tasks

---

## 前置配置 / Setup

### 1. 配置项 / Required Config

| 变量 | 说明 | 是否必填 |
|------|------|----------|
| `HA_URL` | HA 地址，如 `http://192.168.31.202:8123` | ✅ 必填 |
| `HA_TOKEN` | 长期访问令牌 (Long-Lived Access Token) | ✅ 必填 |
| `HA_DEFAULT_ENTITY` | 未指定实体时的默认值，如 `light.bed_lamp` | 可选 |

### 2. 安装依赖 / Install Dependencies

本 skill 需要 `curl` 和 `jq`。`curl` 通常已预装；`jq` 按系统安装：

Ubuntu / Debian

sudo apt-get install -y jq

macOS

brew install jq

无 sudo 备用（需要 Node.js）

npm i -g node-jq # 安装后 jq 命令即可用

验证: `jq --version`

### 3. 获取 Token / How to Get Token

> HA Web → 右下角头像 → **安全** → **长期访问令牌** → **创建令牌** → 复制  
> HA UI → Profile → Security → Long-Lived Access Tokens → Create Token

### 4. 写入配置（三种方式）/ Configure (3 ways)

**方式 A — 飞书/客户端（最简，无需开终端）**

在飞书对话中直接发给 AI：

> 帮我配置小米智能家居 skill，HA 地址 http://192.168.31.202:8123，token 是 eyJhbGc...

AI 会自动运行 `openclaw config set` 完成写入。

**方式 B — 命令行 / CLI**

openclaw config set 'skills."xiaomi-home-ha".env.HA_URL' "http://192.168.31.202:8123"

openclaw config set 'skills."xiaomi-home-ha".env.HA_TOKEN' "eyJhbGc..."

可选 / optional

openclaw config set 'skills."xiaomi-home-ha".env.HA_DEFAULT_ENTITY' "light.bed_lamp"

**方式 C — 直接编辑 `~/.openclaw/openclaw.json`**

{

"skills": {

"entries": {

"xiaomi-home-ha": {

"env": {

"HA_URL": "http://192.168.31.202:8123",

"HA_TOKEN": "eyJhbGc...",

"HA_DEFAULT_ENTITY": "light.bed_lamp"

}

}

}

}

}

> 配置写入后重新开启一个会话即生效（OpenClaw 每次会话启动时注入 env）。  
> Changes take effect on the next new session.

### 5. 验证连接 / Verify Connection

curl -sf "${HA_URL}/api/" \

-H "Authorization: Bearer ${HA_TOKEN}"

预期输出 / Expected output:

{ "message": "API running." }

---

## 核心 API 模型 / Core API Pattern

所有操作基于两个通用端点，AI 根据意图自动填充变量：  
All operations use two universal endpoints; the AI fills in variables based on intent:

### 查询状态 / Query State

查询所有实体 / Query all entities

GET ${HA_URL}/api/states

查询单个实体 / Query single entity

GET ${HA_URL}/api/states/${ENTITY_ID}

### 执行操作 / Execute Action

通用操作模板 / Universal action template

POST ${HA_URL}/api/services/${DOMAIN}/${SERVICE}

Body: { "entity_id": "${ENTITY_ID}", ...service_data }

**AI 工作流 / AI Workflow:**
1. 从 `entity_id` 拆出 `domain`（如 `light.bed_lamp` → `domain=light`）
2. 根据用户意图选择 `service`（如 "开" → `turn_on`，"暂停" → `media_pause`）
3. 构造 `service_data`（可选附加参数，如亮度、温度等）

---

## 查询设备 / Query Entities

### 列出所有设备 / List All Entities

查询所有受控实体（含状态）/ All entities with state

curl -sf "${HA_URL}/api/states" \

-H "Authorization: Bearer ${HA_TOKEN}" \

| jq '[.[] | {entity_id, state, name: .attributes.friendly_name}]'

### 按前缀过滤域 / Filter by Domain Prefix

变量：DOMAIN_PREFIX = light / switch / sensor / media_player / climate / fan 等

Variable: DOMAIN_PREFIX = light / switch / sensor / media_player / climate / fan etc.

DOMAIN_PREFIX="light"

curl -sf "${HA_URL}/api/states" \

-H "Authorization: Bearer ${HA_TOKEN}" \

| jq --arg prefix "${DOMAIN_PREFIX}." \

'[.[] | select(.entity_id | startswith($prefix))

| {entity_id, state,

name: .attributes.friendly_name,

extra: .attributes}]'

### 按区域过滤 / Filter by Area

AREA_KEYWORD="bedroom" # 中文也可以 / Chinese also works, e.g. "卧室"

curl -sf "${HA_URL}/api/states" \

-H "Authorization: Bearer ${HA_TOKEN}" \

| jq --arg area "${AREA_KEYWORD}" \

'[.[] | select(

(.attributes.friendly_name // "" | ascii_downcase | contains($area)) or

(.attributes.area_id // "" | ascii_downcase | contains($area))

) | {entity_id, state, name: .attributes.friendly_name}]'

### 查询单个实体完整状态 / Full State for One Entity

ENTITY_ID="light.bed_lamp"

curl -sf "${HA_URL}/api/states/${ENTITY_ID}" \

-H "Authorization: Bearer ${HA_TOKEN}" \

| jq '{

entity_id,

state,

name: .attributes.friendly_name,

attributes: .attributes,

last_updated

}'

---

## 控制设备 / Control Devices

所有控制操作共用一套模板，只需替换 `DOMAIN`、`SERVICE`、`ENTITY_ID`、`SERVICE_DATA`。  
All control operations share one template — just swap `DOMAIN`, `SERVICE`, `ENTITY_ID`, `SERVICE_DATA`.

### 通用操作模板 / Universal Control Template

必填变量 / Required variables

ENTITY_ID="light.bed_lamp" # 实体 ID / entity ID

DOMAIN="${ENTITY_ID%%.*}" # 自动从 entity_id 拆出 / auto-extracted from entity_id

SERVICE="turn_on" # HA 服务名 / HA service name

SERVICE_DATA='{"transition": 0.5}' # 附加参数（可为空对象）/ extra params (can be {})

curl -sf -X POST "${HA_URL}/api/services/${DOMAIN}/${SERVICE}" \

-H "Authorization: Bearer ${HA_TOKEN}" \

-H "Content-Type: application/json" \

-d "$(jq -n \

--arg eid "${ENTITY_ID}" \

--argjson extra "${SERVICE_DATA}" \

'{entity_id: $eid} + $extra')"

### 开 / 关 / 切换 — Turn On / Off / Toggle

任意实体均适用 / Works for any entity

ENTITY_ID="switch.fan"

curl -sf -X POST "${HA_URL}/api/services/${ENTITY_ID%%.*}/turn_on" \

-H "Authorization: Bearer ${HA_TOKEN}" \

-H "Content-Type: application/json" \

-d "{\"entity_id\": \"${ENTITY_ID}\"}"

关闭 / Turn off

curl -sf -X POST "${HA_URL}/api/services/${ENTITY_ID%%.*}/turn_off" \

-H "Authorization: Bearer ${HA_TOKEN}" \

-H "Content-Type: application/json" \

-d "{\"entity_id\": \"${ENTITY_ID}\"}"

切换 / Toggle

curl -sf -X POST "${HA_URL}/api/services/${ENTITY_ID%%.*}/toggle" \

-H "Authorization: Bearer ${HA_TOKEN}" \

-H "Content-Type: application/json" \

-d "{\"entity_id\": \"${ENTITY_ID}\"}"

### 带附加参数的服务调用 / Service Call with Extra Parameters

示例 1：调节灯光亮度至 40% + 色温 3000K / Light: brightness 40% + color temp 3000K

ENTITY_ID="light.ceiling"

curl -sf -X POST "${HA_URL}/api/services/light/turn_on" \

-H "Authorization: Bearer ${HA_TOKEN}" \

-H "Content-Type: application/json" \

-d "{

\"entity_id\": \"${ENTITY_ID}\",

\"brightness_pct\": 40,

\"color_temp_kelvin\": 3000,

\"transition\": 0.5

}"

示例 2：空调设置温度 / Climate: set temperature

ENTITY_ID="climate.bedroom_ac"

curl -sf -X POST "${HA_URL}/api/services/climate/set_temperature" \

-H "Authorization: Bearer ${HA_TOKEN}" \

-H "Content-Type: application/json" \

-d "{

\"entity_id\": \"${ENTITY_ID}\",

\"temperature\": 26,

\"hvac_mode\": \"cool\"

}"

示例 3：媒体播放器音量 / Media player: set volume

ENTITY_ID="media_player.xiaomi_speaker"

curl -sf -X POST "${HA_URL}/api/services/media_player/volume_set" \

-H "Authorization: Bearer ${HA_TOKEN}" \

-H "Content-Type: application/json" \

-d "{

\"entity_id\": \"${ENTITY_ID}\",

\"volume_level\": 0.5

}"

示例 4：执行场景 / Activate a scene

ENTITY_ID="scene.bedtime_mode"

curl -sf -X POST "${HA_URL}/api/services/scene/turn_on" \

-H "Authorization: Bearer ${HA_TOKEN}" \

-H "Content-Type: application/json" \

-d "{\"entity_id\": \"${ENTITY_ID}\"}"

### 操作后读取最新状态 / Read State After Action

建议操作后等待 600ms 再查询（HA 状态有短暂延迟）

Wait 600ms after action before querying (HA state has brief delay)

sleep 0.6

curl -sf "${HA_URL}/api/states/${ENTITY_ID}" \

-H "Authorization: Bearer ${HA_TOKEN}" \

| jq '{state, name: .attributes.friendly_name, attributes: .attributes}'

---

## 常用 service_data 参数速查 / Common service_data Parameters

以下参数按**参数类型**而非设备类型分组，可组合使用：  
Parameters grouped by **type** (not device), combinable as needed:

| 参数 / Parameter | 适用域 / Domain | 说明 / Description | 示例值 / Example |
|---|---|---|---|
| `brightness_pct` | `light` | 亮度百分比 / Brightness % | `0` – `100` |
| `color_temp_kelvin` | `light` | 色温 Kelvin / Color temp K | `2700` (暖) ~ `6500` (冷) |
| `rgb_color` | `light` | RGB 颜色 / RGB color | `[255, 100, 0]` |
| `transition` | `light` | 过渡秒数 / Fade seconds | `0.5` |
| `temperature` | `climate` | 目标温度℃ / Target temp °C | `26` |
| `hvac_mode` | `climate` | 运行模式 / HVAC mode | `"cool"` `"heat"` `"auto"` `"off"` |
| `volume_level` | `media_player` | 音量 0-1 / Volume 0-1 | `0.5` |
| `percentage` | `fan` | 风速百分比 / Fan speed % | `0` – `100` |
| `media_content_id` | `media_player` | 播放内容 ID / Content ID | `"spotify:..."` |
| `media_content_type` | `media_player` | 内容类型 / Content type | `"music"` |

---

## 快捷场景 / Quick Recipes

### 睡前场景 / Bedtime Mode

所有灯调至 10% 暖黄 / All lights dim warm

for entity in light.bedroom light.corridor; do

curl -sf -X POST "${HA_URL}/api/services/light/turn_on" \

-H "Authorization: Bearer ${HA_TOKEN}" \

-H "Content-Type: application/json" \

-d "{\"entity_id\": \"${entity}\", \"brightness_pct\": 10, \"color_temp_kelvin\": 2700}" &

done

wait

### 读取室内环境 / Read Indoor Environment

一次性读取温湿度等所有 sensor 值

curl -sf "${HA_URL}/api/states" \

-H "Authorization: Bearer ${HA_TOKEN}" \

| jq '[.[] | select(.entity_id | startswith("sensor."))

| select(.attributes.device_class // "" | IN("temperature","humidity","pm25","co2"))

| {

entity_id,

name: .attributes.friendly_name,

value: .state,

unit: .attributes.unit_of_measurement,

type: .attributes.device_class

}]'

### 批量关闭所有设备 / Turn Off All Devices

关闭所有灯和开关 / Turn off all lights and switches

for domain in light switch; do

curl -sf "${HA_URL}/api/states" \

-H "Authorization: Bearer ${HA_TOKEN}" \

| jq -r --arg d "${domain}." '[.[] | select(.entity_id | startswith($d)) | .entity_id] | .[]' \

| while read -r eid; do

curl -sf -X POST "${HA_URL}/api/services/${domain}/turn_off" \

-H "Authorization: Bearer ${HA_TOKEN}" \

-H "Content-Type: application/json" \

-d "{\"entity_id\": \"${eid}\"}" > /dev/null

echo "✓ off: ${eid}"

done

done

---

## 注意事项 / Notes

- **状态延迟**：操作后建议 `sleep 0.6` 再查询，HA 需时同步设备状态  
  **State latency**: Wait `sleep 0.6` after actions before re-querying; HA needs time to sync

- **Token 安全**：`HA_TOKEN` 应存在 shell profile 而非明文传入命令  
  **Token security**: Keep `HA_TOKEN` in shell profile, not hardcoded in commands

- **过渡动画**：`"transition": 0.5` 使灯光平滑变化；开关类设备忽略此参数  
  **Transitions**: `"transition": 0.5` enables smooth changes for lights; ignored by switches

- **entity_id 发现**：不确定实体 ID 时先用"查询设备"命令列出所有实体  
  **Discovering entities**: Use the query commands to list entities when unsure of entity_id

- **401 错误**：Token 错误或已过期，重新在 HA 创建  
  **401 error**: Token invalid or expired — recreate in HA Profile → Security

- **404 错误**：entity_id 不存在，先列出所有实体后再操作  
  **404 error**: entity_id does not exist — list all entities first

---

## 发布信息 / Publishing

校验格式 / Validate format

clawhub validate ./skills/xiaomi-home-ha

发布到 ClawHub / Publish to ClawHub

clawhub publish ./skills/xiaomi-home-ha \

--slug xiaomi-home-ha \

--name "小米智能家居 (Xiao Mi Home for HA)" \

--version 1.0.0 \

--changelog "Initial release: full Xiaomi/HA device control via curl + jq"

安装验证 / Verify installation

clawhub install xiaomi-home-ha

clawhub list | grep xiaomi-home-ha