Home Assistant Skill：安装、连接选择与首次传感器查询

Home Assistant Skill 适合已经有 Home Assistant、想让 Agent 查设备状态和排查能力的读者。先完成“读一个传感器并解释结果”，再考虑控制设备。它不是智能家居服务器，也不会因为装好了 Skill 就自动登录你的家庭系统。

先选连接方式

你的情况	从哪里开始
已连接原生 Home Assistant MCP，工具能完成日常查询	先用已有工具；核对其实际开放范围
需要读取精确实体、安装版本、动作字段	使用本 Skill 的 REST 只读助手
需要设备与区域映射、自动化定义或 Energy 统计	进一步阅读仓库的 WebSocket 工作流

不要为了试用重复搭建 MCP 桥接。MCP 和直接 API 的权限范围不同：Assist 的实体开放名单不会限制另一个 REST 令牌。当前 HA MCP 配置还可能开放全部 LLM APIs 并要求管理员，不能一概称为低权限连接。

在 Claude Code 安装

以下是终端命令，不是聊天提示。先检查目标目录不存在；已有安装不要覆盖，先核对本地改动。本指南对应上游 2.2.0 的以下提交，固定提交便于对照步骤：

命令

git clone https://github.com/anotb/homeassistant-skill.git ~/.claude/skills/homeassistant-skill
git -C ~/.claude/skills/homeassistant-skill checkout 3b5f34a90b927b4ea27a2c3a944c1d69f6e6a923

重新打开 Claude Code 会话，确认能识别 homeassistant-skill。此路径安装只适用于 Claude Code；其他 Agent 的技能目录应按客户端说明配置，不要照搬。ClawHub 也有同名条目，但注册版本与 GitHub 提交可能不同，先核对是否包含这里使用的助手脚本。

首次 REST 任务需要 Python 3.10+，无需额外 Python 包。在 Windows 用可用的 Python 3 命令 python 替换 python3，并使用你的实际安装路径。OpenClaw 的就绪检查另要求 curl、jq、HA_URL 和 HA_TOKEN；Python 能运行脚本，不等于 OpenClaw 的依赖检查通过。

准备地址、令牌和一个实体

在自己的 HA 页面选一个允许读取的温度或连接状态传感器，记下精确 entity_id，例如 sensor.kitchen_temperature。这是占位名称，必须换成你真实存在的实体。不要从“厨房温度”这样的显示名称猜 ID。

在运行 Agent/脚本的本地进程中，通过私有环境设置 HA_URL 和 HA_TOKEN。HA_URL 是可信的基础地址，如 https://ha.example.com:8123，不是 /api、/api/mcp 或登录页面。替换示例地址；远程使用证书有效的 HTTPS。本地 HTTP 不加密令牌，不要为练习开放公网端口。

HA_TOKEN 使用你已经授权提供的访问令牌，不能填浏览器密码；浏览器已登录也不会给终端自动设置令牌。没有令牌时，由本人在自己的 HA 个人资料 → Security → Long-lived access tokens 创建并妥善保存令牌，再继续；这会建立持续访问权限，应先确认所用账号和用途。不要把真实令牌粘到聊天、命令参数或仓库里。确保 Agent 启动时继承了相同环境，而不是只在另一个终端标签页设置过。

下面是在 Bash 终端给当前进程设置已有令牌的一种方式；先替换地址，第二条运行后私下输入令牌，不会显示输入字符。不要在开启 shell tracing 的环境操作。随后从同一终端启动 Claude Code，或直接运行下面的脚本；不要把这段当作 PowerShell 命令。

命令

export HA_URL='https://ha.example.com:8123'
read -r -s -p 'Existing HA token: ' HA_TOKEN
export HA_TOKEN

令牌拥有其 HA 账号的权限；脚本允许的只读命令只是本地限制，并未把令牌变成服务器端只读凭据。

首次任务：只读一个传感器

在本地终端进入 Skill 文件夹，先检查接口连接：

命令

cd ~/.claude/skills/homeassistant-skill
python3 scripts/ha_read.py get /api/
python3 scripts/ha_read.py profile
python3 scripts/ha_read.py get /api/states/sensor.kitchen_temperature

第三条换成刚才选择的实体。按顺序执行，出错先停下；不要一边出现 401 一边继续猜测设备是否离线。profile 输出安装版本、单位体系、组件和动作名称，并省略完整配置中的部分家庭信息；单实体查询则返回状态对象。原始输出仍可能包含私人属性，应留在本地。

也可以在已加载 Skill、具有同一环境的 Claude Code 会话里这样输入。这是练习提示，不是本站的设备实测记录：

提示词

使用 homeassistant-skill。只读我指定的 sensor.kitchen_temperature。
先检查现有连接和安装版本，再使用只读 REST 助手读取该实体。
报告实体 ID、原始 state、单位以及更新时间；说明哪些字段缺失。
如果状态是 unknown 或 unavailable，请保留原值并解释区别。
不要控制设备、运行自动化、改配置或创建凭据。不要输出令牌。

怎样判断完成了

把报告与 HA 当前实体页面对照：ID 是否相同，单位是否来自属性，更新时间是否合理。状态通常是字符串；只有确实为数字且具有相应单位时，才解释成温度或功率。unknown 表示值未知，unavailable 表示当前不可用，都不能写成 0 或关闭。HTTP 200 证明查询返回，不证明传感器数据一定新鲜。

合格的首次结果是“这个指定实体目前提供什么数据、哪些还不能判断”，无需顺便扫描全屋、运行场景或修复设备。如果想看全站可用性，另行选择 python3 scripts/ha_read.py health；它会读取全部状态并列出 unknown/unavailable 实体，范围大于单传感器练习。

按症状排查

症状	下一步
未设置 HA_URL/HA_TOKEN	在实际运行的进程中补环境；不要把密钥打印出来检查
401	本地核对令牌是否有效、是否完整；浏览器地址栏打开 API 不会自动添加 Bearer 请求头
403	当前账号权限不足；停止，不自动升为管理员
404	核对基础地址和精确实体 ID；不要据此宣布设备坏了
Redirect refused / 返回 HTML	使用已确认的最终基础地址，排查反向代理或登录页；不关闭 TLS 校验
超时或连接失败	从运行 Agent 的机器核对网络、证书和地址；该助手不自动重试
Requested action is not exposed	当前安装未提供该动作；先核对集成与 schema，不能当作空成功

旧社区讨论中已经出现“能登录网页却调用 API 返回 401”的疑问；这是认证方式需要区分，不是这个 Skill 新版本已被证实的缺陷。

从读取到更复杂任务

需要确认灯光动作字段时，可运行 python3 scripts/ha_read.py action-schema light.turn_on。它读取动作定义，不开灯；出现 schema 也不等于获得执行许可。需要设备/区域注册表或自动化定义时，再按仓库 modern-workflows 安装可选 WebSocket 依赖到本地环境；REST 练习不需要这一步。

锁、警报、车库门，以及可能间接控制它们的脚本/场景，需要明确目标和操作授权。不要用 POST /api/states 模拟硬件控制。即使服务调用成功，也应核对真实目标状态，而不是宣称物理动作已完成。

Skill 为 MIT 开源；运行 Agent、模型或远程连接服务可能各自收费。家庭状态进入 Agent 后的处理也受其数据策略影响。本指南依据 2.2.0 原文及助手接口整理，未连接家庭设备，也没有验证一次真实设备控制；首次只读任务用于帮助你在自己的环境中核对结果。