VoiceClaw
Local-only voice I/O for OpenClaw agents.
- - STT:
transcribe.sh — converts audio to text via local Whisper binary - TTS:
speak.sh — converts text to speech via local Piper binary - Network calls: none — both scripts run fully offline
- No cloud APIs, no API keys required
Prerequisites
The following must be installed on the system before using this skill:
| Requirement | Purpose |
|---|
| INLINECODE2 binary | Speech-to-text inference |
| INLINECODE3 model file |
Whisper STT model |
|
piper binary | Text-to-speech synthesis |
|
*.onnx voice model files | Piper TTS voices |
|
ffmpeg | Audio format conversion |
See README.md for installation and setup instructions.
Environment Variables
| Variable | Default | Purpose |
|---|
| INLINECODE7 | auto-detected via INLINECODE8 | Path to whisper binary |
| INLINECODE9 |
~/.cache/whisper/ggml-base.en.bin | Path to Whisper model file |
|
PIPER_BIN | auto-detected via
which | Path to piper binary |
|
VOICECLAW_VOICES_DIR |
~/.local/share/piper/voices | Directory containing
.onnx voice model files |
Verify Setup
CODEBLOCK0
Inbound Voice: Transcribe
CODEBLOCK1
Override model path:
WHISPER_MODEL=/path/to/ggml-base.en.bin bash scripts/transcribe.sh audio.ogg
Outbound Voice: Speak
CODEBLOCK3
Override voice directory:
VOICECLAW_VOICES_DIR=/path/to/voices bash scripts/speak.sh "Hello." /tmp/reply.wav
Available Voices
| Voice | Style |
|---|
| INLINECODE16 | Neutral American (default) |
| INLINECODE17 |
Warm American female |
|
en_US-joe-medium | American male |
|
en_US-kusal-medium | Expressive American male |
|
en_US-danny-low | Deep American male (fast) |
|
en_GB-alba-medium | British female |
|
en_GB-northern_english_male-medium | Northern British male |
Agent Behavior Rules
- 1. Voice in → Voice + Text out. Always respond with both a voice reply and a text reply when a voice message is received.
- Include the transcript. Show "🎙️ I heard: [transcript]" at the top of every text reply to a voice message.
- Keep voice responses concise. Piper TTS works best under ~200 words — summarize for audio, include full detail in text.
- Local only. Never use a cloud TTS/STT API. Only the local
whisper and piper binaries. - Send voice before text. Send the audio file first, then follow with the text reply.
Full Example
CODEBLOCK5
Troubleshooting
| Issue | Fix |
|---|
| INLINECODE25 | Ensure whisper binary is installed and in PATH |
| Whisper model not found |
Set
WHISPER_MODEL=/path/to/ggml-base.en.bin |
|
piper: command not found | Ensure piper binary is installed and in PATH |
| Voice model missing | Set
VOICECLAW_VOICES_DIR=/path/to/voices/ |
| OGG won't play on Telegram | Ensure
-c:a libopus flag in ffmpeg command |
VoiceClaw
面向OpenClaw智能体的纯本地语音输入输出。
- - 语音转文字： transcribe.sh — 通过本地Whisper二进制文件将音频转换为文本
- 文字转语音： speak.sh — 通过本地Piper二进制文件将文本转换为语音
- 网络调用：无 — 两个脚本均完全离线运行
- 无需云API，无需API密钥
前置条件
使用此技能前，系统必须安装以下组件：
| 要求 | 用途 |
|---|
| whisper 二进制文件 | 语音转文本推理 |
| ggml-base.en.bin 模型文件 |
Whisper语音转文本模型 |
| piper 二进制文件 | 文本转语音合成 |
| *.onnx 语音模型文件 | Piper文本转语音音色 |
| ffmpeg | 音频格式转换 |
安装和设置说明请参见 README.md。
环境变量
| 变量 | 默认值 | 用途 |
|---|
| WHISPERBIN | 通过 which 自动检测 | Whisper二进制文件路径 |
| WHISPERMODEL |
~/.cache/whisper/ggml-base.en.bin | Whisper模型文件路径 |
| PIPER_BIN | 通过 which 自动检测 | Piper二进制文件路径 |
| VOICECLAW
VOICESDIR | ~/.local/share/piper/voices | 包含 .onnx 语音模型文件的目录 |
验证设置
bash
which whisper && echo 语音转文本二进制：正常
which piper && echo 文本转语音二进制：正常
which ffmpeg && echo ffmpeg：正常
ls ${WHISPER_MODEL:-$HOME/.cache/whisper/ggml-base.en.bin} && echo 语音转文本模型：正常
ls ${VOICECLAWVOICESDIR:-$HOME/.local/share/piper/voices}/*.onnx 2>/dev/null | head -1 && echo 文本转语音音色：正常
入站语音：转写
bash
转写音频→文本（支持ogg、mp3、m4a、wav、flac格式）
TRANSCRIPT=$(bash scripts/transcribe.sh /path/to/audio.ogg)
覆盖模型路径：
bash
WHISPER_MODEL=/path/to/ggml-base.en.bin bash scripts/transcribe.sh audio.ogg
出站语音：朗读
bash
步骤1：生成WAV（本地Piper — 无需网络）
WAV=$(bash scripts/speak.sh 你的回复内容。 /tmp/reply.wav en_US-lessac-medium)
步骤2：转换为OGG Opus（Telegram语音要求）
ffmpeg -i $WAV -c:a libopus -b:a 32k /tmp/reply.ogg -y -loglevel error
步骤3：通过消息工具发送（filePath=/tmp/reply.ogg）
覆盖语音目录：
bash
VOICECLAWVOICESDIR=/path/to/voices bash scripts/speak.sh 你好。 /tmp/reply.wav
可用音色
| 音色 | 风格 |
|---|
| enUS-lessac-medium | 中性美式（默认） |
| enUS-amy-medium |
温暖美式女声 |
| en_US-joe-medium | 美式男声 |
| en_US-kusal-medium | 富有表现力的美式男声 |
| en_US-danny-low | 深沉美式男声（快速） |
| en_GB-alba-medium | 英式女声 |
| en
GB-northernenglish_male-medium | 北英格兰男声 |
智能体行为规则
- 1. 语音输入→语音+文本输出。 收到语音消息时，始终同时回复语音和文本。
- 包含转写内容。 在每条语音消息的文本回复顶部显示 🎙️ 我听到：[转写内容]。
- 保持语音回复简洁。 Piper文本转语音在约200词以内效果最佳——音频内容请概括，完整细节在文本中提供。
- 仅限本地。 绝不使用云端文本转语音/语音转文本API。仅使用本地 whisper 和 piper 二进制文件。
- 先发送语音，后发送文本。 先发送音频文件，再发送文本回复。
完整示例
bash
1. 转写入站语音消息
TRANSCRIPT=$(bash path/to/voiceclaw/scripts/transcribe.sh /path/to/voice.ogg)
2. 撰写回复并生成音频
RESPONSE=部署完成。所有检查通过。
WAV=$(bash path/to/voiceclaw/scripts/speak.sh $RESPONSE /tmp/reply_$$.wav)
ffmpeg -i $WAV -c:a libopus -b:a 32k /tmp/reply_$$.ogg -y -loglevel error
3. 发送语音+文本
message(action=send, filePath=/tmp/reply_$$.ogg, ...)
reply: 🎙️ 我听到：$TRANSCRIPT\n\n$RESPONSE
故障排除
| 问题 | 解决方法 |
|---|
| whisper: command not found | 确保whisper二进制文件已安装并在PATH中 |
| 找不到Whisper模型 |
设置 WHISPER_MODEL=/path/to/ggml-base.en.bin |
| piper: command not found | 确保piper二进制文件已安装并在PATH中 |
| 缺少语音模型 | 设置 VOICECLAW
VOICESDIR=/path/to/voices/ |
| OGG无法在Telegram上播放 | 确保ffmpeg命令中包含 -c:a libopus 参数 |
