← 返回首页

Home Assistant 设备集成：ha_list/ha_call 实战指南

2026-06-04

背景

大多数人控制智能家居的方式是打开 HA 的 Web UI 或者手机 App——点一下开关，调一下亮度，看一眼温度。这没什么不对，但有一个问题：你没法把它编进自动化流程里。

比如你有这样一个需求：”每天晚上 10 点，检查客厅的温湿度，如果湿度低于 40%，开加湿器到中档。”

在 HA 里写自动化规则能做到，但每次改逻辑都要去编辑器里改 YAML。而 AI Agent 可以理解自然语言指令，直接调用 HA 的 API 执行操作。你只需要配置一次，之后说”客厅太干了”它就能自动判断并执行。

Hermes Agent 内置了 Home Assistant 工具集，不需要装 MCP 插件或者第三方 Skill，配好 token 就能用。

四个内置工具

工具代码在 homeassistant_tool.py 里，注册在 homeassistant toolset 下，一共 4 个：

工具 功能 关键参数
ha_list_entities 列出所有 HA 实体，按 domain 或 area 过滤 domain, area
ha_get_state 查看单个设备的详细状态 entity_id
ha_list_services 查看某个设备类型支持哪些操作 domain
ha_call_service 执行控制指令——开灯、调温、开关窗帘 domain, service, entity_id, data

这 4 个工具覆盖了”查状态→查指令→执行控制”的完整闭环。不需要额外安装任何东西。

配置方法

第一步：获取 Token

进 HA 网页 → 点右上角用户头像 → 安全 → Long-Lived Access Tokens → 创建一个

第二步：写入环境变量

在 ~/.hermes/.env 里加两行：

HASS_URL=http://your-ha-ip:8123
HASS_TOKEN=你的令牌

内置工具从环境变量读取配置，不是从 config.yaml。

第三步：重启 gateway

hermes gateway restart

然后就可以在对话里直接控制智能家居了。

实战案例

查设备状态

列出客厅所有灯

Agent 内部会调用 ha_list_entities(domain="light", area="living room")，返回类似：

{
  "count": 4,
  "entities": [
    {"entity_id": "light.living_room_1", "state": "off", "friendly_name": "客厅筒灯1"},
    {"entity_id": "light.living_room_2", "state": "on", "friendly_name": "客厅筒灯2"}
  ]
}

看单个设备的详细信息

如果想知道某个灯的具体属性——亮度、色温、颜色：

查看客厅筒灯1的详细状态

对应 ha_get_state(entity_id="light.living_room_1")，返回除了 state 之外还有 attributes 对象，包含 brightness、color_temp、friendly_name、last_changed 等。

执行控制

把客厅筒灯1亮度调到最高，颜色改成蓝色

Agent 会先查到 light 支持的服务，然后调用：

ha_call_service(
    domain="light",
    service="turn_on",
    entity_id="light.living_room_1",
    data='{"brightness": 255, "color_name": "blue"}'
)

temperature、hvac_mode、volume_level 等参数同理。

查某个类型支持哪些操作

灯具有哪些操作？

调用 ha_list_services(domain="light")，返回 turn_on、turn_off、toggle 等。climate 域会多出 set_temperature、set_hvac_mode。

安全模型

HA 的 REST API 有一个特点：它没有服务级别的访问控制。拿到 token 之后可以调用任何服务，包括 shell_command、python_script 这些可以执行任意代码的接口。

所以安全措施必须在 Agent 层做。内置工具实现了三层防护：

  1. entity_id 格式校验：必须匹配 ^[a-z_][a-z0-9_]*\.[a-z0-9_]+$，防止注入
  2. domain/service 格式校验：同样限制在字母数字下划线范围内
  3. 封禁高危服务域：shell_command、command_line、python_script、pyscript、hassio、rest_command 这 6 个域被硬编码在封禁列表里

这些被封禁的服务各有风险：shell_command 在 HA 容器内以 root 执行任意命令，rest_command 可以从 HA 服务器发起 HTTP 请求（SSRF 向量），hassio 包含主机开关机和插件管理功能。

另外，如果 HASS_TOKEN 没有配置，工具会自动隐藏，不会报错也不会暴露任何信息。

踩坑记录

不重启 gateway → 401

配置完 HASS_TOKEN 之后，gateway 进程读到的还是旧的环境变量。必须 hermes gateway restart 才能生效。只改 .env 不重启，调用工具就会返回 401 Unauthorized。

Token 被 AI 写错

这是一个比较隐蔽的问题：让 AI 帮你把 token 写入 .env 文件时，它可能写出自己编造的内容而不是你实际复制进去的 token。排查了很久才发现是写入内容不对。涉及敏感信息的操作，建议写完之后自己确认一下文件内容。

设备 unavailable

遇到过 47 个米家灯同时变成 unavailable 的情况。一开始以为是 token 问题或者网络问题，后来用 hass-cli 的 integration list 命令发现是 xiaomi_miot 集成在服务器端的状态是 not_loaded——这是 HA 服务端的问题，不是客户端配置的问题。

替代方案

除了 Hermes 内置工具，还有几种方式可以操作 HA：

hass-cli（官方命令行工具）：

pip install homeassistant-cli
export HASS_SERVER="http://your-ha:8123"
export HASS_TOKEN="你的令牌"

hass-cli state list                          # 列出所有设备状态
hass-cli state get light.living_room         # 查看单个设备
hass-cli service call homeassistant.turn_on  # 执行操作
hass-cli event watch state_changed           # 监听状态变更
hass-cli history list --entity sensor.xxx    # 查询历史数据

hass-cli 适合调试和批量操作，比如集成排查、历史数据查询。注意 homeassistant-cli v1.0.0 需要 Python 3.13+。

直接调 REST API：

curl -H "Authorization: Bearer $HASS_TOKEN" \
     -H "Content-Type: application/json" \
     $HASS_URL/api/states

零依赖，适合写脚本做快速测试。

三种方式用同一个 token，可以共存。内置工具适合 Agent 日常自动化，hass-cli 适合排查问题，curl 适合一次性测试。

总结

Hermes Agent 的 Home Assistant 内置工具是我用得最频繁的自动化能力之一。配好 token，说一句话就能控制设备——不管是批量查传感器、调空调温度，还是定时检查环境状态，都比在 Web UI 里翻菜单快得多。

配置只有三步（生成 token → 写 .env → 重启 gateway），配好之后就不用再管了。

© 2026 Ruite的AI实践分享