核心用法
本技能为OpenClaw WebChat Control UI提供完整的语音输入解决方案，在浏览器端实现麦克风录音、本地语音转文字（STT）和对话注入。主要组件包括：
1. 语音交互层：向Control UI注入voice-input.js，提供带状态管理（mic/stop/hourglass）的语音按钮
2. 本地转写服务：通过/transcribe端点代理到本地faster-whisper HTTP服务（默认127.0.0.1:18790）
3. 安全代理层：HTTPS/WSS反向代理（8443端口），处理TLS证书和WebSocket到gateway（ws://127.0.0.1:18789）的穿透
4. 持久化运行：systemd用户服务管理，确保重启后自动恢复
显著优点
- 零API成本：完全本地运行，无第三方语音服务订阅费用
- 隐私优先：音频数据不出本机，适合敏感场景
- 架构完整：从UI组件到网络代理的全栈方案，非简单功能叠加
- 生产级特性：TLS自动管理、systemd守护、idempotent部署脚本
- 状态感知UI：mic/stop/hourglass三态反馈，用户体验完整
潜在缺点与局限性
- 前置依赖重：必须预先部署
faster-whisper-local-service，对GPU/CPU性能有要求（模型加载内存占用显著） - 端口硬编码风险：18790/18789/8443等端口若被占用需手动调整
- 证书管理盲区：文档未说明TLS证书续期机制，长期运行可能面临证书过期
- 单点故障：转写服务崩溃将直接导致语音功能失效，无降级方案
- 浏览器兼容性：MediaRecorder API在部分老旧浏览器中支持有限
适合人群
- 已部署OpenClaw WebChat且需要语音交互的进阶用户
- 对云语音服务有隐私顾虑或成本敏感的场景
- 具备Linux系统管理能力和systemd基础知识的自托管用户
- 有GPU资源支持本地 Whisper 模型推理的环境
常规风险
| 风险类型 | 具体表现 | 缓解建议 |
|---------|---------|---------|
| 服务不可用 | 转写服务未启动或端口冲突 | 部署前严格执行`systemctl --user is-active`和curl验证 |
| 证书失效 | 重启后mic失效（文档提及/tmp路径问题） | 确保证书路径配置为持久化目录 |
| 跨域阻断 | `origin not allowed`错误 | 严格匹配`VOICE_HOST`与gateway配置 |
| 授权失败 | `token missing`或`pairing required` | 首次访问需携带token并完成设备配对审批 |
| SPA路由404 | `/chat?...`路径解析失败 | 检查HTTPS代理的SPA fallback配置 |
关键建议：本技能作为"代理层"不能独立运行，必须与faster-whisper-local-service或webchat-voice-full-stack配合使用，单独部署将导致功能完全不可用。