shazhou-ww
abf38b212d
- 添加 docs/shared/tts-guide.md - 涵盖 provider 配置、auto 模式、中文音色、使用方式、踩坑记录 - 在 mkdocs.yml nav 的 Shared 分类下添加条目
113 lines
2.9 KiB
Markdown
113 lines
2.9 KiB
Markdown
# OpenClaw TTS 语音功能配置指南
|
|
|
|
## 1. 概述
|
|
|
|
OpenClaw 内置 TTS（Text-to-Speech）语音功能，支持以下三种 provider：
|
|
|
|
| Provider | 是否免费 | 需要 API Key |
|
|
|----------|---------|-------------|
|
|
| Microsoft Edge TTS | ✅ 免费 | ❌ 不需要 |
|
|
| OpenAI TTS | ❌ 付费 | ✅ 需要 |
|
|
| ElevenLabs | ❌ 付费 | ✅ 需要 |
|
|
|
|
> **推荐方案：** Microsoft Edge TTS 免费且无需 API key，推荐作为默认方案。
|
|
|
|
## 2. 配置方法
|
|
|
|
在 `openclaw.json` 的 `messages.tts` 下配置：
|
|
|
|
```json
|
|
{
|
|
"messages": {
|
|
"tts": {
|
|
"auto": "off",
|
|
"provider": "microsoft",
|
|
"microsoft": {
|
|
"enabled": true,
|
|
"voice": "zh-CN-XiaoxiaoNeural",
|
|
"lang": "zh-CN"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### auto 模式说明
|
|
|
|
| 模式 | 说明 |
|
|
|------|------|
|
|
| `off` | 默认关闭，可通过 `/tts` 命令或 tts 工具手动触发 |
|
|
| `always` | 每条回复自动转语音 |
|
|
| `inbound` | 收到语音消息时才回复语音 |
|
|
| `tagged` | 回复中包含 `[[tts]]` 标签时才转语音 |
|
|
|
|
## 3. 可用中文音色
|
|
|
|
### zh-CN 女声
|
|
|
|
| 音色名称 | 风格特点 |
|
|
|----------|---------|
|
|
| `zh-CN-XiaoxiaoNeural` | 温暖（新闻/小说风格） |
|
|
| `zh-CN-XiaoyiNeural` | 活泼可爱（卡通/小说风格） |
|
|
|
|
### zh-CN 男声
|
|
|
|
| 音色名称 | 风格特点 |
|
|
|----------|---------|
|
|
| `zh-CN-YunjianNeural` | 热血激情（体育/小说） |
|
|
| `zh-CN-YunxiNeural` | 活泼阳光（小说） |
|
|
| `zh-CN-YunxiaNeural` | 可爱少年（卡通/小说） |
|
|
| `zh-CN-YunyangNeural` | 专业沉稳（新闻） |
|
|
|
|
### zh-HK 粤语
|
|
|
|
| 音色名称 | 性别 |
|
|
|----------|------|
|
|
| `zh-HK-HiuGaaiNeural` | 女 |
|
|
| `zh-HK-HiuMaanNeural` | 女 |
|
|
| `zh-HK-WanLungNeural` | 男 |
|
|
|
|
## 4. 使用方式
|
|
|
|
### tts 工具
|
|
|
|
Agent 可直接调用内置 `tts` 工具发送语音消息。
|
|
|
|
### /tts 命令
|
|
|
|
用户可通过斜杠命令使用：
|
|
|
|
```
|
|
/tts audio <文字> # 生成一条语音
|
|
/tts always # 开启自动语音模式
|
|
/tts off # 关闭自动语音
|
|
/tts inbound # 收到语音时才回复语音
|
|
```
|
|
|
|
## 5. Telegram 特别说明
|
|
|
|
- Telegram 会显示**圆形语音气泡**（Opus 格式），体验最佳
|
|
- 飞书目前收到的是**音频文件**而非语音气泡
|
|
|
|
## 6. 踩坑记录
|
|
|
|
### "produced empty audio file" 错误
|
|
|
|
- **现象：** Microsoft Edge TTS 返回空音频文件
|
|
- **原因：** 服务器网络到 Microsoft 端点不稳定
|
|
- **解决：**
|
|
1. 重启 gateway 后通常恢复：`openclaw gateway restart`
|
|
2. 通过命令行验证 Edge TTS 是否可用：`npx node-edge-tts --text "测试" --voice zh-CN-XiaoxiaoNeural`
|
|
|
|
### 自动 Fallback
|
|
|
|
如果 Microsoft Edge TTS 不可用，系统会自动尝试 fallback 到 OpenAI 或 ElevenLabs（需要对应的 API key 已配置）。
|
|
|
|
### 长文本处理
|
|
|
|
长文本会自动摘要后再转语音（需在配置中设置 `summaryModel`）。
|
|
|
|
### 短文本跳过
|
|
|
|
短于 **10 个字符**的回复会自动跳过 TTS，不生成语音。
|