🤖HermesBlog
Hermes 消息平台接入 · 第11篇2026/8/9· Easy Understand Hermes Agent

Home Assistant 接入——智能家居中枢

Hermes 消息平台接入第11篇：Home Assistant。让 AI 接管你的智能家居。

这篇教程讲的是如何把 Hermes Agent 接入你的 Home Assistant（简称 HA），让 AI 助手能帮你控制家里的灯、空调、门锁，还能在你出门时帮你“看家”。

小提示：HA 接入是通过官方插件 homeassistant 实现的，它由 Nous Research 维护，不属于 Hermes 核心。所以第一步得先把插件装上。

Home Assistant：四个遥控器

第一步：安装插件

HA 插件是按 profile 安装的，装一次只对当前 profile 生效：

hermes plugins install homeassistant

如果你有多个 profile，想在别的 profile 里也用 HA，得再装一遍：

hermes -p <profile> plugins install homeassistant

插件自带 Python 依赖（aiohttp），不需要再额外 pip install 什么。以前那个 hermes-agent[homeassistant] 的安装方式已经取消了。

配置可以原样沿用：HASS_TOKEN / HASS_URL 变量、homeassistant 平台名和 platforms.homeassistant 配置项、homeassistant 工具集与工具名、cron 的 deliver: homeassistant:<通知目标> 写法都不变。

从旧版本升级上来的用户：什么都不用做。只要你的 profile 之前用过 HA（.env 里有 HASS_TOKEN、config.yaml 里启用了 platforms.homeassistant、或者 platform_toolsets 里列了 homeassistant），hermes update 会自动帮你把插件装上。万一自动安装没跑成（比如离线、插件目录连不上），Hermes 会在 profile 第一次启动时再试一次（受 security.allow_lazy_installs 控制）；失败后最多每小时重试一次，而 hermes update 每次都会重试。安装结果会在终端、桌面应用和聊天里告诉你。装过一次之后就不会重复装了——如果你以后手动 hermes plugins remove homeassistant 卸载了，它也不会自己回来。

准备工作：拿一把“钥匙”

想象一下，Hermes Agent 要进你家门，得先有一把专用的钥匙。这把钥匙在 HA 里叫 Long-Lived Access Token（长期访问令牌）。

第 1 步：创建令牌

  1. 打开你的 Home Assistant 网页界面
  2. 点击左下角你的用户名（进入个人资料页）
  3. 往下滑，找到 长期访问令牌 一栏
  4. 点击 创建令牌，名字随便起，比如 Hermes Agent
  5. 复制生成的那串字符——关掉页面就再也看不到了，先存到记事本里

第 2 步：把钥匙交给 Hermes

打开（或新建）~/.hermes/.env 文件，把刚才的令牌贴进去：

# 必填：你的长期访问令牌
HASS_TOKEN=粘贴你的令牌

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

# 选填：给裸写的 deliver: homeassistant 指定默认通知目标
HASS_HOME_CHANNEL=mobile_app_my_phone

在插件已安装的前提下，只要填了 HASS_TOKEN，Hermes 就会自动开启智能家居控制功能——平台接入和四个控制工具都靠这一个令牌激活，不需要额外配置。

HASS_HOME_CHANNEL 是选填项，用来给裸写的 deliver: homeassistant 指定默认通知目标。

第 3 步：启动网关

hermes gateway

看到 Home Assistant 出现在已连接平台列表里，就说明成功了。

能干什么？四个“遥控器”

插件会在 homeassistant 工具集里注册四个工具，相当于四个遥控器（插件注册的工具，不是 Hermes 核心自带的）：

工具名 作用 举例
ha_list_entities 列出设备 “客厅有哪些灯？”
ha_get_state 查看单个设备详情 “空调现在多少度？”
ha_list_services 查看设备支持的操作 “空调能调什么模式？”
ha_call_service 执行操作 “把客厅灯调成蓝色，亮度 50%”

比如你说：

“把客厅灯打开”

Hermes 内部就会执行：

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

注意：如果你开启了 Tool Search（工具搜索），这四个 ha_* 工具不会直接列在工具清单里，而是要通过 tool_search / tool_call 来调用——这是所有插件工具的通用行为。

进阶：让 Hermes 主动“看家”

默认情况下，HA 发生任何变化（比如门开了、温度变了），Hermes 都不会主动告诉你。你需要告诉它“帮我盯着哪些事”。

编辑 ~/.hermes/config.yaml：

platforms:
  homeassistant:
    enabled: true
    extra:
      watch_domains:
        - climate
        - binary_sensor
        - alarm_control_panel
      watch_entities:
        - sensor.front_door_battery
      ignore_entities:
        - sensor.uptime
      cooldown_seconds: 30
      url: http://192.168.1.100:8123   # 选填；等同于 HASS_URL
  • watch_domains：盯哪些类型的设备（climate=空调、binary_sensor=门窗传感器、alarm_control_panel=报警面板）
  • watch_entities：盯某个具体设备
  • ignore_entities：忽略哪些设备（比如 CPU 温度这种老刷新的传感器）
  • cooldown_seconds：同一个设备 30 秒内最多通知一次，防止刷屏
  • url：HA 的地址，不填就依次用 HASS_URL、http://homeassistant.local:8123

这样当门被打开时，Hermes 就会主动告诉你，甚至自动帮你开灯。

顺带一提：HA 平台默认用 minimal 显示模式，通知里不会有工具进度、流式输出那些啰嗦内容。想要更详细，可以在 config.yaml 的 display.platforms.homeassistant 里改。

定时任务和 Webhook 也能发到 HA

定时任务（cron）和 Webhook 路由可以把消息投递到 HA：

deliver: homeassistant:mobile_app_my_phone   # 指定通知目标
deliver: homeassistant                       # 用 HASS_HOME_CHANNEL 里的默认目标

裸写 homeassistant 这种形式，需要先设好 HASS_HOME_CHANNEL。详见 定时任务 和 Webhook。

安全提醒

Hermes 默认禁止调用 HA 里的危险操作，比如 shell_command（执行系统命令）、python_script（运行脚本）、hassio（控制 HA 主机开关机）。这些是为了防止 AI 被“带偏”后搞破坏，不用动它，保持默认就行。

另外，HA 事件是始终授权的——不需要用户白名单，也不需要配对：HASS_TOKEN 本身就认证了连接，而且 HA 事件没有“人类发送者”这个概念。

出问题了？先查这几点

平台或工具不见了。 先用 hermes plugins list 确认插件在当前 profile 里装了、启用了。如果没装，运行 hermes plugins install homeassistant（或 hermes -p <profile> plugins install homeassistant），然后重启网关。

如果你把 security.allow_lazy_installs 关掉了，那么首次启动时的自动安装会被跳过，得自己手动装。

配置项 url 不生效。 platforms.homeassistant.extra.url 是选填的 HA 地址，不填时依次用 HASS_URL、http://homeassistant.local:8123。

小总结

到这里，你已经能让 Hermes 控制家里的智能设备了。核心就几步：装插件 → 创建令牌 → 填进 .env → 启动网关。然后就能用自然语言指挥它开关灯、调空调、查门锁。

下篇预告：智能家居玩熟了，想不想让 Hermes 主动“找你聊天”？下一篇我们讲讲 Telegram 接入，让你的 AI 助手住进手机里。

📖 官方文档

本文根据 Hermes Agent 官方文档编写，原文见：官方文档 › user-guide/messaging/homeassistant

← 返回全部文章