WebChat Voice Full Stack

核心用法

webchat-voice-full-stack 是一个元安装器（meta-installer），通过编排三个独立技能实现 OpenClaw WebChat 的完整语音输入能力：

1. faster-whisper-local-service：本地 STT 后端，基于 faster-whisper 在 127.0.0.1:18790 提供 HTTP 转录服务
2. webchat-https-proxy：HTTPS/WSS 反向代理，解决浏览器麦克风所需的加密上下文
3. webchat-voice-gui：语音交互界面，含麦克风按钮、VU 电平表、Push-to-Talk 快捷键、多语言支持（EN/DE/ZH）

部署流程：先安装三个子技能 → 运行 bash scripts/deploy.sh → 自动完成环境初始化、模型下载（~1.5GB）、systemd 用户服务注册、Control UI 脚本注入。

关键特性包括：SHA256 完整性校验（部署前强制验证子技能脚本）、支持环境变量覆盖（VOICE_HOST, VOICE_HTTPS_PORT, WHISPER_LANGUAGE）、纯用户级部署（无需 root）、可逆卸载流程。

---

显著优点

• 零后续成本：本地 Whisper 推理，无外部 API 调用和订阅费用
• 隐私优先：语音数据本地处理，无云端传输
• 完整性保障：部署前强制 SHA256 校验，篡改即中止
• 透明可控：所有变更文档化，systemd 服务 + 单脚本注入，卸载脚本完整提供
• 工程化体验：Push-to-Talk、连续录音快捷键、VU 电平表、i18n 覆盖专业场景需求

---

潜在缺点与局限性

• 硬件门槛：需 ~1.5GB 模型下载，首次运行依赖互联网；运行期需 Python 3.10+ 及 GStreamer
• 证书管理：自签名 TLS 证书需浏览器手动信任或额外 PKI 配置
• 依赖链复杂度：三技能串联部署，任一环节失败需逐层排查
• 无自动更新：子技能更新后需手动 rehash.sh 更新校验基线
• 平台限制：systemd 用户服务模式对非 systemd 发行版不兼容

---

适合人群

• 注重数据隐私、拒绝云端 STT 的 OpenClaw 重度用户
• 需要语音交互增强自动化工作流的技术团队
• 具备 Linux 基础运维能力、能接受自托管方案的进阶用户

---

常规风险

| 风险类别 | 具体表现 | 缓解措施 |

|---------|---------|---------|

| 供应链攻击 | 子技能脚本被篡改 | SHA256 强制校验 + 审计后 `rehash.sh` |

| 配置漂移 | 子技能独立更新后校验失败 | 更新后必须重新基线化 |

| 服务冲突 | 端口占用（18790, 8443 等） | 环境变量覆盖端口配置 |

| 证书信任失败 | 浏览器拦截自签名证书 | 手动导入根证书或使用受信 CA |

| 模型下载失败 | 首次 ~1.5GB 下载中断 | 稳定网络环境 + 断点续传依赖 wget/curl |

核心用法

WebChat Voice Full Stack 是一个元安装器（meta-installer），用于一键部署 OpenClaw WebChat 的完整语音输入能力。它按顺序协调三个子技能：faster-whisper-local-service（本地语音识别后端）、webchat-https-proxy（HTTPS/WSS 反向代理）和 webchat-voice-gui（语音交互界面）。用户只需执行 bash scripts/deploy.sh 即可完成全部部署，无需手动配置各组件间的连接。

部署过程完全本地化：创建 Python 虚拟环境、下载约 1.5GB 的 Whisper medium 模型、生成自签名 TLS 证书、向 Control UI 注入语音控制脚本，并创建两个 systemd 用户级服务实现开机自启。支持通过环境变量覆盖默认端口和语言设置，提供 VERIFY_ONLY=true 干运行模式用于部署前验证。

显著优点

零持续成本：模型下载后完全离线运行，无 API 调用费用，无外部服务依赖。

安全设计突出：具备 SHA256 完整性验证机制，部署前自动校验所有子技能脚本，篡改即中止；所有变更限于用户空间，无需 root 权限，创建的服务和文件均可干净卸载。

体验完整：支持 Push-to-Talk（按住说话）、连续录音快捷键、VU 表音量可视化，以及英/德/中三语界面。

透明可审计：作为协调层，本身不含业务逻辑，所有操作委托给可独立审查的子技能脚本，便于安全研究人员逐行验证。

潜在缺点与局限性

供应链依赖风险：安全性完全取决于三个子技能的实现质量。虽然本技能会校验脚本完整性，但校验通过后仍会执行子技能的 deploy.sh，若子技能本身存在漏洞（如提示词注入、敏感信息收集），将被引入系统。

T3 来源可信度：由 OpenClaw 社区成员 neldar 维护，非官方团队出品，代码审查和资源投入可能不及商业产品。

首次部署门槛：需预装 Python 3.10+ 和 GStreamer，首次运行需下载 1.5GB 模型，对网络环境有要求。

自签名证书限制：HTTPS 代理使用自动生成的自签名证书，浏览器端需手动信任或配置例外。

适合的目标群体

• 注重隐私的 OpenClaw 用户：希望语音数据完全本地处理，不上传云端。
• 技术型用户与开发者：有能力审查 Shell/Python 脚本，理解 systemd 服务管理。
• 成本敏感场景：需要为团队或机构部署多套环境，规避按量计费的 STT API 成本。
• 安全研究场景：需要可审计、可离线运行的语音交互基础设施。

不适合无技术背景、期望"开箱即用"且不愿阅读代码的最终用户。

使用风险

子技能供应链攻击：若子技能仓库被入侵或维护者账号被盗，恶意代码可能通过本技能的协调机制进入系统。建议隔离环境（VM/容器）中首次运行，并订阅子技能更新公告。

运行时资源占用：Whisper 模型常驻内存，对低配设备可能造成压力；HTTPS 代理和 STT 服务持续监听端口，需监控异常连接。

更新管理负担：子技能更新后必须重新审查并执行 rehash.sh 更新校验基线，自动更新机制可能带来"验证疲劳"。

卸载残留风险：虽然提供了卸载说明，但子技能的卸载脚本质量需自行验证，建议部署前备份 systemd 配置和 workspace 目录。