名称： elevenlabs-tts
描述： ElevenLabs TTS - OpenClaw 上最佳的 ElevenLabs 集成。支持情感音频标签的 ElevenLabs 文本转语音，适用于 WhatsApp 的 ElevenLabs 语音合成，以及多语言支持。使用 ElevenLabs API 生成逼真的 AI 语音。
标签： [elevenlabs, tts, voice, text-to-speech, audio, speech, whatsapp, multilingual, ai-voice]
元数据： {"clawdbot":{"emoji":"🎙️","requires":{"env":["ELEVENLABS_API_KEY"],"system":["ffmpeg"]},"primaryEnv":"ELEVENLABS_API_KEY"}}
允许工具： [exec, tts, message]
使用支持音频标签的 ElevenLabs v3 生成富有表现力的语音消息。
ELEVENLABS_API_KEY): 必需。在 elevenlabs.io → 个人资料 → API 密钥 获取。在 openclaw.json 的 messages.tts.elevenlabs.apiKey 下配置。讲故事（情感旅程）：
[soft] 这开始于平常的一天... [pause] 但感觉有些不同。 [nervous] 当我打开信封时，我的手在颤抖。 [gasps] 我被录取了！ [excited] 我真的被录取了！ [laughs] [happy] 这将改变一切！
恐怖/悬疑（营造恐惧感）：
[whispers] 这房子已经空置多年了... [pause] 至少，他们是这么告诉我的。 [nervous] 但我一直听到脚步声。 [scared] 声音越来越近了。 [gasps] [panicking] 门——它自己打开了！
带反应的对话：
[curious] 会议上发生了什么？ [pause] [surprised] 等等，他们解雇了他？！ [gasps] [sad] 这太糟糕了... [sighs] 他还有家庭。 [thoughtful] 我想知道他接下来会做什么。
希伯来语（浪漫时刻）：
[soft] 她站在那里，面对着日落... [pause] 我的心跳得如此剧烈。 [nervous] 我不知道该说什么。 [hesitates] 我... [breathes] [tender] 你知道我爱你，对吧？
西班牙语（庆祝到反思）：
[excited] 我们做到了！ [laughs] [happy] 我简直不敢相信... [pause] [thoughtful] 这么多年的努力。 [emotional] [soft] 感谢所有相信我的人。 [sighs] [content] 每一刻都是值得的。
在 openclaw.json 中，在 messages.tts 下配置 TTS：
{
"messages": {
"tts": {
"provider": "elevenlabs",
"elevenlabs": {
"apiKey": "sk_your_api_key_here",
"voiceId": "pNInz6obpgDQGcFmaJgB",
"modelId": "eleven_v3",
"languageCode": "en",
"voiceSettings": {
"stability": 0.5,
"similarityBoost": 0.75,
"style": 0,
"useSpeakerBoost": true,
"speed": 1
}
}
}
}
}
获取 API 密钥：
1. 访问 https://elevenlabs.io
2. 注册/登录
3. 点击个人资料 → API 密钥
4. 复制你的密钥
这些预制的语音针对 v3 进行了优化，与音频标签配合良好：
| 语音 | ID | 性别 | 口音 | 最佳用途 |
|---|---|---|---|---|
| Adam | pNInz6obpgDQGcFmaJgB |
男 | 美式 | 深度旁白，通用 |
| Rachel | 21m00Tcm4TlvDq8ikWAM |
女 | 美式 | 平静旁白，对话 |
| Brian | nPczCjzI2devNBz1zQrb |
男 | 美式 | 深度旁白，播客 |
| Charlotte | XB0fDUnXU5powFXDhCwa |
女 | 英式-瑞典 | 富有表现力，视频游戏 |
| George | JBFqnCBsd6RMkjVDRZzb |
男 | 英式 | 沙哑旁白，讲故事 |
寻找更多语音：
- 浏览：https://elevenlabs.io/voice-library
- v3 优化合集：https://elevenlabs.io/app/voice-library/collections/aF6JALq9R6tXwCczjhKH
- API：GET https://api.elevenlabs.io/v1/voices
语音选择技巧：
- 使用 IVC（即时语音克隆）或预制语音 - PVC 尚未针对 v3 优化
- 根据用例匹配语音特性（耳语语音不适合大喊）
- 对于富有表现力的 IVC，训练样本应包含多样的情感语调
eleven_v3 (alpha) - 唯一支持音频标签的模型| 模式 | 稳定性 | 描述 |
|---|---|---|
| 创意 | 0.3-0.5 | 更具情感/表现力，可能产生幻觉 |
| 自然 | 0.5-0.7 | 平衡，最接近原始语音 |
| 稳健 | 0.7-1.0 | 高度稳定，对标签响应较弱 |
对于音频标签，使用创意 (0.5) 或自然模式。更高的稳定性会降低对标签的响应度。
范围：0.7（慢）到 1.2（快），默认 1.0
极端值会影响质量。对于节奏控制，更推荐使用 [rushed] 或 [drawn out] 等音频标签。
使用多少标签：
- 每句或每个短语使用 1-2 个标签（不要更多！）
- 标签效果会持续到下一个标签出现 - 无需重复
- 过度使用标签会听起来不自然且机械
标签放置位置：
- 情感转换点
- 关键戏剧性时刻之前
- 能量/节奏变化时
上下文很重要：
- 编写匹配标签情感的文本
- 带有上下文的长文本 = 更好的情感诠释
- 示例：[nervous] 我... 我不太确定这个。如果它不奏效怎么办？ 比 [nervous] 你好。 效果更好
组合标签以增加细微差别：
- [nervously][whispers] = 紧张的耳语
- [excited][laughs] = 兴奋的笑声
- 组合最多保持 2 个标签
重新生成以获得最佳效果：
- v3 是非确定性的 - 相同文本 = 不同输出
- 生成 3 个以上版本，选择最佳的一个
- 微调文本可以改善结果
标签与语音匹配：
- 不要在耳语语音上使用 [shouts]
- 不要在响亮/充满活力的语音上使用 [whispers]
- 用你选择的语音测试标签
v3 不支持 SSML 中断标签。请使用音频标签和标点符号代替。
标点符号增强音频标签：
- 省略号 (...) → 戏剧性停顿：[nervous] 我... 我不知道...
- 大写字母 → 强调：[excited] 这太棒了！
- 破折号 (—) → 打断：[explaining] 所以你要做的就是— [interrupting] 等等！
- 问号 → 不确定性：[nervous] 你确定这个吗？
- 感叹号！ → 能量提升：[happy] 我们做到了！
结合标签 + 标点符号以达到最佳效果：
[tired] 这是漫长的一天... [sighs] 没人再听了。
tts 工具（返回 MP3）message 工具1. 生成 TTS（在末尾添加 [pause] 以防止截断）：
tts text="[excited] 这太棒了！ [pause]" channel=whatsapp
返回：MEDIA:/tmp/tts-xxx/voice-123.mp3
2. 转换 MP3 → Opus：
ffmpeg -i /tmp/tts-xxx/voice-123.mp3 -c:a libopus -b:a 64k -vbr on -application voip /tmp/tts-xxx/voice-123.ogg
3. 发送 Opus 文件：
注意： 下面的
message字段在引号之间包含一个 Unicode 从左到右标记 (U+200E)。
这是有意为之 —— WhatsApp 要求一个非空的消息正文才能发送语音便笺。
LTR 标记不可见，但可以满足此要求而不会显示任何文本。
message action=send channel=whatsapp target="+972..." filePath="/tmp/tts-xxx/voice-123.ogg" asVoice=true message=""
| 格式 | iOS | Android | 转录 |
|---|---|---|---|
| MP3 | ✅ 可用 | ❌ 可能失败 | ❌ 否 |
| Opus (.ogg) | ✅ 可用 | ✅ 可用 | ✅ 是 |
始终转换为 Opus - 这是唯一能：
- 在所有设备上运行（iOS + Android）
- 支持 WhatsApp 转录按钮的格式
ElevenLabs 有时会截断最后一个词。始终在末尾添加 [pause] 或 ...：
[excited] 这太棒了！ [pause]
对于超过 800 字符的内容：
tts 工具生成每一段bash
cat > list.txt << EOF
file '/path/file1.mp3'
file '/path/file2.mp3'
EOF
ffmpeg -f concat -safe 0 -i list.txt -c copy final.mp3重要提示：不要提及“第 2 部分”或“章节” - 保持无缝衔接。
v3 可以在一次生成中处理多个角色：
Jessica: [whispers] 你听到了吗？
Chris: [interrupting] —我也听到了！
Jessica: [panicking] 我们需要躲起来！
对话标签：[interrupting], [overlapping], [cuts in], [interjecting]
| 类别 | 标签 | 使用时机 |
|---|---|---|
| 情感 | [excited], [happy], [sad], [angry], [nervous], [curious] | 主要情感状态 - 每部分使用 1 个 |
| 表达方式 | [whispers], [shouts], [soft], [rushed], [drawn out] | 音量/速度变化 |
| 反应 | [laughs], [sighs], [gasps], [clears throat], [gulps] | 自然的人类瞬间 - 少量点缀 |
| 节奏 | [pause], [hesitates], [stammers], [breathes] | 戏剧性时机 |
| 角色 | [French accent], [British accent], [robotic tone] | 角色语音转换 |
| 对话 | [interrupting], [overlapping], [cuts in] | 多说话者对话 |
最有效的标签（结果可靠）：
- 情感：[excited], [nervous], [sad], [happy]
- 反应：[laughs], [sighs], [whispers]
- 节奏：[pause]
可靠性较低（需测试和重新生成）：
- 音效：[explosion], [gunshot]
- 口音：结果因语音而异
完整标签列表：参见 references/audio-tags.md
标签被朗读出来？
- 确认使用 eleven_v3 模型
- 使用 IVC/预制语音，而非 PVC
- 简化标签（不要使用 "tone" 后缀）
- 增加文本长度（250+ 字符）
语音不一致？
- 段落太长 - 分割为 <800 字符
- 重新生成（v3 是非确定性的）
- 尝试较低的稳定性设置
WhatsApp 无法播放？
- 转换为 Opus 格式（见上文）
尽管有标签但没有情感？
- 语音可能与标签风格不匹配
- 尝试创意稳定性模式 (0.5)
- 在标签周围添加更多上下文