VoiceClaw

核心用法

VoiceClaw 是专为 OpenClaw 代理设计的纯离线语音 I/O 系统，实现双向语音处理能力：

• 语音输入 (STT)：通过 whisper.cpp 本地运行 Whisper ggml-base.en.bin 模型，将音频文件（支持 ogg/mp3/m4a/wav/flac）转录为文本
• 语音输出 (TTS)：通过 Piper 引擎将文本合成为自然语音，支持 8 种英语音色

典型工作流程：接收语音消息 → 调用 transcribe.sh 转录 → 生成回复 → 调用 speak.sh 合成语音 → ffmpeg 转换为 OGG Opus 格式 → 发送语音+文本双回复。

显著优点

1. 零网络依赖：脚本执行期间完全不发起网络请求，所有推理在本地设备完成
2. 隐私零泄露：语音数据无需上传云端，杜绝第三方监听与数据留存风险
3. 零 API 成本：无需 OpenAI、Azure 等云服务商密钥，无用量计费
4. 快速响应：本地推理延迟可控，不受网络波动影响
5. 多格式支持：ffmpeg 自动处理常见音频格式转换
6. 开源可审计：基于 whisper.cpp 和 Piper，代码完全透明

潜在局限

| 局限类型 | 具体说明 |

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

| 语言限制 | 当前仅优化支持英语，其他语言需更换模型 |

| 模型体积 | Whisper 基础模型约 150MB，Piper 语音模型各约 50-100MB |

| 硬件要求 | 需要足够的 CPU/GPU 资源进行本地推理 |

| 安装复杂度 | 需手动安装 3 个二进制文件并下载模型，非一键部署 |

| 音色选择 | 仅内置 8 种英语预设音色，无法自定义训练 |

| 上下文长度 | 建议语音回复控制在 200 词以内，过长文本合成质量下降 |

适合人群

• 隐私敏感型用户：医疗、法律、金融从业者处理敏感语音信息
• 离线环境部署：内网隔离、无公网访问权限的服务器场景
• 成本控制场景：高频语音交互需求，希望消除按量计费
• 技术爱好者：具备 Linux 命令行基础，愿意维护本地推理环境

常规风险

| 风险类别 | 等级 | 说明 |

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

| 数据泄露 | 极低 | 本地处理，无网络传输 |

| 依赖可用性 | 中等 | 需确保二进制文件和模型文件存在，否则技能失效 |

| 推理错误 | 中等 | 本地模型准确度可能低于云端大模型，专业术语识别有误 |

| 存储占用 | 低 | 模型文件总计约 200-500MB |

| 环境配置 | 中等 | PATH、环境变量配置不当导致二进制无法调用 |

> 关键安全承诺：技能脚本执行期间 transcribe.sh 和 speak.sh 均不发起任何网络请求，仅在首次设置时需要下载模型文件。

核心用法

VoiceClaw 为 OpenClaw Agent 提供端到端的本地语音处理能力，包含两个核心脚本：transcribe.sh 负责将入站音频转录为文本，speak.sh 负责将文本合成为语音回复。用户接收语音消息后，Agent 自动调用转录功能获取文字内容，生成回复后通过 TTS 引擎合成音频，最终以"语音+文字"双模形式响应。

部署需预先安装三个本地二进制：whisper.cpp（语音识别）、piper-tts（语音合成）和 ffmpeg（格式转换），并下载约 150MB 的 Whisper 模型文件。所有环境路径均可通过环境变量自定义，支持多种英语口音的 Piper 声模选择。

显著优点

绝对隐私保障：技能脚本零网络调用设计从根本上消除数据外泄风险，语音数据不出本地设备，完全符合 GDPR/CCPA 合规要求，特别适合医疗、法律等高隐私敏感场景。

零运营成本：无需订阅任何云服务或管理 API 密钥，一次性配置后即可无限使用，长期运行成本显著低于云端语音方案。

离线可用性：完全脱离互联网依赖，适用于内网环境、边缘设备或网络受限场景，确保服务连续性。

开源生态支撑：基于 ggerganov/whisper.cpp 和 Piper 等成熟开源项目，技术透明度高，社区活跃，漏洞响应及时。

潜在缺点与局限性

部署复杂度：相比一键调用的云端 API，需手动安装编译 whisper.cpp、配置 Python 依赖、下载模型文件，对非技术用户门槛较高。

硬件资源占用：本地推理依赖设备算力，低配置设备可能出现延迟；150MB 模型文件对存储受限设备也是负担。

语言支持有限：当前仅支持英语语音处理（whisper-base.en 模型 + Piper 英语声模），多语言场景需自行更换模型。

音质与延迟权衡：Piper 的"low"质量声模速度更快但音质下降，"medium"音质更佳但推理耗时增加，需根据场景取舍。

适合的目标群体

• 隐私优先型用户：政府机构、医疗机构、金融机构等对数据主权有严格要求的组织
• 离线/边缘场景开发者：需要在无网络环境运行的物联网设备、工控系统、野外作业终端
• 成本控制敏感团队：初创公司、个人开发者希望消除 API 调用费用
• 开源技术拥护者：偏好透明可控技术栈，避免供应商锁定

使用风险

依赖管理风险：技能依赖外部二进制程序，若系统 PATH 被篡改存在恶意代码执行可能；建议部署后锁定环境变量，生产环境考虑二进制完整性校验。

模型文件维护：Whisper 模型需手动更新，长期未维护可能错过准确率改进；模型文件损坏会导致服务中断。

格式兼容性：Telegram 等平台要求 OGG Opus 格式，ffmpeg 转换参数错误可能导致音频无法播放，需严格遵循文档中的编码参数。

性能瓶颈：并发语音请求可能挤占本地计算资源，高负载场景需评估硬件配置或限制并发数。

声模文件管理：Piper 声模分散存放，多项目共用易出现版本冲突，建议通过 VOICECLAW_VOICES_DIR 隔离管理。