stt-tts 模式中的语音输出部分(talk.speak 调用相同的
合成路径)。提供商原生的 realtime Talk 会话改为在实时提供商内部
合成语音;transcription 会话从不
合成助手语音回复。
快速开始
1
选择提供商
OpenAI 和 ElevenLabs 是最可靠的托管选项。Microsoft 和
Local CLI 无需 API key 即可工作。完整列表请参阅提供商矩阵。
2
设置 API key
导出你的提供商所需的环境变量(例如
OPENAI_API_KEY、
ELEVENLABS_API_KEY)。Microsoft 和 Local CLI 无需 API key。3
在配置中启用
设置
tts.auto: "always" 和 tts.provider:4
在聊天中试用
/tts status 显示当前状态。/tts audio Hello from OpenClaw
发送一次性音频回复。自动 TTS 默认关闭。未设置
tts.provider 时,
OpenClaw 会按照注册表自动选择顺序选取第一个已配置的提供商。
内置的 tts Agent 工具仅用于明确意图:普通聊天仍使用
文本,除非用户请求音频、使用 /tts,或启用自动 TTS/指令
语音。支持的提供商
如果配置了多个提供商,将优先使用选定的提供商,其他提供商则作为回退选项。
自动摘要使用
summaryModel(或
agents.defaults.model.primary),因此如果保持启用摘要,
也必须对该提供商进行身份验证。
配置
TTS 配置位于~/.openclaw/openclaw.json 中的 tts 下。选择一个
预设并调整提供商配置块。下方显示的 speakerVoice/speakerVoiceId
字段是规范字段;每个提供商自己的 voice/voiceId/
voiceName 字段名仍可作为旧版别名使用。
- Azure Speech
- ElevenLabs
- Google Gemini
- Gradium
- Inworld
- Local CLI
- Microsoft(无需 API key)
- MiniMax
- OpenAI + ElevenLabs
- OpenRouter
- Volcengine
- xAI
- Xiaomi MiMo
mimo-v2.5-tts-voicedesign,请省略 speakerVoice,并将 style 设置为
语音设计提示。OpenClaw 会将该提示作为 TTS 的 user 消息发送,
并且不会为 voicedesign 模型发送 audio.voice。
每个 Agent 的语音覆盖配置
当某个 Agent 应使用不同的提供商、语音、模型、角色设定或自动 TTS 模式时, 请使用agents.entries.*.tts。Agent 配置块会深度合并并覆盖
tts,因此提供商凭据可以保留在全局提供商配置中:
agents.entries.*.tts.persona 与提供商配置一同设置——它仅为该智能体覆盖全局 tts.persona。
自动回复、/tts audio、/tts status 和
tts 智能体工具的优先级顺序:
tts- 活动的
agents.entries.*.tts - 渠道覆盖(当渠道支持
channels.<channel>.tts时) - 账号覆盖(当渠道传递
channels.<channel>.accounts.<id>.tts时) - 此主机的本地
/tts偏好设置 - 启用模型驱动指令时的内联
[[tts:...]]指令
tts 相同的结构,并在之前的层级之上进行深度合并,因此共享的提供商凭据可以保留在
tts 中,而渠道或 Bot 账号只需更改说话声音、模型、persona
或自动模式:
Persona
Persona 是一种稳定的语音身份,可以确定性地应用于不同提供商。 它可以首选某个提供商、定义与提供商无关的提示意图,并携带声音、模型、提示模板、种子和声音设置等提供商专属绑定。最小 persona
完整 persona(提供商专属塑形)
Persona 解析
活动 persona 按以下确定性顺序选择:/tts persona <id>本地偏好设置(如果已设置)。tts.persona(如果已设置)。- 无 persona。
- 直接覆盖(CLI、Gateway 网关、Talk、允许的 TTS 指令)。
/tts provider <id>本地偏好设置。- 活动 persona 的
provider。 tts.provider。- 注册表自动选择。
tts.providers.<id>tts.personas.<persona>.providers.<id>- 可信请求覆盖
- 允许的模型生成 TTS 指令覆盖
自定义 persona 塑形
与提供商无关的personas.<id>.prompt.* 配置已停用。Doctor 会移除这些字段,并指向语音提供商接缝。请将内置提供商设置放在 personas.<id>.providers.<provider> 下(例如 Google
personaPrompt 或 OpenAI instructions)。如需自定义塑形,请使用 prepareSynthesis(ctx) 实现语音提供商插件,并在 synthesize() 运行前返回调整后的文本、提供商配置或覆盖。这样可将富有表现力的提示构建保留在了解请求语义的提供商代码中。
回退策略
fallbackPolicy 控制 persona 对尝试的提供商没有绑定时的行为:
只有在尝试的所有提供商均被跳过或失败时,整个 TTS 请求才会失败。
Talk 会话的提供商选择仅作用于会话范围。Talk 客户端应从
talk.catalog 中选择提供商 ID、模型 ID、声音 ID 和区域设置,并通过 Talk 会话或交接请求传递这些值。打开语音会话不应修改 tts 或全局 Talk 提供商默认值。
模型驱动指令
默认情况下,助手可以生成[[tts:...]] 指令,为单次回复覆盖声音、模型或速度,还可以附加可选的
[[tts:text]]...[[/tts:text]] 块,用于仅应出现在音频中的表现力提示:
tts.auto 为 "tagged" 时,必须使用指令才能触发音频。分块流式传输会在渠道看到可见文本之前移除其中的指令,即使指令被拆分到相邻的块中也是如此。
除非 modelOverrides.allowProvider: true,否则 provider=... 会被忽略。当回复声明 provider=... 时,该指令中的其他键仅由该提供商解析;不支持的键会被移除,并报告为 TTS 指令警告。
可用的指令键:
provider(已注册的提供商 ID;需要allowProvider: true)speakerVoice/speakerVoiceId(旧版别名:voice、voiceName、voice_name、google_voice、voiceId)model/google_modelstability、similarityBoost、style、speed、useSpeakerBoostvol/volume(MiniMax 音量,(0, 10])pitch(MiniMax 整数音高,−12 到 12;小数值会被截断)emotion(Volcengine 情感标签)applyTextNormalization(auto|on|off)languageCode(ISO 639-1)seed
斜杠命令
单个命令/tts。在 Discord 上,OpenClaw 还会注册 /voice,因为
/tts 是 Discord 内置命令——文本 /tts ... 仍然有效。
命令要求发送者已获授权(适用允许列表/所有者规则),并且必须启用
commands.text 或原生命令注册。/tts on将本地 TTS 偏好设置写入always;/tts off将其写入off。/tts chat on|off|default为当前聊天写入会话范围的自动 TTS 覆盖。/tts persona <id>写入本地 persona 偏好设置;/tts persona off将其清除。/tts latest从当前会话记录中读取最新的助手回复,并将其作为音频发送一次。它仅在会话条目中存储该回复的哈希值,以避免重复发送语音。/tts audio生成一次性音频回复(不会开启 TTS)。/tts limit <chars>接受 100–4096(4096 是 Telegram 说明文字/消息的最大值);超出此范围的值会被拒绝。limit和summary存储在本地偏好设置中,而不是主配置中。/tts status包含最近一次尝试的回退诊断信息——Fallback: <primary> -> <used>、Attempts: ...,以及每次尝试的详细信息(provider:outcome(reasonCode) latency)。/status会在启用 TTS 时显示活动 TTS 模式,以及已配置的提供商、模型、声音和经过清理的自定义端点元数据。
每用户偏好设置
斜杠命令会将本地覆盖写入 TTS 偏好设置路径。默认路径为~/.openclaw/settings/tts.json;可使用 OPENCLAW_TTS_PREFS 覆盖。Doctor
会将已停用的全局 tts.prefsPath 值移入共享机器状态。
在有意让智能体使用独立偏好设置存储的高级多智能体配置中,仍可设置 agents.entries.<id>.tts.prefsPath。
这些设置会覆盖由
tts 加上该主机活动的
agents.entries.*.tts 块所产生的有效配置。
输出格式
TTS 语音传递由渠道能力驱动。渠道插件会声明语音式 TTS 是否应要求提供商生成原生voice-note 目标,还是继续使用普通的 audio-file 合成,以及渠道是否会在发送前对非原生输出进行转码。
各提供商说明:
- **Feishu / WhatsApp 转码:**当语音留言回复以 MP3/WebM/WAV/M4A 或其他可能的音频文件形式生成时,渠道插件会在发送原生语音消息之前,使用
ffmpeg(libopus,64 kbps)将其转码为 48 kHz Ogg/Opus。WhatsApp 通过 Baileysaudio载荷发送结果,并设置ptt: true和audio/ogg; codecs=opus。转码失败时:Feishu 会捕获错误并回退为将原始文件作为普通附件发送;WhatsApp 没有回退机制,因此发送本身会失败,而不会发布不兼容的 PTT 载荷。 - **MiniMax:**普通音频附件使用 MP3(
speech-2.8-hd模型,32 kHz 采样率);对于渠道声明支持的语音留言目标,使用ffmpeg转码为 48 kHz Opus。 - **Xiaomi MiMo:**默认使用 MP3,也可配置为 WAV;对于渠道声明支持的语音留言目标,使用
ffmpeg转码为 48 kHz Opus。 - **本地 CLI:**使用已配置的
outputFormat。语音留言目标会转换为 Ogg/Opus,电话输出则使用ffmpeg转换为原始 16 kHz 单声道 PCM。 - **Google Gemini:**返回原始 24 kHz PCM。OpenClaw 将其封装为 WAV 以用作音频附件,为语音留言目标转码为 48 kHz Opus,并为 Talk/电话直接返回 PCM。
- **Gradium:**音频附件使用 WAV,语音留言目标使用 Opus,电话场景使用 8 kHz 的
ulaw_8000。 - **Inworld:**普通音频附件使用 MP3,语音留言目标使用原生
OGG_OPUS,Talk/电话使用 22050 Hz 的原始PCM。 - **xAI:**默认使用 MP3;音频文件合成可为缓冲输出和流式输出使用
mp3、wav、pcm、mulaw或alaw。语音留言目标在流式输出和缓冲回退时使用 MP3,因为 xAI 的pcm、mulaw和alaw输出是不含标头的原始音频。缓冲合成使用 xAI 的批量 REST/v1/tts端点;textToSpeechStream使用原生wss://api.x.ai/v1/tts。这不是实时语音契约。不支持原生 Opus 语音留言格式。 - **Microsoft:**使用
microsoft.outputFormat(默认为audio-24khz-48kbitrate-mono-mp3)。- 内置传输层接受
outputFormat,但服务并不提供所有格式。 - 输出格式值遵循 Microsoft Speech 输出格式(包括 Ogg/WebM Opus)。
- Telegram
sendVoice接受 OGG/MP3/M4A;如果需要确保生成 Opus 语音消息,请使用 OpenAI/ElevenLabs。 - 如果配置的 Microsoft 输出格式失败,OpenClaw 会使用 MP3 重试。
- 如果未设置明确的语音覆盖项,并且使用默认英语语音,当回复文本主要由 CJK 字符组成时,OpenClaw 会自动切换到中文神经网络语音(
zh-CN-XiaoxiaoNeural,zh-CN区域设置)。
- 内置传输层接受
自动 TTS 行为
启用tts.auto 后,OpenClaw 会:
- 如果回复已包含结构化媒体,则跳过 TTS。
- 跳过非常短的回复(少于 10 个字符)。
- 启用摘要时,使用
summaryModel(或agents.defaults.model.primary)概括较长的回复。 - 将生成的音频附加到回复中。
- 在
mode: "final"中,文本流完成后,仍会为流式最终回复发送纯音频 TTS; 生成的媒体会像普通回复附件一样经过相同的 渠道媒体标准化处理。
maxLength,OpenClaw 绝不会直接跳过音频:
- 启用摘要(默认)且摘要模型可用:将文本概括为大约
maxLength个字符,然后合成摘要。 - 关闭摘要、摘要生成失败,或摘要模型没有可用的 API key:
将文本截断为
maxLength个字符,然后合成 截断后的文本。
字段参考
顶层 tts.*
顶层 tts.*
"off" | "always" | "inbound" | "tagged"
自动 TTS 模式。
inbound 仅在收到入站语音消息后发送音频;tagged 仅在回复包含 [[tts:...]] 指令或 [[tts:text]] 块时发送音频。boolean
已弃用
旧版开关。
openclaw doctor --fix 会将其迁移到 auto。"final" | "all"
默认值:"final"
除最终回复外,
"all" 还包括工具/块回复。string
语音提供商 ID。未设置时,OpenClaw 使用注册表自动选择顺序中的第一个已配置提供商。旧版
provider: "edge" 会由 openclaw doctor --fix 重写为 "microsoft"。string
来自
personas 的活动角色 ID。标准化为小写。string
用于自动摘要的低成本模型;默认为
agents.defaults.model.primary。接受 provider/model 或已配置的模型别名。object
允许模型发出 TTS 指令。
enabled 默认为 true;allowProvider 默认为 false。object
按语音提供商 ID 设置键名的提供商自有设置。旧版直接配置块(
tts.openai、.elevenlabs、.microsoft、.edge)会由 openclaw doctor --fix 重写;仅提交 tts.providers.<id>。number
默认值:"4096"
TTS 输入字符数的硬性上限。超出时,
/tts audio、tts.convert 和 tts.speak 会失败。number
默认值:"30000"
请求超时时间,以毫秒为单位。设置后,每次调用的
timeoutMs(智能体工具、Gateway 网关)优先;否则,明确配置的 tts.timeoutMs 优先于任何插件定义的提供商默认值。apiKey 字段可以是原始字符串或 SecretRef。在 Gateway 网关
冷启动期间,不可用的 TTS SecretRef 会将内置 TTS 能力标记为
“已配置但不可用”,而不会阻止 Gateway 网关启动。随后,tts.speak 返回
UNAVAILABLE,原因为 SECRET_SURFACE_UNAVAILABLE,并且不会
发送提供商请求。状态和 Doctor 会列出降级的 TTS 所有者及其配置路径。显式
引用会保留在运行时快照中,因此环境或配置文件中的
凭据无法静默选择其他账户。重新加载和配置写入
预检会应用可感知所有者的降级策略:未更改且符合条件的 TTS
所有者可以继续使用其最后已知有效的凭据作为过期凭据,而新的或已更改的
故障会转为冷状态,且不会阻止正常的所有者。结构无效的引用
和解析后的值仍会导致启动失败或更新被拒绝。Azure Speech
Azure Speech
string
环境变量:
AZURE_SPEECH_KEY、AZURE_SPEECH_API_KEY 或 SPEECH_KEY。string
Azure Speech 区域(例如
eastus)。环境变量:AZURE_SPEECH_REGION 或 SPEECH_REGION。string
可选的 Azure Speech 端点覆盖项(别名为
baseUrl)。string
Azure 语音 ShortName。默认为
en-US-JennyNeural。旧版别名:voice。string
SSML 语言代码。默认为
en-US。string
用于标准音频的 Azure
X-Microsoft-OutputFormat。默认为 audio-24khz-48kbitrate-mono-mp3。string
用于语音留言输出的 Azure
X-Microsoft-OutputFormat。默认为 ogg-24khz-16bit-mono-opus。ElevenLabs
ElevenLabs
string
回退到
ELEVENLABS_API_KEY 或 XI_API_KEY。string
模型 ID。默认为
eleven_multilingual_v2。旧版 ID eleven_turbo_v2_5/eleven_turbo_v2 会标准化为匹配的 flash 模型。string
ElevenLabs 语音 ID。默认为
pMsXgVXv3BLzUgSXRplE。旧版别名:voiceId。object
stability、similarityBoost、style(每项均为 0..1,默认值分别为 0.5/0.75/0)、useSpeakerBoost(true|false,默认为 true)、speed(0.5..2.0,默认为 1.0)。"auto" | "on" | "off"
文本标准化模式。
string
双字母 ISO 639-1 代码(例如
en、de)。number
用于尽力实现确定性的整数
0..4294967295。string
覆盖 ElevenLabs API 基础 URL。
Google Gemini
Google Gemini
string
回退到
GEMINI_API_KEY / GOOGLE_API_KEY。如果省略,TTS 可以在回退到环境变量之前复用 models.providers.google.apiKey。string
Gemini TTS 模型。默认值为
gemini-3.1-flash-tts-preview。string
Gemini 预构建语音名称。默认值为
Kore。旧版别名:voiceName、voice。string
添加在朗读文本之前的自然语言风格提示词。
string
可选的说话者标签;当提示词使用具名说话者时,添加在朗读文本之前。
"audio-profile-v1"
设为
audio-profile-v1,以确定性的 Gemini TTS 提示词结构封装当前角色提示词字段。string
附加到模板中 Director’s Notes 的 Google 专用额外角色提示词文本。
string
仅接受
https://generativelanguage.googleapis.com。Gradium
Gradium
Inworld
Inworld
本地 CLI(tts-local-cli)
本地 CLI(tts-local-cli)
string
用于 CLI TTS 的本地可执行文件或命令字符串。
string[]
命令参数。支持
{{Text}}、{{OutputPath}}、{{OutputDir}}、{{OutputBase}} 占位符。"mp3" | "opus" | "wav"
预期的 CLI 输出格式。音频附件的默认值为
mp3。number
命令超时时间(毫秒)。默认值为
120000。string
可选的命令工作目录。
Record<string, string>
可选的命令环境变量覆盖项。
Microsoft(无需 API key)
Microsoft(无需 API key)
boolean
默认值:"true"
允许使用 Microsoft 语音。
string
Microsoft 神经语音名称(例如
en-US-MichelleNeural)。旧版别名:voice。如果正在使用默认英语语音,并且回复文本以 CJK 字符为主,OpenClaw 会自动切换到 zh-CN-XiaoxiaoNeural。string
语言代码(例如
en-US)。string
Microsoft 输出格式。默认值为
audio-24khz-48kbitrate-mono-mp3。内置的 Edge 后端传输并不支持所有格式。string
百分比字符串(例如
+10%、-5%)。boolean
在音频文件旁写入 JSON 字幕。
string
Microsoft 语音请求使用的代理 URL。
number
请求超时覆盖值(毫秒)。
object
已弃用
旧版别名。运行
openclaw doctor --fix,将持久化配置重写为 providers.microsoft。MiniMax
MiniMax
string
回退到
MINIMAX_API_KEY。通过 MINIMAX_OAUTH_TOKEN、MINIMAX_CODE_PLAN_KEY 或 MINIMAX_CODING_API_KEY 进行 Token Plan 身份验证。string
默认值为
https://api.minimax.io。环境变量:MINIMAX_API_HOST。string
默认值为
speech-2.8-hd。环境变量:MINIMAX_TTS_MODEL。string
默认值为
English_expressive_narrator。环境变量:MINIMAX_TTS_VOICE_ID。旧版别名:voiceId。number
0.5..2.0。默认值为 1.0。number
(0, 10]。默认值为 1.0。number
整数
-12..12。默认值为 0。发送请求前会截断小数值。OpenAI
OpenAI
string
回退到
OPENAI_API_KEY。string
OpenAI TTS 模型 ID。默认值为
gpt-4o-mini-tts。string
语音名称(例如
alloy、cedar)。默认值为 coral。旧版别名:voice。string
显式的 OpenAI
instructions 字段。设置后,角色提示词字段不会自动映射。Record<string, unknown>
生成 OpenAI TTS 字段后,合并到
/audio/speech 请求体中的额外 JSON 字段。对于 Kokoro 等需要 lang 这类提供商专用键的 OpenAI 兼容端点,请使用此字段;不安全的原型键会被忽略。string
覆盖 OpenAI TTS 端点。解析顺序:配置 →
OPENAI_TTS_BASE_URL → https://api.openai.com/v1。非默认值会被视为 OpenAI 兼容的 TTS 端点,因此接受自定义模型和语音名称,并且 speed 不再进行 0.25..4.0 范围检查。OpenRouter
OpenRouter
Volcengine(BytePlus Seed Speech)
Volcengine(BytePlus Seed Speech)
string
环境变量:
VOLCENGINE_TTS_API_KEY 或 BYTEPLUS_SEED_SPEECH_API_KEY。string
默认值为
seed-tts-1.0。环境变量:VOLCENGINE_TTS_RESOURCE_ID。当项目具有 TTS 2.0 权限时,使用 seed-tts-2.0。string
App key 请求头。默认值为
aGjiRDfUWi。环境变量:VOLCENGINE_TTS_APP_KEY。string
覆盖 Seed Speech TTS HTTP 端点。环境变量:
VOLCENGINE_TTS_BASE_URL。string
语音类型。默认值为
en_female_anna_mars_bigtts。环境变量:VOLCENGINE_TTS_VOICE。旧版别名:voice。number
提供商原生速度比率,
0.2..3。string
提供商原生情感标签。
string
已弃用
旧版 Volcengine Speech Console 字段。环境变量:
VOLCENGINE_TTS_APPID、VOLCENGINE_TTS_TOKEN、VOLCENGINE_TTS_CLUSTER(默认值为 volcano_tts)。xAI
xAI
string
环境变量:
XAI_API_KEY。string
默认值为
https://api.x.ai/v1。环境变量:XAI_BASE_URL。string
默认值为
eve。进行身份验证后,openclaw infer tts voices --provider xai 会获取当前内置目录;未进行身份验证时,它会列出离线回退项 ara、eve、leo、rex 和 sal。即使账号自定义语音 ID 不在内置列表中,也会照常转发。旧版别名:voiceId。string
BCP-47 语言代码或
auto。默认值为 en。"mp3" | "wav" | "pcm" | "mulaw" | "alaw"
默认值为
mp3。number
提供商原生速度覆盖值,
0.7..1.5。Xiaomi MiMo
Xiaomi MiMo
string
环境变量:
XIAOMI_API_KEY。string
默认值为
https://api.xiaomimimo.com/v1。环境变量:XIAOMI_BASE_URL。string
默认值为
mimo-v2.5-tts。环境变量:XIAOMI_TTS_MODEL。还支持 mimo-v2.5-tts-voicedesign。string
预设语音模型的默认值为
mimo_default。环境变量:XIAOMI_TTS_VOICE。旧版别名:voice。使用 mimo-v2.5-tts-voicedesign 时不发送此字段。"mp3" | "wav"
默认值为
mp3。环境变量:XIAOMI_TTS_FORMAT。string
作为用户消息发送的可选自然语言风格指令;不会被朗读。对于
mimo-v2.5-tts-voicedesign,这是语音设计提示词;省略时,OpenClaw 会提供默认值。Agent 工具
tts 工具将文本转换为语音,并返回音频附件用于
发送回复。在 Feishu、Matrix、Telegram 和 WhatsApp 上,音频会
作为语音消息而非文件附件发送。当 ffmpeg 可用时,Feishu 和
WhatsApp 可以在此路径上对非 Opus TTS 输出进行转码。
WhatsApp 通过 Baileys 将音频作为 PTT 语音便笺发送(audio,并带有
ptt: true),并将可见文本与 PTT 音频分开发送,因为
客户端无法始终如一地显示语音便笺的说明文字。
该工具接受可选的 channel 和 timeoutMs 字段;timeoutMs 是
每次调用的提供商请求超时时间(毫秒)。每次调用的值会覆盖
tts.timeoutMs;已配置的 TTS 超时时间会覆盖插件指定的任何
提供商默认值。
Gateway RPC 参考
服务链接
- OpenAI 文本转语音指南
- OpenAI Audio API 参考
- Azure Speech REST 文本转语音
- Azure Speech provider
- ElevenLabs 文本转语音
- ElevenLabs 身份验证
- Gradium
- Inworld TTS API
- MiniMax T2A v2 API
- Volcengine TTS HTTP API
- 小米 MiMo 语音合成
- node-edge-tts
- Microsoft Speech 输出格式
- xAI 文本转语音