Home Assistant 集成

Hermes Agent 通過兩種方式與 Home Assistant 集成：

1. 網關平臺 —— 通過 WebSocket 訂閱實時狀態變更，並響應事件
2. 智能家居工具 —— 四個可通過 LLM 調用的工具，通過 REST API 查詢和控制設備

設置

1. 創建長期訪問令牌

1. 打開你的 Home Assistant 實例
2. 進入你的 個人資料（側邊欄點擊你的用戶名）
3. 滾動到 長期訪問令牌
4. 點擊 創建令牌，為其命名，例如 "Hermes Agent"
5. 複製令牌

2. 配置環境變量

# 添加到“0”

# 必需：您的長期訪問權限 Token
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 等

示例：

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 模式從 '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秒心跳，用於實時事件
• 自動重連，指數退避：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."

基於網關事件的響應式自動化

作為網關平臺連接時，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."