voice-tts

语音输入（ASR）+ 语音输出（TTS）技能，完整替代 OpenClaw 内置 tts 工具处理中文内容。

技术概览

方向	技术	说明
语音 → 文字	Whisper（本地）	接收语音，自动转文字
文字 → 语音

Edge TTS（云端） | 生成 MP3，发送 Telegram 语音消息 |

---

工作方式

ASR（语音 → 文字）

用户发来语音消息 → voice-asr.mjs 转写为文字 → 触发 agent 处理。

语音识别在 OpenClaw 工具层自动完成，agent 收到的是文字。

TTS（文字 → 语音）

agent 回复文字后，如需以语音发送，调用 sendvoicereply.mjs 手动发送 Telegram 语音消息：

bash
node /path/to/voice-tts/scripts/sendvoicereply.mjs \
--text 你的回复内容 \
--chat-id 8317347201 \
--agent main

---

快速安装

方式一：一键安装（推荐）

bash

默认安装 turbo 模型

bash /path/to/voice-tts/install.sh

国内加代理

bash /path/to/voice-tts/install.sh --proxy http://127.0.0.1:7897

方式二：手动安装

bash
pip install edge-tts whisper click
brew install ffmpeg # macOS
sudo apt install -y ffmpeg # Ubuntu

安装完成后运行冒烟测试：

bash
bash tests/smoke.sh

---

配置（可选）

config.default.json 已包含所有默认值，不填配置可直接使用。

如需自定义 agent 音色映射或 ASR 参数，在 openclaw.json 的 skills.entries.voice-tts.config 中覆盖：

json
{
skills: {
entries: {
voice-tts: {
enabled: true,
config: {
tts: {
defaultVoice: zh-CN-XiaoxiaoNeural,
agentVoices: {
main: zh-CN-XiaoxiaoNeural,
researcher: zh-CN-YunxiNeural,
product: zh-CN-XiaoyiNeural,
coder: zh-CN-YunyangNeural,
devops: zh-CN-YunjianNeural
}
},
asr: {
defaultInitialPrompt: 以下是中文语音转文字。常见词包括：管家、研究员、邮差、码农、产品、运维、OpenClaw、小爱、Telegram。,
defaultTemperature: 0,
conditionOnPreviousText: true
}
}
}
}
}
}

修改后执行 openclaw gateway restart。

---

核心脚本

语音合成 — bin/voice-tts.mjs

将文字转为语音文件：

bash

基本用法

node bin/voice-tts.mjs 你好 -f /tmp/demo.mp3

指定 agent 音色

node bin/voice-tts.mjs 你好 -f /tmp/demo.mp3 --agent main

指定声音 / 语速

node bin/voice-tts.mjs 你好 -f /tmp/demo.mp3 -v zh-CN-YunxiNeural -r +10%

可用中文音色：zh-CN-XiaoxiaoNeural（女声，推荐）、zh-CN-YunxiNeural、zh-CN-XiaoyiNeural、zh-CN-YunyangNeural、zh-CN-YunjianNeural、zh-CN-XiaomoNeural

语音识别 — bin/voice-asr.mjs

将音频文件转文字：

bash

基本用法

node bin/voice-asr.mjs audio.ogg

指定模型 / 语言

node bin/voice-asr.mjs audio.ogg --model turbo --language zh

输出 JSON（含语言检测）

node bin/voice-asr.mjs audio.ogg --json

可用模型：tiny base small turbo large-v3

发送 Telegram 语音 — scripts/sendvoicereply.mjs

一键完成文字 → TTS 合成 → Telegram 语音消息发送：

bash
node scripts/sendvoicereply.mjs \
--text 已收到！ \
--chat-id 8317347201 \
--agent main

参数说明：

参数	必填	说明
--text	✅	要语音播报的文字内容
--chat-id

✅ | Telegram 目标用户 ID |
| --agent | 否 | agent id，自动选对应音色 |
| --voice | 否 | 覆盖默认音色，如 zh-CN-YunxiNeural |
| --rate | 否 | 语速，如 +10%、-5% |
| --token | 否 | 直接指定 Telegram Bot Token |

Token 自动查找优先级：

1. 1. --token 参数
2. openclaw.json → channels.telegram.accounts.<当前agent>.botToken
3. openclaw.json → channels.telegram.accounts.default.botToken
4. 环境变量 TELEGRAMBOTTOKEN

---

文件结构

voice-tts/
├── SKILL.md # 本文档
├── config.default.json # 默认配置（直接可用，不需修改）
├── install.sh # 一键安装脚本
│
├── bin/
│ ├── voice-tts.mjs # TTS 入口
│ └── voice-asr.mjs # ASR 入口
│
├── lib/
│ ├── config.mjs # 配置读取（支持 openclaw.json 覆盖）
│ ├── errors.mjs # 统一错误码 + 用户兜底消息
│ └── audio.mjs # 音频校验
│
├── scripts/
│ ├── sendvoicereply.mjs # Telegram 语音发送（核心）
│ └── autovoicecheck # 批量处理未处理语音
│
└── tests/
└── smoke.sh # 冒烟测试

注意： scripts/edge_tts 和 scripts/whisper 是内部 Python 封装，非直接入口；直接使用上表中的 bin/ 入口即可。

---

错误码

错误码	含义	用户兜底消息
nofilepath	未提供音频文件	抱歉，没有收到音频文件，请重试。
filenotfound

文件不存在 | 抱歉，音频文件没找到，请重试。 | | file_empty | 文件为空 | 抱歉，音频文件是空的，请重试。 | | filetoosmall | 文件过小 | 抱歉，音频文件不完整，请重试。 | | file_stale | 文件过期 | 抱歉，音频文件已过期，请重试。 | | transcription_failed | Whisper 转写失败 | 抱歉，语音识别失败了，请重试。 | | synthesis_failed | Edge TTS 生成失败 | 抱歉，语音生成失败了，请重试。 | | timeout | 执行超时 | 抱歉，处理超时了，请稍后重试。 |

---

语音文件自动归档

voice-asr.mjs 成功转写后，自动将原文件从 ~/.openclaw/media/inbound/ 复制到 agent workspace media/inbound/，然后删除原文件。

• - ✅ 成功时：复制归档，删除原文件
• ❌ 失败时：保留原文件，可重试

---

故障排查

bash

检查依赖

ffmpeg -version
python3 -c import edge_tts; print(edge-tts ok)
python3 -c import whisper; print(whisper ok)

检查未处理语音文件

ls -la ~/.openclaw/media/inbound/

直接测试 ASR

node bin/voice-asr.mjs ~/.openclaw/media/inbound/your-file.ogg

直接测试 TTS

node bin/voice-tts.mjs 测试 -f /tmp/test.mp3

运行冒