HomeAssistant 与 Hermes Agent 可通过四种方式集成：一、直连 REST API，配置长期令牌与工具参数；二、安装 HACS 的 hermes-integration 插件实现事件双向同步；三、基于 MQTT 协议桥接，通过主题收发结构化指令；四、用 cpolar 内网穿透实现跨网段安全访问。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您已部署 HomeAssistant 并希望将其与 Hermes Agent 集成以实现自然语言驱动的智能家居控制，则需建立双向通信通道，使 Hermes Agent 能识别用户指令、调用 HomeAssistant REST API 或 WebSocket 接口执行设备操作，并将执行结果反馈至记忆系统。以下是实现该集成的多种可行路径：
一、通过 HomeAssistant REST API 直接调用
此方法无需额外中间件，Hermes Agent 利用内置 HTTP 工具模块直接向 HomeAssistant 的 REST API 发起认证请求，适用于已启用 API 密钥且开放本地网络访问的 HomeAssistant 实例。所有设备状态查询与开关控制均可通过标准 HTTP 方法完成。
1、在 HomeAssistant 中进入“设置 > 用户 > 您的用户 > 创建长期访问令牌”，复制生成的 token 值。
2、编辑 Hermes Agent 的工具配置文件 ~/.hermes/tools.yaml，在 tools 下新增 homeassistant 条目，填入 base_url（如 http://192.168.1.10:8123/api）、token 与 timeout 参数。
3、重启 Hermes Agent 后，向其发送指令如 “把客厅灯调到50%亮度”，Agent 将自动解析设备实体 ID、构建 PUT 请求体并提交至 /api/services/light/turn_on 接口。
二、通过 HACS 插件 hermes-integration 接入
该方式由社区维护的 HACS 插件提供专用网关服务，将 HomeAssistant 的事件流与 Hermes Agent 的消息循环桥接，支持双向事件订阅——既可响应语音/文本指令触发设备动作，也可将设备状态变更（如门窗开启、温度突变）实时推送至 Hermes Agent 记忆层，触发自动化反思与技能沉淀。
1、在 HomeAssistant 的前端界面中打开 HACS，搜索并安装 “Hermes Integration” 插件。
2、安装完成后重启 HomeAssistant，进入“设置 > 系统 > 集成”，点击右下角“+ 添加集成”，选择 Hermes Agent 并填写 Hermes 实例的公网或局域网地址及端口（默认 8000）。
3、确认配对成功后，插件将在 ~/.homeassistant/hermes/ 目录下生成 device_map.json，自动映射全部可控实体为自然语言可识别名称，例如将 light.living_room_ceiling 映射为 “客厅主灯”。
三、使用 MQTT 协议桥接双系统
MQTT 作为轻量级发布/订阅消息协议，天然适配边缘设备与 AI Agent 的松耦合通信需求。此方案将 HomeAssistant 配置为 MQTT 客户端，Hermes Agent 作为独立 MQTT 客户端订阅主题，双方通过预定义主题层级（如 hermes/homeassistant/command）交换结构化指令与响应，避免直接暴露 API 端点，提升安全性。
1、在 HomeAssistant 中启用 MQTT 集成，配置 Broker 地址（如 mosquitto 容器 IP）与认证凭据。
2、在 Hermes Agent 的 ~/.hermes/config.yaml 中启用 mqtt 模块，指定 broker_host、port、username、password 及 subscribe_topic（如 hermes/homeassistant/response）与 publish_topic（如 hermes/homeassistant/command）。
3、编写自定义技能文件 ~/.hermes/skills/light_control.md，定义当检测到“开灯”“关窗帘”等意图时，向 publish_topic 推送 JSON 格式 payload，包含 entity_id、service、data 字段。
四、借助 cpolar 内网穿透实现跨网段控制
当 Hermes Agent 运行于云服务器或远程开发机，而 HomeAssistant 部署在家庭内网时，需打通网络边界。cpolar 提供安全隧道，将 HomeAssistant 的本地 API 端口（8123）映射为 HTTPS 公网地址，Hermes Agent 通过该地址发起请求，所有流量经加密隧道传输，无需修改路由器端口转发规则。
1、在运行 HomeAssistant 的主机上安装 cpolar 客户端，执行 cpolar http 8123 启动临时隧道，获取 https://xxxx.cpolar.io 地址。
2、登录 cpolar Web 控制台，将该隧道设为“保留域名”，并绑定自定义子域名（如 ha.yourname.cpolar.io）。
3、将该域名填入 Hermes Agent 的 tools.yaml 中 homeassistant.base_url 字段，确保 token 权限已授予远程访问能力。
