Home Assistant 集成

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

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

设置

1. 创建长期访问令牌

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

2. 配置环境变量

# Add to ~/.hermes/.env

# Required: your Long-Lived Access Token
HASS_TOKEN=your-long-lived-access-token

# Optional: HA URL (default: 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 事件。当设备状态发生变化且匹配你的过滤规则时，该事件将作为消息转发给代理。

事件过滤

必需配置

默认情况下，不会转发任何事件。你必须配置至少一个 watch_domains、watch_entities 或 watch_all 才能接收事件。若无过滤规则，启动时将记录警告信息，所有状态变更将被静默丢弃。

在 ~/.hermes/config.yaml 文件中，于 Home Assistant 平台的 extra 部分配置代理可见的事件：

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

示例自动化

早晨例行程序

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

基于网关事件的响应式自动化

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

[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."