Home Assistant 智能助手

通过将自然语言传递给 Home Assistant 的智能助手（对话）API 来控制智能家居设备。一键操控，无需跟进——相信智能助手能处理意图解析、实体识别和执行操作。

何时使用此技能

当用户想要控制或查询任何智能家居设备时可使用此技能。只要设备接入 Home Assistant，智能助手就能处理。

工作原理

将用户的请求直接传递给智能助手：

curl -s -X POST "$HASS_SERVER/api/conversation/process" \
  -H "Authorization: Bearer $HASS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text": "USER REQUEST HERE", "language": "en"}'

信任智能助手。它能处理：

• 意图解析
• 模糊实体名称匹配
• 区域感知命令
• 执行操作
• 错误响应

处理响应

只需转述智能助手的回应。使用response.speech.plain.speech该字段包含人类可读的结果。

• "打开了灯"→ 成功，告知用户
• "抱歉，我没能理解"→ 助手无法解析
• "抱歉，有多个名为 X 的设备"→ 名称不明确

不要过度解读。如果助手说它成功了，那就是成功了。请相信这个响应。

当助手返回错误时

仅当助手返回错误时（response_type: "error"），您可以建议 Home Assistant 端的改进：

这些是用于改进HA配置的建议，而非技能故障。该技能已完成其工作——它将请求传递给了Assist。

设置

在OpenClaw配置中设置环境变量：

{
  "env": {
    "HASS_SERVER": "https://your-homeassistant-url",
    "HASS_TOKEN": "your-long-lived-access-token"
  }
}

生成令牌：Home Assistant → 个人资料 → 长期访问令牌 → 创建令牌

API参考

端点

POST /api/conversation/process

注意：使用/api/conversation/process，而非/api/services/conversation/process。

请求

{
  "text": "turn on the kitchen lights",
  "language": "en"
}

响应

{
  "response": {
    "speech": {
      "plain": {"speech": "Turned on the light"}
    },
    "response_type": "action_done",
    "data": {
      "success": [{"name": "Kitchen Light", "id": "light.kitchen"}],
      "failed": []
    }
  }
}

理念

• 信任Assist——它比我们更了解用户的HA设置
• 发射后不管——传递请求，转达响应
• 不要进行故障排除— 如果某项功能无法正常工作，建议改进HA配置
• 保持简洁— 一次API调用，自然语言输入，自然语言输出

链接

• Home Assistant对话API文档