介绍
# Home Assistant Assist
通过将自然语言传递给 Home Assistant 的 Assist（对话）API 来控制智能家居设备。**即发即弃**——相信 Assist 能够处理意图解析、实体解析和执行。
## 何时使用此技能
当用户想要**控制或查询任何智能家居设备**时使用此技能。只要它在 Home Assistant 中，Assist 就能处理。
## 工作原理
将用户的请求直接传递给 Assist：
```bash 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"}' ```
**信任 Assist。** 它负责处理： - 意图解析 - 模糊实体名称匹配 - 区域感知命令 - 执行 - 错误响应
## 处理响应
**只需转述 Assist 所说的内容。** `response.speech.plain.speech` 字段包含人类可读的结果。
- `"Turned on the light"` → 成功，告知用户 - `"Sorry, I couldn't understand that"` → Assist 无法解析 - `"Sorry, there are multiple devices called X"` → 名称歧义
**不要过度解读。** 如果 Assist 表示它成功了，那就是成功了。信任响应。
## 当 Assist 返回错误时
只有当 Assist 返回错误（`response_type: "error"`）时，你可以**建议在 HA（Home Assistant）端进行改进**：
| 错误 | 建议 | |-------|------------| | `no_intent_match` | "HA 未识别该命令" | | `no_valid_targets` | "尝试在 HA 中检查实体名称，或添加别名" | | 多个设备 | "可能存在名称重复——建议在 HA 中添加唯一的别名" |
这些是**改进 HA 配置的建议**，而非技能故障。技能已完成其工作——它已将请求传递给 Assist。
## 设置
在 OpenClaw 配置中设置环境变量：
```json { "env": { "HASS_SERVER": "https://your-homeassistant-url", "HASS_TOKEN": "your-long-lived-access-token" } } ```
生成令牌：Home Assistant → Profile → Long-Lived Access Tokens → Create Token
## API 参考
### 端点
``` POST /api/conversation/process ```
**注意：** 使用 `/api/conversation/process`，而**非** `/api/services/conversation/process`。
### 请求
```json { "text": "turn on the kitchen lights", "language": "en" } ```
### 响应
```json { "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 文档](https://developers.home-assistant.io/docs/intent_conversation_api/)