2026-05-28 OpenClaw 接入 HomeAssistant MCP 指南
环境
- OpenClaw 运行于 Docker/CasaOS 容器中
- 容器内无 pip，需使用
uvx安装 MCP 包 - 配置文件需持久化到宿主机
步骤一：配置容器启动命令（安装 uv）
在 CasaOS 容器配置中，将启动命令改为：
/bin/bash -c "curl -LsSf https://astral.sh/uv/install.sh | sh && /app/start.sh && node dist/index.js gateway --bind lan --allow-unconfigured --port '18789'"
解释：先用官方安装脚本安装 uv，再用 uvx 运行 ha-mcp
步骤二：持久化配置（挂载目录）
在 CasaOS 挂载路径中添加：
~/.openclaw:/root/.openclaw
这样配置文件不会在容器重建后丢失。
步骤三：配置 openclaw.json
编辑宿主机上的 ~/.openclaw/openclaw.json，在顶层添加或合并以下内容：
{
"mcpServers": {
"homeassistant": {
"command": "uvx",
"args": ["ha-mcp@latest"],
"env": {
"HOMEASSISTANT_URL": "http://192.168.12.110:8123",
"HOMEASSISTANT_TOKEN": "你的令牌"
}
}
}
}
配置说明
| 字段 | 值 | 说明 |
|---|---|---|
command |
uvx |
容器内已安装 uv，用 uvx 运行临时包 |
args |
["ha-mcp@latest"] |
MCP 包名 |
env.HOMEASSISTANT_URL |
http://IP:8123 |
HomeAssistant 地址 |
env.HOMEASSISTANT_TOKEN |
令牌 | 来自 HA 的长期访问令牌 |
HA 令牌获取方式
- 打开 HomeAssistant Web UI
- 用户头像 → 个人资料
- 滚动到底部 长期访问令牌 区
- 点击「创建令牌」，输入名称，复制生成的令牌
步骤四：重启容器
在 CasaOS 中重启 OpenClaw 容器，使配置生效。
验证方法
在 OpenClaw WebUI 中发送消息测试，例如：
查一下我家里有哪些灯光设备是打开的？
如果 AI 能正确调用 HA 设备，说明配置成功。
注意事项
- 环境变量名必须全大写：
HOMEASSISTANT_URL、HOMEASSISTANT_TOKEN - 包名是
ha-mcp@latest，不是homeassistant-mcp - OpenClaw 仅支持 stdio 模式的 MCP，不支持 HTTP transport
- 配置修改后需重启容器生效