需依次完成五步：一、启用home assistant rest api并生成长期访问令牌；二、配置hermes agent的http网关插件；三、注册设备别名与语义映射规则；四、启用webhook实现反向通知；五、可选mqtt中间件实现异步通信。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您希望将 Hermes Agent 与 Home Assistant 集成，实现通过 Telegram、微信、飞书等消息平台远程控制灯光、空调、窗帘等设备，并触发预设场景（如“回家模式”“睡眠模式”），则需建立双向通信通道并配置设备映射规则。以下是完成该集成的步骤：
一、启用 Home Assistant REST API 并生成长期访问令牌
Home Assistant 必须对外暴露安全的 REST 接口，供 Hermes Agent 发起 HTTP 请求调用设备服务。此步骤为所有后续通信的基础，需确保本地网络可达且认证机制可靠。
1、登录 Home Assistant 前端，进入「设置」→「系统」→「核心」→ 开启「高级模式」。
2、进入「设置」→「用户」→ 点击当前用户 → 滚动到底部点击「创建长期访问令牌」。
3、为 Hermes Agent 单独生成一个令牌，命名如 hermes_gateway_token，勾选「不设过期时间」，点击「提交」并立即复制保存该令牌值。
4、确认 Home Assistant 配置文件 configuration.yaml 中已启用 REST API，且 http: 区块下包含 cors_allowed_origins: ["*"]（仅限可信内网）或明确列出 Hermes 所在服务器 IP。
二、配置 Hermes Agent 的 HTTP 网关插件
Hermes Agent 支持自定义 HTTP 网关，可将自然语言指令解析为对 Home Assistant 的标准 service call 请求。该方式无需额外中间服务，直接复用 Hermes 内置的工具调度能力。
1、编辑 Hermes 配置文件 ~/.hermes/config.yaml，在 tools: 下新增 homeassistant: 模块。
2、填入 Home Assistant 实例地址、端口、访问令牌及基础路径，其中 base_url: 必须与实际部署一致，例如 "http://192.168.1.10:8123"。
3、确保 token: 字段值为第一步中复制的长期访问令牌。
4、保存后执行 hermes restart 使配置生效。
三、注册设备别名与语义映射规则
为支持自然语言理解（如“打开客厅灯”“调低卧室空调温度”），需在 Hermes 中定义设备别名与 Home Assistant 实体 ID 的映射关系，并设定动作模板。该映射存储于 ~/.hermes/skills/homeassistant_mapping.yaml。
1、创建目录：mkdir -p ~/.hermes/skills。
2、新建映射文件：nano ~/.hermes/skills/homeassistant_mapping.yaml。
3、按 YAML 格式编写实体别名映射，例如将 light.living_room_ceiling 映射为 客厅主灯，并将 climate.bedroom_ac 映射为 卧室空调。
4、在映射文件中声明动作模板，如 turn_on 对应 light.turn_on 服务调用，set_temperature 对应 climate.set_temperature 服务调用。
四、启用 Webhook 桥接实现反向通知
Home Assistant 可通过 Webhook 向 Hermes Agent 主动推送设备状态变更或自动化触发事件（如门窗开启告警、离家模式启动），从而实现双向联动。该方式依赖 Hermes Agent 的内置 Webhook 服务端点。
1、在 Hermes 配置中启用 Webhook 插件，确保 webhook: 区块存在且 enabled: true。
2、获取 Hermes Webhook 地址，格式为 http://[hermes-host]:8000/webhook/homeassistant，其中端口与主机需与实际部署匹配。
3、在 Home Assistant 的 configuration.yaml 中添加 webhook 集成，指定 webhook_id: homeassistant 并绑定对应 URL。
4、在 Home Assistant 自动化中添加触发动作：当指定条件满足时，调用 webhook.trigger 服务，传入 webhook_id: homeassistant 及自定义 payload。
五、通过 MQTT 中间件实现轻量级异步通信
若需降低 HTTPS 调用延迟、提升高并发场景下的稳定性，可绕过 REST API，改用 MQTT 协议作为 Hermes Agent 与 Home Assistant 之间的通信桥梁。该方案依赖 Mosquitto 或内置 MQTT Broker。
1、在 Home Assistant 中启用 MQTT 集成，配置 Broker 地址、端口（默认 1883）、用户名与密码。
2、在 Hermes Agent 中安装并启用 MQTT 工具插件，配置相同 Broker 连接参数，并订阅主题如 hermes/ha/control，发布主题如 hermes/ha/status。
3、编写 MQTT 消息解析逻辑：将接收到的 JSON 指令（如 {"entity":"light.living_room","action":"toggle"}）转换为对应服务调用。
4、在 Home Assistant 中配置 MQTT sensor 和 switch，将 Hermes 发布的状态消息映射为实体状态，实现设备状态同步。
