OpenClaw 的 ESP32 语音助手

为 OpenClaw 赋予硬件级语音能力：一台运行 原生 ESPHome 固件 的 ESP32-S3-BOX-3 直接与 Docker 桥接服务通信 —— 设备端唤醒词检测（on-device wake word）、语音活动检测（VAD）、语音转文本（STT），由 OpenClaw 充当智能体大脑，再将分句流式合成的文本转语音（TTS）音频实时推送至扬声器。整个语音链路中不经过 Home Assistant，且无需修改设备固件：该桥接服务通过 ESPHome 原生 API（TCP 6053）模拟 Home Assistant 语音客户端行为，因此你无需重新刷写固件或编辑设备 YAML 配置。

唤醒词（设备端）→ ESP32-S3-BOX-3 → 桥接服务（Docker）：VAD → STT（xAI｜ElevenLabs）
  → 口语化确认应答 → OpenClaw /v1/chat/completions → TTS（xAI｜ElevenLabs，流式输出）
  → 设备通过 HTTP（:10400 端口，FLAC 格式）拉取回复音频

作者所用设备响应自定义训练的唤醒词 "Yo Marvin"。你可选用任意标准 ESPHome 唤醒词（例如 "Hey Jarvis"），或自行训练专属唤醒词；相关流程详见《Hardware Voice Assistant for OpenClaw》文档。

STT 和 TTS 服务提供商可独立切换为 xAI Grok Voice 或 ElevenLabs —— 支持自由组合（例如：低成本 xAI STT + ElevenLabs 自定义音色用于 TTS）。

硬件要求与前置条件

• ESP32-S3-BOX-3，需运行支持设备端唤醒词的 ESPHome 语音助手固件（如官方提供的 wake-word-voice-assistants 配置，或其衍生版本；支持标准唤醒词或自定义训练唤醒词）。其他兼容 ESPHome 的语音设备理论上也可工作；桥接服务会自动适配设备所声明的媒体格式。
• 同一局域网内的 Docker 主机 —— 设备必须能访问桥接服务的 HTTP 端口（默认为 10400）。
• 已启用聊天接口（chat interface）的 OpenClaw —— 桥接服务调用 OpenClaw 提供的 OpenAI 兼容接口 /v1/chat/completions，该端点仅在 OpenClaw 配置中启用聊天接口后才对外提供。该端点须可从桥接服务所在容器访问（默认 compose 配置假定其位于 Docker 主机的 18789 端口）。
• xAI API 密钥 和/或 ElevenLabs API 密钥 —— 至少提供一个，且需与你设定的 STT_PROVIDER/TTS_PROVIDER 相匹配。ELEVENLABS_VOICE_ID 在 TTS 使用 ElevenLabs 时为必填项。

部署步骤

1. 克隆代码仓库并创建配置文件：

   git clone https://github.com/darrenjrobinson/voice-esp32-openclaw.git
   cd voice-esp32-openclaw
   cp .env.example .env
   

2. 在 OpenClaw 中，确保已启用聊天接口，使 /v1/chat/completions 接口正常提供服务，并记录其 URL 与 API 密钥。

3. 编辑 .env 文件 —— 至少需设置以下变量：STT_PROVIDER/TTS_PROVIDER、对应 API 密钥、OPENCLAW_URL、OPENCLAW_API_KEY、ESP32_HOST（若设备 API 启用加密，则还需设置 ESP32_NOISE_PSK），以及 BRIDGE_ADVERTISE_HOST（即 Docker 主机在局域网中的 IP 地址 —— 此值在容器内必需）。本技能附带一份带注释的参考示例文件 example.env。

4. 断开 Home Assistant 对该设备的语音订阅（禁用 ESPHome 集成条目，或禁用其 assist satellite 实体）。该协议仅允许单个语音助手订阅者；若存在两个订阅者，唤醒词将静默失效，无任何响应。

5. 启动桥接服务并验证连接状态：

   docker compose --profile bridge up -d --build
   docker compose logs -f voice-bridge
   # 预期日志中出现："Connected to  (…)" 和 "device announcement format: flac @ 48000 Hz"
   

6. 说出唤醒词。完成。

配置项参考（全部位于 .env 中）

每轮对话的成本统计（美元金额 + ElevenLabs 积分）将追加写入 out/metrics.jsonl。典型单轮成本约为 $0.005（全 xAI 方案）至 $0.015（ElevenLabs TTS 方案）。

故障排查

• .env 修改未生效：容器仅在创建时读取 .env 文件。请在仓库根目录下执行 docker compose --profile bridge up -d（若提示“无变更”，请额外添加 --force-recreate 参数）。仅执行 restart 不足以触发配置重载。
• OpenClaw 返回 401 或连接被拒：请确认 OpenClaw 已启用聊天接口（即确有提供 /v1/chat/completions 接口）、OPENCLAW_URL 可从容器内部访问，且 OPENCLAW_API_KEY 与 OpenClaw 配置完全一致。
• 唤醒词无响应：其他服务（通常是 Home Assistant）仍持有语音助手订阅权限 —— 协议限制仅允许单一订阅者。
• 无语音回复：请检查 BRIDGE_ADVERTISE_HOST 是否为 Docker 主机 在局域网中的 IP 地址，并确认设备可访问该主机的 10400 端口。
• 设备异常行为（如拒绝分块传输、仅支持 FLAC 解码、设备广播卡死、音量控制异常等）已在桥接服务中统一处理 —— 若怀疑设备问题，请先查阅 README 中的 “Device quirks” 表格。
• 回滚操作：执行 docker compose --profile bridge down，然后在 Home Assistant 中重新启用 ESPHome 集成 —— 设备将立即恢复使用 HA Assist 语音流水线；设备端从未发生任何变更。

延伸阅读

• Going Direct — ESP32 Voice for OpenClaw —— 本集成方案的完整技术说明。
• Hardware Voice Assistant for OpenClaw —— 设备部署指南及自定义唤醒词（如 "Yo Marvin"）训练方法。
• GitHub: darrenjrobinson/voice-esp32-openclaw —— 源码、完整 README、成本分析及实用脚本。