Home Assistant 集成

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

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

设置

1. 创建长期访问令牌 (Long-Lived Access Token)

1. 打开您的 Home Assistant 实例
2. 导航到您的个人资料（点击侧边栏中的姓名）
3. 滚动到长期访问令牌
4. 点击创建令牌，并命名为“Hermes Agent”
5. 复制该令牌

2. 配置环境变量

# 添加到 ~/.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. 启动网关

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 对象的附加参数

示例:

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

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

将客厅灯光设为蓝色，亮度 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 事件。当设备状态发生变化并匹配您的过滤器时，它会作为消息转发给 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 模式从 'off' 更改为 'heat' (当前: 21, 目标: 23)"
sensor	"从 21°C 更改为 22°C"
binary_sensor	"触发" / "清除"
light, switch, fan	"打开" / "关闭"
alarm_control_panel	"警报状态从 'armed_away' 更改为 'triggered'"
(其他)	"从 'old' 更改为 'new'"

Agent 响应

Agent 发出的消息作为Home Assistant 持久通知（通过 persistent_notification.create）交付。这些通知会出现在 HA 通知面板中，标题为“Hermes Agent”。

连接管理

• 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_]+$ 进行验证，以防止注入攻击。

自动化示例

早晨例程

用户: 启动我的早晨例程

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

安全检查

用户: 家里安全吗？

Agent:
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 状态，所有锁已锁定。"

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

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

[Home Assistant] 前门: triggered (之前是 cleared)

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