OpenClaw Home Assistant 技能指南

OpenClaw Home Assistant 技能概述

Home Assistant 技能将 OpenClaw 连接到你的 Home Assistant 实例，将你的 AI 智能体变成强大的智能家居控制器。无需在仪表盘中导航或编辑 YAML 配置文件，你可以通过自然语言管理整个智能家居——切换灯光、查看传感器读数、创建自动化、排查设备问题，一切都在终端中完成。

Home Assistant 是全球最大的开源家庭自动化（Home Automation）平台，支持超过 2,000 种设备集成，包括 Philips Hue、Zigbee、Z-Wave、Matter 等数百种协议和品牌。OpenClaw Home Assistant 技能利用 Home Assistant REST API 让你的智能体直接访问实例上运行的实体、服务、自动化和脚本。

典型工作流：

1. 让 OpenClaw 关闭客厅所有灯光并将恒温器设置为 20°C。
2. 智能体调用 Home Assistant API，识别相关实体并执行服务调用。
3. 即刻返回确认——无需打开 Home Assistant 应用或仪表盘。

该技能非常适合已经在运行 Home Assistant 的开发者，让他们以更快、可脚本化的方式访问智能家居。它与 Slack 技能搭配使用可将智能家居通知发送到团队频道，如果你在容器中运行 Home Assistant，还能与基于 Docker 的部署自然集成。

Home Assistant 技能安装前的准备

安装 Home Assistant 技能之前，请确保你具备以下条件：

• OpenClaw 已安装并运行（v1.0+）
• 一个可通过网络访问的 Home Assistant 实例（v2023.1+）——安装指南
• 从 Home Assistant 个人资料中生成的长期访问令牌（Long-Lived Access Token）
• 从你的机器到 Home Assistant 实例的网络访问（本地或远程）
• 已安装 clawhub CLI 用于技能管理

验证你的环境：

# 检查 OpenClaw 版本
openclaw --version

# 测试 Home Assistant API 连通性
curl -s -H "Authorization: Bearer YOUR_TOKEN" \
  http://YOUR_HA_HOST:8123/api/ | head -1

# 检查 clawhub CLI
clawhub --version

如果 API 返回 {"message": "API running."}，说明你的 Home Assistant 实例已就绪。

如何安装 Home Assistant 技能

使用一条命令安装 Home Assistant 技能：

npx clawhub@latest install home-assistant

验证安装结果：

clawhub list

你应该在已安装技能列表中看到 home-assistant。使用 clawhub CLI 安装可获得最快的设置体验。

Home Assistant 技能配置指南

该技能需要 Home Assistant URL 和长期访问令牌来验证 API 请求。

生成长期访问令牌

1. 打开你的 Home Assistant 仪表盘，地址为 http://YOUR_HA_HOST:8123。
2. 点击左下角的个人资料图标。
3. 滚动到长期访问令牌部分，点击创建令牌。
4. 将其命名为 openclaw-agent，并复制生成的令牌。

环境变量配置

设置以下环境变量：

# Home Assistant 实例 URL（如使用非标准端口请包含端口号）
export HOMEASSISTANT_URL="http://192.168.1.100:8123"

# 长期访问令牌
export HOMEASSISTANT_TOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6..."

你可以将这些变量添加到 shell 配置文件（~/.bashrc、~/.zshrc）或使用 .env 文件配合密钥管理工具。

重要提示： 切勿将令牌硬编码在配置文件中或提交到版本控制系统。请使用环境变量或专用的密钥管理工具，如 1Password。

可选：远程访问

如果你的 Home Assistant 实例不在同一网络中，可通过以下方式配置远程访问：

| 方式 | 描述 | |------|------| | Nabu Casa | Home Assistant Cloud——最简单的选项，提供远程 URL | | 反向代理 | 使用 Nginx 或 Caddy 进行 SSL 终结 | | Tailscale/WireGuard | VPN 隧道，提供安全的类局域网访问 |

Home Assistant 技能使用示例

1. 控制灯光和设备

你："关闭卧室所有灯光，并将客厅亮度设置为 40%。"

智能体对卧室实体调用 light.turn_off，对客厅灯光调用 light.turn_on 并设置 brightness_pct: 40。它通过房间分配识别实体，并返回确认摘要。

2. 查询传感器数据

你："办公室当前温度是多少？今天的总能耗是多少？"

智能体查询 sensor.office_temperature 和 sensor.energy_daily 实体，返回格式化的读数："办公室温度：22.3°C。今日能耗：14.7 kWh。"它会处理单位转换并格式化数据以提高可读性。

3. 创建自动化

你："创建一个自动化，在日落时打开门廊灯，每晚 11 点关闭。"

智能体使用 sun 触发器处理日落事件，使用 time 触发器处理 23:00。它通过 API 注册自动化，分配一个描述性名称，并确认已启用。

4. 激活场景

你："激活电影之夜场景。"

智能体对 scene.movie_night 调用 scene.turn_on，该场景会调暗灯光、关闭窗帘并将媒体播放器设置为正确的输入源——所有配置都基于你现有的场景定义。

5. 排查设备状态

你："哪些设备当前不可用或离线？"

智能体查询所有状态为 unavailable 或 unknown 的实体，按集成分组，并返回诊断报告："3 个设备离线——Zigbee 运动传感器（最后在线 2 小时前）、厨房智能插座（无法连接）、天气集成（API 超时）。"

安全与最佳实践

遵循以下指南以确保智能家居安全：

• 使用最小权限原则。 为 OpenClaw 创建一个专用的 Home Assistant 用户，权限仅限于你希望智能体控制的房间和设备。避免使用管理员账户的令牌。
• 执行前确认。 智能体在执行删除自动化或禁用集成等破坏性操作之前，会描述其计划的操作。请始终审查操作摘要。
• 妥善保管令牌。 长期访问令牌提供完整的 API 访问权限。将其存储在环境变量中，切勿存放在纯文本文件中。定期从 Home Assistant 个人资料中轮换令牌。
• 使用 HTTPS。 如果远程访问 Home Assistant，请始终使用带有有效 SSL 证书的 HTTPS。切勿在没有加密的情况下将实例暴露在公共互联网上。
• 限制网络访问。 使用 Home Assistant 的 ip_bans 或防火墙规则将 API 访问限制在受信任的 IP 范围内。查阅安全检查清单了解通用的 OpenClaw 安全指南。

常见错误与故障排除

"401 Unauthorized — Invalid access token"

长期访问令牌无效或已过期。

1. 验证令牌是否正确设置：

echo $HOMEASSISTANT_TOKEN

2. 从 Home Assistant 个人资料页面生成新令牌。
3. 确保令牌值中没有多余的空格或换行符。

"Connection refused — Cannot reach Home Assistant"

智能体无法连接到你的 Home Assistant 实例。

1. 验证 URL 是否正确且包含端口：

curl -s http://YOUR_HA_HOST:8123/api/

2. 检查 Home Assistant 是否正在运行：sudo systemctl status homeassistant（适用于 Supervised 安装）。
3. 如果使用 Docker，确认容器正在运行：docker ps | grep homeassistant。
4. 检查防火墙规则——端口 8123 必须从你的机器可访问。

"Entity not found — light.living_room"

实体 ID 与 Home Assistant 中的任何设备不匹配。

1. 列出所有可用实体：

curl -s -H "Authorization: Bearer $HOMEASSISTANT_TOKEN" \
  http://YOUR_HA_HOST:8123/api/states | jq '.[].entity_id' | grep light

2. 实体 ID 区分大小写且使用下划线——检查是否有拼写错误。
3. 如果设备是最近添加的，重启 Home Assistant 以刷新实体注册。