核心用法
本 skill 为 OpenClaw WebChat 的 Control UI 叠加语音输入功能。部署后，用户界面将新增麦克风按钮，点击后浏览器通过 MediaRecorder API 采集音频，经本地 faster-whisper 服务转写为文本，再注入对话流。整套方案无需调用云端 API，实现完全离线的语音识别。
部署流程分为四步：
1. 前置依赖检查：确认 openclaw-transcribe.service 已运行，默认监听 127.0.0.1:18790。
2. 前端注入：将 voice-input.js 置入 Control UI 静态资源，并向 index.html 插入 script 标签。
3. 网关配置：在 gateway 的 allowedOrigins 中登记 HTTPS UI 地址，避免跨域拦截。
4. 代理启动：以 systemd 用户服务形式常驻 HTTPS/WSS 反向代理，对外暴露 8443 端口，对内透传至 gateway WebSocket。
脚本支持幂等执行，可通过 VOICE_HOST/VOICE_HTTPS_PORT 自定义监听地址。
显著优点
- 零 API 成本：依托本地 faster-whisper，无按量计费或网络延迟。
- 隐私优先：音频流不离开本机，适合敏感场景。
- 无缝集成：麦克风按钮 UI 与 WebChat 原生样式一致，支持录音中/停止/等待三种状态。
- 开箱自启：systemd 用户服务确保重启后自动恢复，TLS 证书路径持久化。
潜在缺点与局限性
- 前置依赖重：必须预先部署
faster-whisper-local-service，否则整个链路无法工作。 - 本地算力消耗：whisper 模型推理占用 GPU/CPU，低配设备可能出现延迟。
- 证书管理负担：自签名 TLS 需手动信任或自行维护 ACME，易因证书过期导致服务中断。
- 浏览器限制：MediaRecorder 的编码格式支持因浏览器而异，极端情况下需 polyfill。
适合人群
- 注重隐私、不愿将语音数据上传云端的技术用户。
- 已本地部署 OpenClaw 全家桶，希望补齐语音交互能力的进阶玩家。
- 拥有足够算力（建议 4G+ VRAM 或现代 CPU）支撑实时转写的场景。
常规风险
- 服务耦合：transcription 服务异常会直接导致麦克风按钮失效，需熟悉 systemd 日志排查。
- 网络配置陷阱：
origin not allowed与token missing是最常见的集成错误，需按文档顺序逐一核对 gateway 配置与 URL 参数。 - 持久化路径：若证书存放于
/tmp，重启后丢失，导致 HTTPS 握手失败。 - 模型加载延迟：faster-whisper 冷启动耗时数秒，首次点击麦克风可能无响应。