Section: Messaging Platforms · URL: https://hermesbible.com/docs/user-guide/messaging/homeassistant

Home Assistant 整合

Hermes Agent 以兩種方式與 Home Assistant 整合：

Gateway 平台 — 透過 WebSocket 即時訂閱狀態變更並回應事件
智慧家庭工具 — 四個可供 LLM 呼叫的工具，透過 REST API 查詢和控制裝置

設定

1. 建立長期存取權杖（Long-Lived Access Token）

開啟你的 Home Assistant 實例
前往你的個人檔案（點擊側邊欄中的你的名字）
捲動到長期存取權杖
點擊建立權杖，輸入名稱如「Hermes Agent」
複製權杖

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 工具集會自動啟用。Gateway 平台和裝置控制工具都由此單一權杖啟動。

3. 啟動 Gateway

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

範例：

climate 裝置有哪些可用服務？

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

Gateway 平台：即時事件

Home Assistant Gateway 適配器透過 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 用於外送通知（獨立 session 以避免 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，所有鎖已上鎖。」

反應式自動化（透過 Gateway 事件）

連線為 Gateway 平台時，Agent 可以對事件做出反應：

[Home Assistant] 前門：觸發（原為解除）

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. 發送通知：「前門已開啟。走廊燈具已打開。」

疑難排解

環境變數未被讀取。 適配器從 ~/.hermes/.env（啟動時自動合併）或 config.yaml 讀取憑證。請再次確認檔案位於作用中的 Hermes 設定檔主目錄下，且網址/權杖周圍沒有多餘的引號。編輯後請重新啟動 Gateway — 環境變數僅在程式啟動時套用。

conversation entity not found / Agent 從不回應。 Home Assistant 的 conversation API 需要已設定的 Assist conversation agent。在 HA 中，前往 設定 → 語音助理 → 新增助理 並記下產生的實體 ID（類似 conversation.home_assistant 或 conversation.openai_<name>）。在適配器的 conversation_entity 設定中設定該實體 ID；預設值可能不存在於你的實例中。

REST 認證失敗（401 Unauthorized）。 權杖必須是從你的 HA 用戶個人檔案頁面建立的長期存取權杖（個人檔案 → 安全性 → 長期存取權杖）。短期的 UI session 權杖無法使用。另外請驗證基礎網址包含協定和連接埠（例如 http://homeassistant.local:8123），並且從執行 Hermes 的主機可以連線到 — curl -H "Authorization: Bearer <token>" <url>/api/ 應該回傳 {"message": "API running."}。

Home Assistant 整合

設定

1. 建立長期存取權杖（Long-Lived Access Token）

2. 設定環境變數

3. 啟動 Gateway

可用工具

ha_list_entities

ha_get_state

ha_list_services

ha_call_service

Gateway 平台：即時事件

事件篩選

事件格式化

Agent 回應

連線管理

安全性

範例自動化

晨間例行流程

安全檢查

反應式自動化（透過 Gateway 事件）

疑難排解

Webhooks

`ha_list_entities`

`ha_get_state`

`ha_list_services`

`ha_call_service`