OpenClaw 接入 Home Assistant：用聊天控制智能家居

🔧 Step 0：先确认外部工具配置

⚠️ 本案例依赖外部工具（Telegram/Notion/飞书等），先确认已配置 👉 查看常用工具配置指南 →

这个场景解决什么问题

Home Assistant 自带的语音助手功能有限，OpenClaw 接入后可以用强大的 LLM 理解更复杂的指令，比如”把卧室调成睡眠模式”而不是只能说”关卧室灯”。

直接复制这段配置

前提条件

• Home Assistant Core 2025.1.0+
• 已安装并运行 OpenClaw Gateway

第一步：开启 OpenClaw OpenAI 兼容 API

在 ~/.openclaw/openclaw.json 中添加：

{
  "gateway": {
    "auth": {
      "mode": "token",
      "token": "your-gateway-token"
    },
    "http": {
      "endpoints": {
        "chatCompletions": {
          "enabled": true
        }
      }
    }
  }
}

重启 Gateway：

openclaw gateway restart

验证 API 已开启：

curl http://localhost:18789/v1/chat/completions \
  -H "Authorization: Bearer your-gateway-token" \
  -H "Content-Type: application/json" \
  -d '{"model": "openclaw:main", "messages": [{"role": "user", "content": "hi"}]}'

查看当前 token（如果忘了）：

openclaw config get gateway.auth.token

第二步：安装 HA 集成

方法一：HACS 安装（推荐）

1. 打开 HACS → 集成
2. 搜索 “OpenClaw Integration”
3. 安装并重启 HA

方法二：手动安装

# 在 HA 主机上运行
cd /config/custom_components
git clone https://github.com/techartdev/OpenClawHomeAssistantIntegration.git openclaw

然后在 HA 界面重启。

第三步：配置集成

在 HA → 设置 → 集成 → 添加集成 → 搜索 “OpenClaw”

填写：

• OpenClaw URL：http://你的服务器IP:18789
• API Token：第一步里的 your-gateway-token

如果 HA 和 OpenClaw 在同一台机器：

• URL 填 http://localhost:18789

第四步：设为默认语音助手

1. HA 设置 → 语音助手
2. 点击 “添加助手”
3. 对话 Agent 选 “OpenClaw”
4. 在任意 Dashboard 点麦克风图标测试

第五步：测试控制

在 Assist 界面输入：

把客厅的灯调暗一点，营造看电影的氛围

关掉所有卧室的设备，准备睡觉

明天早上 7 点把卧室温度调到 22 度

可选：Lovelace 聊天卡片

安装集成后，在 Dashboard 添加卡片：

type: custom:openclaw-chat-card
title: AI 助手
show_history: true
voice_input: true

集成提供的功能

功能	描述
对话 Agent	替换 HA 默认 NLU
Lovelace 卡片	带历史记录的聊天界面
openclaw.send_message 服务	从自动化中触发 OpenClaw
状态传感器	监控 OpenClaw 连接状态

让 OpenClaw 主动通知 HA

OpenClaw 也可以反向推送消息到 Home Assistant。在 AGENTS.md 里加：

## 通知规则
以下情况通过 HA webhook 发送通知：
- 定时任务完成
- 系统告警

调用方式：
POST http://homeassistant.local:8123/api/services/notify/mobile_app_你的手机
Header: Authorization: Bearer <HA长期令牌>
Body: {"title": "OpenClaw", "message": "任务完成"}

注意事项

• OpenClaw 的 OpenAI API 必须网络可达（不能只绑 127.0.0.1）
• 如使用 HA Addon 版 OpenClaw，支持自动发现
• 首次配置建议先测试简单指令，再尝试复杂场景
• 语音识别仍使用 HA 自带引擎，OpenClaw 只处理理解和执行部分