跳到主要内容

Home Assistant 集成

KOPI AI AGENT 通过两种方式与 Home Assistant 集成:

  1. Gateway platform(网关平台) — 通过 WebSocket 订阅实时状态变更并响应事件
  2. Smart home tools(智能家居工具) — 四个可供 LLM 调用的工具,用于通过 REST API 查询和控制设备

设置​

1. 创建长期访问令牌​

  1. 打开你的 Home Assistant 实例
  2. 进入你的 Profile(个人资料)(点击侧边栏中的你的名字)
  3. 滚动到 Long-Lived Access Tokens(长期访问令牌)
  4. 点击 Create Token(创建令牌),为其命名,例如 "KOPI AI AGENT"
  5. 复制该令牌

2. 配置环境变量​

# Add to ~/.kopi/.env

# Required: your Long-Lived Access Token
HASS_TOKEN=your-long-lived-access-token

# Optional: HA URL (default: http://homeassistant.local:8123)
HASS_URL=http://192.168.1.100:8123
信息

设置 HASS_TOKEN 后,homeassistant 工具集会自动启用。Gateway platform(网关平台)和设备控制工具都会通过这一个令牌激活。

3. 启动网关​

kopi gateway

Home Assistant 将与其他消息平台(Telegram、Discord 等)一起显示为已连接的平台。

可用工具​

KOPI AI AGENT 注册了四个用于智能家居控制的工具:

ha_list_entities​

列出 Home Assistant 实体,可按 domain(域)或 area(区域)进行过滤。

参数:

  • domain (可选) — 按实体 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​

列出可用于设备控制的 service(服务)(操作)。显示每种设备类型可以执行哪些操作以及它们接受哪些参数。

参数:

  • domain (可选) — 按 domain(域)过滤,例如 light、climate、switch

示例:

What services are available for climate devices?

ha_call_service​

调用 Home Assistant service(服务)以控制设备。

参数:

  • domain (必填) — 服务 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 中的至少一个才能接收事件。如果没有过滤器,启动时会记录一条警告,且所有状态变更都会被静默丢弃。

在 ~/.kopi/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(无)仅监视这些实体 domain(域)(例如 climate、light、binary_sensor)
watch_entities(无)仅监视这些特定的实体 ID
watch_allfalse设置为 true 以接收所有状态变更(对于大多数部署不推荐)
ignore_entities(无)始终忽略这些实体(在 domain(域)/实体过滤器之前应用)
cooldown_seconds30同一实体事件之间的最小间隔秒数
提示

从一组聚焦的 domain(域)开始 —— climate、binary_sensor 和 alarm_control_panel 覆盖了最有用的自动化场景。根据需要添加更多。使用 ignore_entities 来抑制 CPU 温度或运行时间计数器这类嘈杂的传感器。

事件格式化​

状态变更会根据 domain(域)格式化为人类可读的消息:

Domain(域)格式
climate"HVAC mode changed from 'off' to 'heat' (current: 21, target: 23)"(HVAC 模式从 'off' 变更为 'heat'(当前:21,目标:23))
sensor"changed from 21°C to 22°C"(从 21°C 变更为 22°C)
binary_sensor"triggered"(已触发)/ "cleared"(已清除)
light、switch、fan"turned on"(已打开)/ "turned off"(已关闭)
alarm_control_panel"alarm state changed from 'armed_away' to 'triggered'"(报警状态从 'armed_away' 变更为 'triggered')
(其他)"changed from 'old' to 'new'"(从 'old' 变更为 'new')

Agent 响应​

来自 agent 的出站消息会作为 Home Assistant 持久通知(通过 persistent_notification.create)送达。这些通知会显示在 HA 通知面板中,标题为 "KOPI AI AGENT"。

连接管理​

  • WebSocket,带有 30 秒心跳,用于实时事件
  • 自动重连,带退避机制:5s → 10s → 30s → 60s
  • REST API 用于出站通知(使用独立会话以避免 WebSocket 冲突)
  • 授权 — HA 事件始终被授权(无需用户允许列表,因为 HASS_TOKEN 会对连接进行身份验证)

安全性​

Home Assistant 工具会强制执行安全限制:

被阻止的 domain(域)

以下服务 domain(域)被阻止,以防止在 HA 主机上执行任意代码:

  • shell_command — 任意 shell 命令
  • command_line — 执行命令的传感器/开关
  • python_script — 脚本化 Python 执行
  • pyscript — 更广泛的脚本集成
  • hassio — 加载项控制、主机关机/重启
  • rest_command — 来自 HA 服务器的 HTTP 请求(SSRF 攻击向量)

尝试调用这些 domain(域)中的服务会返回错误。

实体 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."

响应式自动化(通过 Gateway 事件)​

当作为 gateway(网关)平台连接时,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."

故障排查​

环境变量未被读取。 适配器从 ~/.kopi/.env(启动时自动合并)或 config.yaml 读取凭据。请仔细检查该文件是否位于当前 Kopi Agent profile 主目录下,并确认 URL/token 周围没有多余的引号。编辑后请重启 gateway —— 环境变量的更改仅在进程启动时生效。

REST 认证失败(401 Unauthorized)。 该 token 必须是从你的 HA 用户配置文件页面(Profile → Security → Long-lived access tokens)创建的长期访问令牌(Long-Lived Access Token)。短期的 UI 会话令牌无法使用。另外请验证 base URL 是否包含协议和端口(例如 http://homeassistant.local:8123),并且可以从运行 Kopi Agent 的主机访问 —— curl -H "Authorization: Bearer <token>" <url>/api/ 应该返回 {"message": "API running."}。