hermes教程-Home Assistant 集成

设置

1. 创建长期访问令牌

打开你的 Home Assistant 实例
进入你的个人资料（点击侧边栏中的你的名字）
滚动到长期访问令牌
点击创建令牌，为其命名，例如 "Hermes Agent"
复制令牌

2. 配置环境变量

bash

## 添加到 ~/.hermes/.env
## 必需：你的长期访问令牌
HASS_TOKEN=your-long-lived-access-token
## 可选：HA URL（默认：http://homeassistant.local:8123）
HASS_URL=http://192.168.1.100:8123

信息

当设置了 HASS_TOKEN 时，homeassistant 工具集会自动启用。网关平台和设备控制工具都通过这一个令牌激活。

3. 启动网关

bash

hermes gateway

Home Assistant 将作为一个已连接平台出现，与其他消息平台（Telegram、Discord 等）并列。

可用工具

Hermes Agent 注册了四个用于智能家居控制的工具：

`ha_list_entities`

列出 Home Assistant 实体，可按域或区域进行过滤。

参数：

domain （可选） — 按实体域过滤：light、switch、climate、sensor、binary_sensor、cover、fan、media_player 等。
area （可选） — 按区域/房间名称过滤（与友好名称匹配）：living room、kitchen、bedroom 等。

示例：

列出客厅中的所有灯

返回实体 ID、状态和友好名称。

`ha_get_state`

获取单个实体的详细状态，包括所有属性（亮度、颜色、温度设定值、传感器读数等）。

参数：

entity_id （必需） — 要查询的实体，例如 light.living_room、climate.thermostat、sensor.temperature

示例：

climate.thermostat 的当前状态是什么？

返回：状态、所有属性、最后更改/更新时间戳。

`ha_list_services`

列出可用于设备控制的服务（操作）。显示每种设备类型可以执行哪些操作以及它们接受哪些参数。

参数：

domain （可选） — 按域过滤，例如 light、climate、switch

示例：

气候设备有哪些可用服务？

`ha_call_service`

调用 Home Assistant 服务以控制设备。

参数：

domain （必需） — 服务域：light、switch、climate、cover、media_player、fan、scene、script
service （必需） — 服务名称：turn_on、turn_off、toggle、set_temperature、set_hvac_mode、open_cover、close_cover、set_volume_level
entity_id （可选） — 目标实体，例如 light.living_room
data （可选） — 作为 JSON 对象的附加参数

示例：

text

打开客厅灯
→ ha_call_service(domain="light", service="turn_on", entity_id="light.living_room")

text

将恒温器设置为 22 度，制热模式
→ ha_call_service(domain="climate", service="set_temperature",
    entity_id="climate.thermostat", data={"temperature": 22, "hvac_mode": "heat"})

text

将客厅灯设置为蓝色，亮度 50%
→ ha_call_service(domain="light", service="turn_on",
    entity_id="light.living_room", data={"brightness": 128, "color_name": "blue"})

网关平台：实时事件

Home Assistant 网关适配器通过 WebSocket 连接，并订阅 state_changed 事件。当设备状态发生变化且与你的过滤器匹配时，它会作为消息转发给代理。

事件过滤

警告 — 必需配置

默认情况下，不会转发任何事件。你必须至少配置 watch_domains、watch_entities 或 watch_all 中的一个才能接收事件。如果没有过滤器，启动时会记录一条警告，并且所有状态更改都会被静默丢弃。

在 ~/.hermes/config.yaml 中 Home Assistant 平台的 extra 部分下配置代理可以看到哪些事件：

yaml

platforms:
  homeassistant:
    enabled: true
    extra:
      watch_domains:
        - climate
        - binary_sensor
        - alarm_control_panel
        - light
      watch_entities:
        - sensor.front_door_battery
      ignore_entities:
        - sensor.uptime
        - sensor.cpu_usage
        - sensor.memory_usage
      cooldown_seconds: 30

设置	默认值	描述
`watch_domains`	（无）	仅监视这些实体域（例如 `climate`、`light`、`binary_sensor`）
`watch_entities`	（无）	仅监视这些特定的实体 ID
`watch_all`	`false`	设置为 `true` 以接收所有状态更改（不推荐用于大多数设置）
`ignore_entities`	（无）	始终忽略这些实体（在域/实体过滤器之前应用）
`cooldown_seconds`	`30`	同一实体的两个事件之间的最小秒数

提示

从一组集中的域开始——climate、binary_sensor 和 alarm_control_panel 涵盖了最有用的自动化。根据需要添加更多。使用 ignore_entities 来抑制嘈杂的传感器，如 CPU 温度或运行时间计数器。

事件格式化

状态更改根据域格式化为人类可读的消息：

域	格式
`climate`	"HVAC 模式从 'off' 更改为 'heat'（当前：21，目标：23）"
`sensor`	"从 21°C 更改为 22°C"
`binary_sensor`	"触发" / "清除"
`light`、`switch`、`fan`	"打开" / "关闭"
`alarm_control_panel`	"警报状态从 'armed_away' 更改为 'triggered'"
（其他）	"从 'old' 更改为 'new'"

代理响应

来自代理的出站消息作为 Home Assistant 持久通知（通过 persistent_notification.create）传递。这些通知会出现在 HA 通知面板中，标题为 "Hermes Agent"。

连接管理

WebSocket，30 秒心跳，用于实时事件
自动重连，带退避：5 秒 → 10 秒 → 30 秒 → 60 秒
REST API，用于出站通知（单独的会话以避免 WebSocket 冲突）
授权 — HA 事件始终被授权（无需用户允许列表，因为 HASS_TOKEN 对连接进行身份验证）

安全性

Home Assistant 工具强制执行安全限制：

警告 — 被阻止的域

以下服务域被阻止，以防止在 HA 主机上执行任意代码：

shell_command — 任意 shell 命令

command_line — 执行命令的传感器/开关

python_script — 脚本化 Python 执行

pyscript — 更广泛的脚本集成

hassio — 插件控制、主机关机/重启

rest_command — 来自 HA 服务器的 HTTP 请求（SSRF 向量）

尝试调用这些域中的服务会返回错误。

实体 ID 根据模式 ^[a-z_][a-z0-9_]*\.[a-z0-9_]+$ 进行验证，以防止注入攻击。

示例自动化

早晨例行程序

text

用户：开始我的早晨例行程序

代理：
1. ha_call_service(domain="light", service="turn_on",
     entity_id="light.bedroom", data={"brightness": 128})
2. ha_call_service(domain="climate", service="set_temperature",
     entity_id="climate.thermostat", data={"temperature": 22})
3. ha_call_service(domain="media_player", service="turn_on",
     entity_id="media_player.kitchen_speaker")

安全检查

text

用户：房子安全吗？

代理：
1. ha_list_entities(domain="binary_sensor")
     → 检查门/窗传感器
2. ha_get_state(entity_id="alarm_control_panel.home")
     → 检查警报状态
3. ha_list_entities(domain="lock")
     → 检查锁状态
4. 报告："所有门已关闭，警报处于 armed_away 状态，所有锁已锁上。"

响应式自动化（通过网关事件）

当作为网关平台连接时，代理可以响应事件：

text

[Home Assistant] 前门：触发（之前是清除状态）

代理自动：
1. ha_get_state(entity_id="binary_sensor.front_door")
2. ha_call_service(domain="light", service="turn_on",
     entity_id="light.hallway")
3. 发送通知："前门已打开。走廊灯已打开。"

故障排除

环境变量未被识别。 适配器从 ~/.hermes/.env（启动时自动合并）或 config.yaml 读取凭据。请仔细检查文件是否位于活动的 Hermes 配置文件主目录下，并且 URL/令牌周围没有多余的引号。编辑后重新启动网关——环境变量更改仅在进程启动时应用。

conversation entity not found / 代理从不回复。 Home Assistant 的对话 API 需要配置一个 Assist 对话代理。在 HA 中，打开 设置 → 语音助手 → 添加助手，并记下生成的实体 ID（看起来像 conversation.home_assistant 或 conversation.openai_<name>）。在适配器的 conversation_entity 设置中设置该实体 ID；默认值可能在你的实例上不存在。

REST 认证失败（401 Unauthorized）。 令牌必须是来自你的 HA 用户个人资料页面（个人资料 → 安全 → 长期访问令牌）创建的长期访问令牌。短期的 UI 会话令牌不起作用。还要验证基础 URL 包含方案和端口（例如 http://homeassistant.local:8123），并且可以从运行 Hermes 的主机访问——curl -H "Authorization: Bearer <token>" <url>/api/ 应返回 {"message": "API running."}。

字节笔记本

hermes教程-Home Assistant 集成

设置

1. 创建长期访问令牌

2. 配置环境变量

3. 启动网关

可用工具

ha_list_entities

ha_get_state

ha_list_services

ha_call_service

网关平台：实时事件

事件过滤

事件格式化

代理响应

连接管理

安全性

示例自动化

早晨例行程序

安全检查

响应式自动化（通过网关事件）

故障排除

`ha_list_entities`

`ha_get_state`

`ha_list_services`

`ha_call_service`