Voice messaging setup

核心用法

本技能为 OpenClaw 平台配置完整的语音消息处理能力，包含双向流程：

语音输入（STT）：通过 faster-whisper 本地转录语音消息。用户发送语音后，系统自动调用隔离的 Python 虚拟环境中的转录脚本，将音频转换为文本供 AI 处理。支持多模型选择（tiny 至 large），默认 small 模型平衡质量与速度。

语音输出（TTS）：通过 Microsoft Edge TTS 服务将 AI 回复合成为语音。配置 auto: "inbound" 模式后，系统仅在收到语音消息时以语音回复，文本消息则保持文本回复，实现自然交互。

显著优点

1. 零成本运行：Edge TTS 完全免费，faster-whisper 本地运行无 API 调用费用
2. 隐私友好：语音识别在本地完成，音频数据不上传第三方服务
3. 硬件适配：针对 Raspberry Pi 4/ARM 优化，small 模型 20-40 秒可完成转录
4. 灵活配置：支持语速、音调、音量调节，20+ 种语音可选
5. 智能模式：inbound 自动识别避免对文本消息滥用语音回复

潜在局限

1. 本地性能依赖：medium/large 模型在低端设备上转录时间过长（40-160 秒）
2. 首次下载延迟：Whisper 模型首次运行时自动下载（约 250MB）
3. 单语言限制：需手动配置 --lang 参数，多语言场景需额外处理
4. Edge TTS 可用性：依赖微软服务，存在间歇性不可用的风险
5. 环境隔离要求：需维护独立的 Python venv，增加运维复杂度

适合人群

• 运行 OpenClaw 自托管实例的技术用户
• 希望为 Telegram Bot 添加语音交互的开发者
• Raspberry Pi 等 ARM 设备用户寻求离线语音方案
• 注重隐私、不愿将语音数据提交云端服务的场景

常规风险

| 风险类型 | 说明 | 缓解建议 |

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

| 超时失败 | 音频过大或模型过慢导致转录超时 | 设置合理 `maxBytes` 和 `timeoutSeconds` |

| 存储膨胀 | Hugging Face 缓存模型长期累积 | 定期清理 `~/.cache/huggingface/` |

| 服务依赖 | Edge TTS 微软服务不稳定 | 准备降级到纯文本回复的预案 |

| 权限配置 | 脚本可执行权限或路径错误 | 严格遵循安装步骤验证 `chmod +x` 和绝对路径 |

| 短文本过滤 | 过短回复被 TTS 跳过 | 此为设计行为，长文本场景无影响 |

核心用法

该 Skill 为 OpenClaw 平台提供完整的语音消息处理能力，构建"语音→文本→语音"的端到端对话体验。配置分为两大模块：

STT（语音转文本）：基于 faster-whisper 开源框架，在本地虚拟环境中运行 Whisper 模型。用户需创建 Python 虚拟环境、安装 faster-whisper 依赖（约 250MB），并部署自定义转录脚本 transcribe.py。脚本支持多模型选择（tiny/base/small/medium/large）、多语言识别、CPU/CUDA 设备切换，以及 VAD（语音活动检测）过滤噪音。

TTS（文本转语音）：集成 Microsoft Edge TTS 官方服务，无需 API 密钥即可使用。配置采用 auto: "inbound" 智能模式——仅对语音消息以语音回复，文本消息仍以文字回应，避免不必要的语音干扰。

配置完成后，通过 OpenClaw Gateway 重启生效，即可在 Telegram 等平台上实现：用户发送语音 → 本地转录为文本 → Agent 理解处理 → 生成语音回复的完整流程。

显著优点

零成本 TTS 服务：Microsoft Edge TTS 完全免费，提供 Jenny、Ana、Roger 等多款高质量神经网络语音，支持语速、音调、音量参数微调，媲美商业 TTS 服务效果。

本地化隐私保护：语音识别完全在本地运行，敏感语音数据无需上传第三方，仅最终生成的文本传入云端 TTS，兼顾效率与隐私。

硬件适配灵活：针对 Raspberry Pi 等 ARM 设备优化，提供 tiny 到 large 五级模型选择，低配设备可选 small/base 模型平衡速度与精度。

配置即文档：纯 Markdown 文档型 Skill，无隐藏可执行代码，每个配置步骤透明可审计，适合安全敏感场景。

潜在缺点与局限性

首次部署门槛较高：需手动完成虚拟环境创建、pip 依赖安装、脚本权限设置、JSON 配置编辑等多步操作，对非技术用户不够友好。

模型下载耗时：Whisper 模型首次运行自动从 Hugging Face 下载（small 模型约 500MB），需等待 1-2 分钟，且依赖网络稳定性。

TTS 云端依赖：Edge TTS 需连接 Microsoft 服务，网络波动或区域限制可能导致语音合成失败，无法纯离线运行。

性能瓶颈明显：Raspberry Pi 4 运行 small 模型需 20-40 秒转录，medium/large 模型可达分钟级，实时性受限。

功能边界限制：仅支持单轮语音交互的闭环处理，不支持语音打断、情感识别、说话人分离等高级音频功能。

适合的目标群体

• OpenClaw 自托管用户：已在本地部署 OpenClaw Gateway，希望扩展语音交互能力的进阶用户
• 隐私优先型开发者：对语音数据本地化有强需求，不愿将原始音频上传云端的场景
• IoT/边缘设备爱好者：基于 Raspberry Pi 等 ARM 设备构建语音助手的硬件玩家
• Telegram Bot 运营者：需要为现有文本 Bot 低成本增加语音能力的个人开发者
• 技术学习与研究：希望深入理解 STT/TTS pipeline 架构的学生和技术研究者

常规使用风险

依赖供应链风险：faster-whisper 及底层 ctranslate2、onnxruntime 等依赖通过 PyPI 分发，存在供应链攻击可能，建议锁定依赖版本或使用私有镜像。

资源占用风险：Whisper 模型缓存常驻磁盘（~2GB 若多模型并存），转录时 CPU 占用高，可能影响同设备其他服务。

超时与容量风险：默认 20MB 文件限制和 120 秒超时可能无法处理长语音，需根据场景调优，否则导致转录失败。

隐私合规风险：Edge TTS 将文本发送至 Microsoft 云端处理，企业用户需评估 GDPR/CCPA 合规性，敏感内容建议使用本地 TTS 替代。

配置漂移风险：JSON 配置手动编辑易出错，建议版本控制配置变更，Gateway 重启失败时需排查配置语法。