Home Assistant 集成
KOPI AI AGENT 通过两种方式与 Home Assistant 集成:
- Gateway platform(网关平台) — 通过 WebSocket 订阅实时状态变更并响应事件
- Smart home tools(智能家居工具) — 四个可供 LLM 调用的工具,用于通过 REST API 查询和控制设备
设置
1. 创建长期访问令牌
- 打开你的 Home Assistant 实例
- 进入你的 Profile(个人资料)(点击侧边栏中的你的名字)
- 滚动到 Long-Lived Access Tokens(长期访问令牌)
- 点击 Create Token(创建令牌),为其命名,例如 "KOPI AI AGENT"
- 复制该令牌
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、scriptservice(必填) — 服务名称:turn_on、turn_off、toggle、set_temperature、set_hvac_mode、open_cover、close_cover、set_volume_levelentity_id(可选) — 目标实体,例如light.living_roomdata(可选) — 以 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_all | false | 设置为 true 以接收所有状态变更(对于大多数部署不推荐) |
ignore_entities | (无) | 始终忽略这些实体(在 domain(域)/实体过滤器之前应用) |
cooldown_seconds | 30 | 同一实体事件之间的最小间隔秒数 |
从一组聚焦的 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(域)被阻止,以防止在 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."}。