xiaoai-ha-control

通过 Home Assistant + Xiaomi Miot 控制小爱音箱，并可选支持“小爱语音 → OpenClaw”的桥接。适用于两类场景：1) 用户要求“让小爱说一句… / 播报… / 通知…”、“告诉小爱… / 让小爱执行…”、“让小爱播放音频 / mp3 / 链接”时，使用本 skill 进行下行控制...

Security Scan

Skill appears to do what it claims (control Xiaoai via Home Assistant and optionally bridge Xiaoai → OpenClaw) but there are configuration and exposure inconsistencies you should review before installing (missing declared env vars, an HTTP bridge that listens on 0.0.0.0 by default, and references to configuration files that may be missing).

Purpose & Capability

The skill's name/description align with the code and scripts: the shell scripts and bridge_server.py legitimately need a Home Assistant URL/token and entity IDs to control Xiaoai and to forward Xiaoai conversation text to OpenClaw. However the registry metadata lists no required environment variables while the SKILL.md and scripts clearly expect HA_URL, HA_TOKEN, XIAOAI_*_ENTITY_ID and optionally OPENCLAW_BIN — this mismatch is an inconsistency that should be fixed/verified before use.

Instruction Scope

SKILL.md and the scripts stay within the stated domain (calling Home Assistant APIs, invoking local OpenClaw, and optionally running a local bridge). The bridge_server.py runs subprocesses (calls the openclaw binary and the included xiaoai.sh), writes status/log files in the skill directory, and accepts POSTs to forward text to OpenClaw. These behaviors are expected for a bridge but grant the service permission to run local commands and produce network I/O — review and control where the bridge is reachable and which prompts it sends to OpenClaw.

Install Mechanism

This is an instruction-only skill with bundled scripts and Python code; there is no remote download/install step. No external installers or arbitrary archive downloads are used, so installation risk is limited to running the included code locally.

Credentials

The runtime needs sensitive credentials (Home Assistant long-lived access token) and entity IDs as documented in SKILL.md and the scripts, but the registry metadata did not declare these required env variables. Storing HA_TOKEN in a local .env file is necessary for operation; protect it. The bridge also requires an OPENCLAW_BIN (or will call 'openclaw' from PATH), which may cause the bridge to invoke the main agent and therefore generate outbound model activity — this is expected but sensitive.

Persistence & Privilege

bridge_server.py listens by default on 0.0.0.0:8765 and start_bridge.sh instructs running it as a daemon / via systemd/launchd. That makes the bridge a persistent network service; if started on a machine with public network exposure it could accept unsolicited requests unless firewalling/restricting is applied. The skill does not request unusual system privileges, but its default network binding and suggested persistent setup are notable security considerations.

What to consider before installing

Key things to check before installing: - Expect to provide sensitive env vars even though the registry shows none: HA_URL, HA_TOKEN, XIAOAI_PLAY_TEXT_ENTITY_ID, XIAOAI_EXECUTE_TEXT_ENTITY_ID, XIAOAI_MEDIA_PLAYER_ENTITY_ID (and optionally OPENCLAW_BIN). Do not commit or share your .env containing HA_TOKEN. - The bridge (bridge_server.py) binds to 0.0.0.0:8765 by default. If you run it, restrict access with a firewall, bind it to localhost, or configure a reverse proxy that requires authentication so it isn't reachable from untrusted networks. - The bridge executes local subprocesses (openclaw and the xiaoai scripts) and writes logs/status files in the skill directory. Review the code to ensure prompts and outputs meet your privacy needs; consider running it in a confined account or container. - The README references whitelist.json.example and copying a whitelist; verify that whitelist.json exists before enabling forwarding. Use the whitelist to avoid forwarding device-control commands you want Xiaoai to handle natively. - If you plan to enable autostart (systemd/launchd), follow the README's launchd notes: do not double-daemonize, and ensure PATH/OPENCLAW_BIN are explicitly set in the service environment. If these points are acceptable and you harden network exposure and protect HA_TOKEN, the skill's behavior is coherent with its stated purpose. If you cannot restrict the bridge port or do not want local services to invoke OpenClaw automatically, do not enable the bridge component.

这个 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：当前架构定位与已知限制