Home Assistant 集成

Hermes Agent 通过两种方式与 Home Assistant 集成：

1. 网关平台 —— 通过 WebSocket 订阅实时状态变化并响应事件
2. 智能家居工具 —— 四个可被 LLM 调用的工具，通过 REST API 查询和控制设备

配置

1. 创建长期访问令牌

1. 打开您的 Home Assistant 实例
2. 进入个人资料（点击侧边栏中的用户名）
3. 滚动到长期访问令牌
4. 点击创建令牌，命名为"Hermes Agent"
5. 复制令牌

2. 配置环境变量

# 添加到 ~/.hermes/.env

# 必填：您的长期访问令牌
HASS_TOKEN=your-long-lived-access-token

# 可选：HA 地址（默认：http://homeassistant.local:8123）
HASS_URL=http://192.168.1.100:8123

信息

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

3. 启动网关

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 等

示例：

List all lights in the living room

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

ha_get_state

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

参数：

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

示例：

What's the current state of climate.thermostat?

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

ha_list_services

列出可用的服务（操作）供设备控制使用。显示每种设备类型可执行的操作及其接受的参数。

参数：

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

示例：

What services are available for climate devices?

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 对象形式提供的附加参数

示例：

Turn on the living room lights
→ ha_call_service(domain="light", service="turn_on", entity_id="light.living_room")

Set the thermostat to 22 degrees in heat mode
→ ha_call_service(domain="climate", service="set_temperature",
    entity_id="climate.thermostat", data={"temperature": 22, "hvac_mode": "heat"})

Set living room lights to blue at 50% brightness
→ ha_call_service(domain="light", service="turn_on",
    entity_id="light.living_room", data={"brightness": 128, "color_name": "blue"})

网关平台：实时事件

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

事件过滤

必须配置

默认情况下，不转发任何事件。您必须配置 watch_domains、watch_entities 或 watch_all 中的至少一个来接收事件。没有过滤器时，启动时会记录警告并静默丢弃所有状态变化。

在 ~/.hermes/config.yaml 的 Home Assistant 平台 extra 部分配置 Agent 接收的事件：

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 mode changed from 'off' to 'heat' (current: 21, target: 23)"
sensor	"changed from 21°C to 22°C"
binary_sensor	"triggered" / "cleared"
light、switch、fan	"turned on" / "turned off"
alarm_control_panel	"alarm state changed from 'armed_away' to 'triggered'"
（其他）	"changed from 'old' to 'new'"

Agent 响应

来自 Agent 的出站消息以 Home Assistant 持久通知（通过 persistent_notification.create）的形式投递，标题为"Hermes Agent"，显示在 HA 通知面板中。

连接管理

• WebSocket 带 30 秒心跳，用于实时事件
• 自动重连，退避策略：5s → 10s → 30s → 60s
• 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_]+$ 模式进行验证，以防止注入攻击。

自动化示例

早晨例程

User: Start my morning routine

Agent:
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")

安全检查

User: Is the house secure?

Agent:
1. ha_list_entities(domain="binary_sensor")
     → checks door/window sensors
2. ha_get_state(entity_id="alarm_control_panel.home")
     → checks alarm status
3. ha_list_entities(domain="lock")
     → checks lock states
4. Reports: "All doors closed, alarm is armed_away, all locks engaged."

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

连接为网关平台后，Agent 可以对事件做出反应：

[Home Assistant] Front Door: triggered (was cleared)

Agent automatically:
1. ha_get_state(entity_id="binary_sensor.front_door")
2. ha_call_service(domain="light", service="turn_on",
     entity_id="light.hallway")
3. Sends notification: "Front door opened. Hallway lights turned on."