xiaoai-ha-control

通过 Home Assistant + Xiaomi Miot 控制小爱音箱，并可选支持“小爱语音 → OpenClaw”的桥接。适用于两类场景：1) 用户要求“让小爱说一句… / 播报… / 通知…”、“告诉小爱… / 让小爱执行…”、“让小爱播放音频 / mp3 / 链接”时，使用本 skill 进行下行控制；2) 已接入小爱语音桥时，处理带有 `【来自小爱】` / `【来自小爱语音】` 标识的上行消息。只要任务涉及小爱音箱控制、通过小爱执行命令、通过小爱播报结果，或小爱来源消息的桥接与分流，就应使用此 skill。

这个 skill 提供两层能力：

1. OpenClaw → 小爱音箱（核心能力）
   • say：让小爱播报文本
   • exec：让小爱执行文本指令
   • play：让小爱播放 URL 音频
2. 小爱音箱 → OpenClaw（可选桥接能力）
   • 通过 Home Assistant conversation sensor + bridge_server.py 把小爱语音文本转给 OpenClaw

优先把它理解为一个 小爱控制 skill；语音桥接是可选增强，不是所有用户都必须启用。

何时使用

A. 普通聊天中，用户想让 OpenClaw 控制小爱

当消息不带 【来自小爱】 / 【来自小爱语音】 标识，并且文本中出现：

• 小爱
• 小爱同学

优先按 OpenClaw 控制小爱 处理。

推荐映射：

• 明确“说 / 播报 / 通知” → say
• 明确“播放音频 / 链接 / mp3” → play
• 其他默认 → exec

示例：

• 告诉小爱同学，5分钟后该我洗碗 → exec
• 让小爱播报一句：开会啦 → say
• 让小爱播放这个 mp3 → play

B. 消息带有小爱来源标识

当消息中明确带有：

• 【来自小爱】
• 【来自小爱语音】

说明这是 小爱控制 OpenClaw 的上行请求。

此时：

• 不要把它当普通聊天消息理解
• 若环境已接入 bridge，应按桥接规则处理
• 若桥接环境未配置，则只说明当前未接入该能力，不要假装已经收到真实小爱入口事件

前置条件

使用本 skill 前，通常需要：

1. 已安装并启动 Home Assistant
2. 已安装 HACS
3. 已安装 Xiaomi Miot
4. 已将小爱音箱接入 HA
5. 已找到以下实体：
   • play_text
   • execute_text_directive
   • media_player（可选但推荐）
6. 已配置 .env：
   • HA_URL
   • HA_TOKEN
   • XIAOAI_PLAY_TEXT_ENTITY_ID
   • XIAOAI_EXECUTE_TEXT_ENTITY_ID
   • XIAOAI_MEDIA_PLAYER_ENTITY_ID

详细搭建步骤见 README.md。

推荐调用

say

bash scripts/xiaoai.sh say "你好，我是小叮当。"

exec

bash scripts/xiaoai.sh exec "关闭客厅灯"

play

bash scripts/xiaoai.sh play "http://example.com/test.mp3"

语音桥接规则（启用 bridge 时）

如果已启用 bridge_server.py：

• HA 只做入口转发
• bridge_server.py 负责白名单放行
• 命中白名单才继续交给 OpenClaw
• 未命中则终止，让小爱原生处理

若带小爱来源标识的文本中明确点名了某个子 agent（如研究员、邮差、码农、产品、运维、教练、运营等），推荐规则是：

1. main 必须将任务分配给对应子 agent
2. 子 agent 完成后先回 main
3. 再由 main 统一决定聊天回复与小爱口播

不要让 bridge 直接跳过 main 去找子 agent。

重要注意事项

• say 用于播报，不负责设备控制
• exec 用于让小爱理解一条文本命令，能否成功取决于小爱本身是否能理解该命令
• play 用于播放 URL 音频，要求小爱音箱能访问该 URL
• 不同设备型号、不同 Xiaomi Miot 接入方式，暴露的实体可能不同
• 如果要对外分享，请提醒使用者：先跑通 say / exec / play，再考虑语音桥接

文档导航

• README.md：从零搭建、完整架构、桥接说明
• NOTES.md：兼容性边界、分享注意事项
• STATUS.md：当前架构定位与已知限制