文本转语音
文本转语音（TTS）
OpenClaw 可以使用 ElevenLabs、OpenAI 或 Edge TTS 将出站回复转换为音频。 它在 OpenClaw 可以发送音频的任何地方工作；Telegram 会获得圆形语音笔记气泡。
支持的服务
- ElevenLabs（主要或回退提供商）
- OpenAI（主要或回退提供商；也用于摘要）
- Edge TTS（主要或回退提供商；使用
node-edge-tts，无 API 密钥时的默认值）
Edge TTS 说明
Edge TTS 通过 node-edge-tts 库使用 Microsoft Edge 的在线神经 TTS 服务。
它是一个托管服务（非本地），使用 Microsoft 的端点，不需要 API 密钥。
node-edge-tts 公开语音配置选项和输出格式，但并非所有选项都受 Edge 服务支持。
由于 Edge TTS 是没有公布 SLA 或配额的公共 Web 服务，请将其视为尽力而为。 如果你需要保证的限制和支持，请使用 OpenAI 或 ElevenLabs。 Microsoft 的 Speech REST API 记录了每个请求 10 分钟的音频限制；Edge TTS 没有公布限制，因此假设类似或更低的限制。
可选密钥
如果你想要 OpenAI 或 ElevenLabs：
ELEVENLABS_API_KEY（或XI_API_KEY）OPENAI_API_KEY
Edge TTS 不需要 API 密钥。如果未找到 API 密钥，OpenClaw 默认
使用 Edge TTS（除非通过 messages.tts.edge.enabled=false 禁用）。
如果配置了多个提供商，首先使用选定的提供商，其他提供商作为回退选项。
自动摘要使用配置的 summaryModel（或 agents.defaults.model.primary），
因此如果你启用摘要，该提供商也必须经过认证。
服务链接
默认是否启用？
否。自动 TTS 默认关闭。在配置中使用
messages.tts.auto 启用，或每个会话使用 /tts always（别名：/tts on）。
一旦 TTS 开启，Edge TTS 默认启用，并且在没有 OpenAI 或 ElevenLabs API 密钥时自动使用。
配置
TTS 配置位于 openclaw.json 中的 messages.tts 下。
完整模式在 网关配置 中。
最小配置（启用 + 提供商）
{
messages: {
tts: {
auto: "always",
provider: "elevenlabs",
},
},
}
OpenAI 主要，ElevenLabs 回退
{
messages: {
tts: {
auto: "always",
provider: "openai",
summaryModel: "openai/gpt-4.1-mini",
modelOverrides: {
enabled: true,
},
openai: {
apiKey: "openai_api_key",
model: "gpt-4o-mini-tts",
voice: "alloy",
},
elevenlabs: {
apiKey: "elevenlabs_api_key",
baseUrl: "https://api.elevenlabs.io",
voiceId: "voice_id",
modelId: "eleven_multilingual_v2",
seed: 42,
applyTextNormalization: "auto",
languageCode: "en",
voiceSettings: {
stability: 0.5,
similarityBoost: 0.75,
style: 0.0,
useSpeakerBoost: true,
speed: 1.0,
},
},
},
},
}
Edge TTS 主要（无 API 密钥）
{
messages: {
tts: {
auto: "always",
provider: "edge",
edge: {
enabled: true,
voice: "en-US-MichelleNeural",
lang: "en-US",
outputFormat: "audio-24khz-48kbitrate-mono-mp3",
rate: "+10%",
pitch: "-5%",
},
},
},
}
禁用 Edge TTS
{
messages: {
tts: {
edge: {
enabled: false,
},
},
},
}
自定义限制 + 偏好路径
{
messages: {
tts: {
auto: "always",
maxTextLength: 4000,
timeoutMs: 30000,
prefsPath: "~/.openclaw/settings/tts.json",
},
},
}
仅在入站语音笔记后使用音频回复
{
messages: {
tts: {
auto: "inbound",
},
},
}
为长回复禁用自动摘要
{
messages: {
tts: {
auto: "always",
},
},
}
然后运行：
/tts summary off
字段说明
auto：自动 TTS 模式（off、always、inbound、tagged）。inbound仅在入站语音笔记后发送音频。tagged仅在回复包含[[tts]]标签时发送音频。
enabled：传统切换（doctor 会将其迁移到auto）。mode："final"（默认）或"all"（包括工具/块回复）。provider："elevenlabs"、"openai"或"edge"（回退是自动的）。- 如果
provider未设置，OpenClaw 首选openai（如果有密钥），然后elevenlabs（如果有密钥）， 否则edge。 summaryModel：用于自动摘要的可选廉价模型；默认为agents.defaults.model.primary。- 接受
provider/model或配置的模型别名。
- 接受
modelOverrides：允许模型发出 TTS 指令（默认开启）。allowProvider默认为false（提供商切换是选择加入的）。
maxTextLength：TTS 输入的硬上限（字符）。如果超过，/tts audio将失败。timeoutMs：请求超时（毫秒）。prefsPath：覆盖本地偏好 JSON 路径（提供商/限制/摘要）。apiKey值回退到环境变量（ELEVENLABS_API_KEY/XI_API_KEY、OPENAI_API_KEY）。elevenlabs.baseUrl：覆盖 ElevenLabs API 基础 URL。elevenlabs.voiceSettings：stability、similarityBoost、style：0..1useSpeakerBoost：true|falsespeed：0.5..2.0（1.0 = 正常）
elevenlabs.applyTextNormalization：auto|on|offelevenlabs.languageCode：2 字母 ISO 639-1（例如en、de）elevenlabs.seed：整数0..4294967295（尽力确定性）edge.enabled：允许 Edge TTS 使用（默认true；无 API 密钥）。edge.voice：Edge 神经语音名称（例如en-US-MichelleNeural）。edge.lang：语言代码（例如en-US）。edge.outputFormat：Edge 输出格式（例如audio-24khz-48kbitrate-mono-mp3）。- 查看 Microsoft Speech 输出格式以获取有效值；并非所有格式都受 Edge 支持。
edge.rate/edge.pitch/edge.volume：百分字符串（例如+10%、-5%）。edge.saveSubtitles：在音频文件旁边写入 JSON 字幕。edge.proxy：Edge TTS 请求的代理 URL。edge.timeoutMs：请求超时覆盖（毫秒）。
模型驱动的覆盖（默认开启）
默认情况下，模型可以为单个回复发出 TTS 指令。
当 messages.tts.auto 为 tagged 时，这些指令是触发音频所必需的。
启用时，模型可以发出 [[tts:...]] 指令来覆盖单个回复的语音，
以及可选的 [[tts:text]]...[[/tts:text]] 块来提供
仅应出现在音频中的表达性标签（笑声、唱歌提示等）。
除非 modelOverrides.allowProvider: true，否则 provider=... 指令被忽略。
示例回复负载：
Here you go.
[[tts:voiceId=pMsXgVXv3BLzUgSXRplE model=eleven_v3 speed=1.1]]
[[tts:text]](laughs) Read the song once more.[[/tts:text]]
可用的指令键（启用时）：
provider（openai|elevenlabs|edge，需要allowProvider: true）voice（OpenAI 语音）或voiceId（ElevenLabs）model（OpenAI TTS 模型或 ElevenLabs 模型 id）stability、similarityBoost、style、speed、useSpeakerBoostapplyTextNormalization（auto|on|off）languageCode（ISO 639-1）seed
禁用所有模型覆盖：
{
messages: {
tts: {
modelOverrides: {
enabled: false,
},
},
},
}
可选允许列表（启用提供商切换同时保持其他旋钮可配置）：
{
messages: {
tts: {
modelOverrides: {
enabled: true,
allowProvider: true,
allowSeed: false,
},
},
},
}
每用户偏好
斜杠命令将本地覆盖写入 prefsPath（默认：
~/.openclaw/settings/tts.json，使用 OPENCLAW_TTS_PREFS 或
messages.tts.prefsPath 覆盖）。
存储的字段：
enabledprovidermaxLength（摘要阈值；默认 1500 字符）summarize（默认true）
这些为该主机覆盖 messages.tts.*。
输出格式（固定）
- Telegram：Opus 语音笔记（ElevenLabs 的
opus_48000_64，OpenAI 的opus）。- 48kHz / 64kbps 是良好的语音笔记权衡，圆形气泡所必需。
- 其他通道：MP3（ElevenLabs 的
mp3_44100_128，OpenAI 的mp3）。- 44.1kHz / 128kbps 是语音清晰度的默认平衡。
- Edge TTS：使用
edge.outputFormat（默认audio-24khz-48kbitrate-mono-mp3）。node-edge-tts接受outputFormat，但并非所有格式都可用于 Edge 服务。- 输出格式值遵循 Microsoft Speech 输出格式（包括 Ogg/WebM Opus）。
- Telegram
sendVoice接受 OGG/MP3/M4A；如果你需要 保证的 Opus 语音笔记，请使用 OpenAI/ElevenLabs。 - 如果配置的 Edge 输出格式失败，OpenClaw 重试 MP3。
OpenAI/ElevenLabs 格式是固定的；Telegram 期望 Opus 以获得语音笔记体验。
自动 TTS 行为
启用时，OpenClaw：
- 如果回复已包含媒体或
MEDIA:指令，则跳过 TTS。 - 跳过非常短的回复（< 10 字符）。
- 启用时使用
agents.defaults.model.primary（或summaryModel）摘要长回复。 - 将生成的音频附加到回复。
如果回复超过 maxLength 且摘要关闭（或摘要模型没有 API 密钥），音频
被跳过并发送正常文本回复。
流程图
回复 -> TTS 启用？
否 -> 发送文本
是 -> 有媒体 / MEDIA: / 短？
是 -> 发送文本
否 -> 长度 > 限制？
否 -> TTS -> 附加音频
是 -> 摘要启用？
否 -> 发送文本
是 -> 摘要（summaryModel 或 agents.defaults.model.primary）
-> TTS -> 附加音频
斜杠命令使用
只有一个命令：/tts。
查看 斜杠命令 了解启用详情。
Discord 说明：/tts 是内置的 Discord 命令，因此 OpenClaw 在那里注册
/voice 作为原生命令。文本 /tts ... 仍然有效。
/tts off
/tts always
/tts inbound
/tts tagged
/tts status
/tts provider openai
/tts limit 2000
/tts summary off
/tts audio Hello from OpenClaw
注意：
- 命令需要授权的发送者（允许列表/所有者规则仍然适用）。
commands.text或原生命令注册必须启用。off|always|inbound|tagged是每会话切换（/tts on是/tts always的别名）。limit和summary存储在本地偏好中，而不是主配置中。/tts audio生成一次性音频回复（不切换 TTS 开启）。
代理工具
tts 工具将文本转换为语音并返回 MEDIA: 路径。当
结果与 Telegram 兼容时，工具包括 [[audio_as_voice]] 以便
Telegram 发送语音气泡。
网关 RPC
网关方法：
tts.statustts.enabletts.disabletts.converttts.setProvidertts.providers