文本转语音字段参考
字段参考¶
提供商 apiKey 字段(包括 personas.<id>.providers.<provider>.apiKey)在全局、每个智能体和 Discord 语音 TTS 配置中可以是原始字符串或 SecretRef。在 Gateway 冷启动期间,不可用的 TTS SecretRef 会将内置 TTS 能力标记为已配置但不可用,而不是停止 Gateway。随后 tts.speak 返回 UNAVAILABLE,原因为 SECRET_SURFACE_UNAVAILABLE,并且不会发送任何提供商请求。Status 和 doctor 会列出降级的 TTS 所有者及其配置路径。显式引用会保留在运行时快照中,因此环境或配置文件凭据无法静默选择不同的账户。重载和配置写入预检会应用感知所有者的降级策略:未更改的合格 TTS 所有者可以将其上次已知良好的凭据保留为过期状态,而新的或更改后的失败会变为冷状态,但不会阻塞健康的所有者。结构无效的引用和解析后的值仍会导致启动失败或拒绝更新。
顶层 tts.*
auto"off" | "always" | "inbound" | "tagged" (路径)- 自动 TTS 模式。
inbound仅在收到入站语音消息后发送音频;tagged仅在回复包含[[tts:...]]指令或[[tts:text]]块时发送音频。 enabledboolean (路径) 已弃用- 旧版开关。
openclaw doctor --fix会将其迁移为auto。 mode"final" | "all" (路径) 默认:final"all"在最终回复之外还包含工具/块回复。providerstring (路径)- 语音提供商 ID。未设置时,OpenClaw 使用注册表自动选择顺序中的第一个已配置提供商。旧版
provider: "edge"会被openclaw doctor --fix重写为"microsoft"。 personastring (路径)-
来自
personas的当前使用 persona ID。规范化为小写。<ParamField path="personas.
" type="object"> 稳定的语音身份。字段: label、description、provider、fallbackPolicy、providers.<provider>。参见 Personas。 summaryModelstring (路径)- 用于自动摘要的低成本模型;默认为
agents.defaults.model.primary。接受provider/model或已配置的模型别名。 modelOverridesobject (路径)-
允许模型发出 TTS 指令。
enabled默认为true;allowProvider默认为false。<ParamField path="providers.
" type="object"> 按语音提供商 ID 键控的提供商自有设置。旧版直接块( tts.openai、.elevenlabs、.microsoft、.edge)会被openclaw doctor --fix重写;只提交tts.providers.<id>。 maxTextLengthnumber (路径) 默认:4096- TTS 输入字符的硬上限。如果超过,
/tts audio、tts.convert和tts.speak将失败。 timeoutMsnumber (路径) 默认:30000- 以毫秒为单位的请求超时时间。设置后,每次调用的
timeoutMs(智能体工具、gateway)优先;否则,显式配置的tts.timeoutMs优先于任何插件编写的提供商默认值。
Azure Speech
apiKeystring (路径)- 环境变量:
AZURE_SPEECH_KEY、AZURE_SPEECH_API_KEY或SPEECH_KEY。 regionstring (路径)- Azure Speech 区域(例如
eastus)。环境变量:AZURE_SPEECH_REGION或SPEECH_REGION。 endpointstring (路径)- 可选的 Azure Speech 端点覆盖(别名:
baseUrl)。 speakerVoicestring (路径)- Azure 语音 ShortName。默认为
en-US-JennyNeural。旧版别名:voice。 langstring (路径)- SSML 语言代码。默认为
en-US。 outputFormatstring (路径)- 标准音频的 Azure
X-Microsoft-OutputFormat。默认为audio-24khz-48kbitrate-mono-mp3。 voiceNoteOutputFormatstring (路径)- 语音留言输出的 Azure
X-Microsoft-OutputFormat。默认为ogg-24khz-16bit-mono-opus。
ElevenLabs
apiKeystring (路径)- 回退使用
ELEVENLABS_API_KEY或XI_API_KEY。 modelIdstring (路径)- 模型 ID。默认为
eleven_multilingual_v2;使用 v3 请设置modelId: "eleven_v3"。配置键model会被忽略。旧版 IDeleven_turbo_v2_5/eleven_turbo_v2会被规范化为匹配的flash模型。 speakerVoiceIdstring (路径)- ElevenLabs 语音 ID。默认为
pMsXgVXv3BLzUgSXRplE。旧版别名:voiceId。 voiceSettingsobject (路径)- 参数:
stability、similarityBoost、style(各为0..1,默认0.5/0.75/0)、useSpeakerBoost(true|false,默认true)、speed(0.5..2.0,默认1.0)。 applyTextNormalization"auto" | "on" | "off" (路径)- 文本规范化模式。
languageCodestring (路径)- 两位 ISO 639-1 语言代码(例如
en、de)。 seednumber (路径)- 整数
0..4294967295,用于尽力而为的确定性。 baseUrlstring (路径)- 覆盖 ElevenLabs API 基础 URL。
Google Gemini
apiKeystring (路径)- 回退使用
GEMINI_API_KEY/GOOGLE_API_KEY。如果省略,TTS 在环境变量回退之前可以复用models.providers.google.apiKey。 modelstring (路径)- Gemini TTS 模型。默认为
gemini-3.1-flash-tts-preview。设置gemini-3.8-flash-tts或gemini-3.8-flash-lite-tts可选择使用 Gemini 3.8,OpenClaw 会通过 Interactions API 发送。gemini-2.5-flash-preview-tts和gemini-2.5-pro-preview-tts也同样可用。 speakerVoicestring (路径)- Gemini 预置语音名称。默认为
Kore。旧版别名:voiceName、voice。 audioProfilestring (路径)- 自然语言表达风格。Gemini 3.8 会将其作为
speech_metadata.style发送。Gemini 3.1 和 2.5 预览模型会将其添加到朗读文本之前。 speakerNamestring (路径)- 可选的说话人标签。Gemini 3.8 会将其作为结构化的
speech_metadata.speaker标签,与单个配置的语音一起发送。旧版预览模型会在朗读文本之前添加Speaker name:。
speakers array (path)
: 正好两个 { speaker, voice, style? } 条目。在 Gemini 3.8 上,以两个已配置名称之一加冒号(其后可有或可无空格)开头的行会成为对话轮次,且该名称不会被朗读;任何其他行(包括其他 Word: text 散文)都保留在当前轮次内。没有配置标签的转录文本保持单语音。
`promptTemplate` *"audio-profile-v1"* (path)
: 在 Gemini 3.1 和 2.5 预览模型上,将激活的人设字段包装进一个确定性的 prompt。在 Gemini 3.8 上,`personaPrompt` 作为 `speech_metadata.style` 发送且不会被朗读;人设标签不会发送。
`personaPrompt` *string* (path)
: Google 专属人设指示。Gemini 3.8 将其作为样式元数据发送。较旧的预览模型会将其附加到 audio-profile 模板的 Director's Notes 中。
`baseUrl` *string* (path)
: 仅接受 `https://generativelanguage.googleapis.com`。
Gradium
apiKeystring (path)- 环境变量:
GRADIUM_API_KEY。 baseUrlstring (path)api.gradium.ai上的 HTTPS Gradium API URL。默认https://api.gradium.ai。speakerVoiceIdstring (path)- 默认 Emma(
YTpq7expH9539ERJ)。旧版别名:voiceId。
Inworld
<a id="inworld-primary" />
apiKeystring (path)- 环境变量:
INWORLD_API_KEY。 baseUrlstring (path)- 默认
https://api.inworld.ai。 modelIdstring (path)- 默认
inworld-tts-1.5-max。也可用:inworld-tts-1.5-mini、inworld-tts-1-max、inworld-tts-1。 speakerVoiceIdstring (path)- 默认
Sarah。旧版别名:voiceId。 temperaturenumber (path)- 采样温度
0..2(不含 0)。
本地 CLI(tts-local-cli)
commandstring (path)- 用于 CLI TTS 的本地可执行文件或命令字符串。
argsstring[] (path)- 命令参数。支持
{{Text}}、{{OutputPath}}、{{OutputDir}}、{{OutputBase}}占位符。 outputFormat"mp3" | "opus" | "wav" (path)- 预期的 CLI 输出格式。音频附件默认
mp3。 timeoutMsnumber (path)- 命令超时时间(毫秒)。设置后会覆盖已解析的 TTS 请求超时时间。省略时遵循请求超时;插件默认为
120000。 cwdstring (path)-
可选的命令工作目录。
<ParamField path="env" type="Record
">命令的可选环境变量覆盖。 命令的 stdout 以及生成或转换后的音频限制为 50 MiB。诊断用 stderr 限制为 1 MiB。当任一限制被超过时,OpenClaw 会终止命令并使合成失败。
Microsoft(无需 API 密钥)
enabledboolean (path)- 允许使用 Microsoft 语音。
speakerVoicestring (path)- Microsoft 神经语音名称(例如
en-US-MichelleNeural)。旧版别名:voice。如果默认英文语音生效且回复文本以 CJK 为主,OpenClaw 会自动切换到zh-CN-XiaoxiaoNeural。 langstring (path)- 语言代码(例如
en-US)。 outputFormatstring (path)- Microsoft 输出格式。默认
audio-24khz-48kbitrate-mono-mp3。并非所有格式都受捆绑的 Edge 后端传输支持。 rate / pitch / volumestring (path)- 百分比字符串(例如
+10%、-5%)。 saveSubtitlesboolean (path)- 在音频文件旁写入 JSON 字幕。
proxystring (path)- 用于 Microsoft 语音请求的代理 URL。
timeoutMsnumber (path)- 请求超时覆盖(毫秒)。
edge.*object (path) 已弃用- 旧版别名。运行
openclaw doctor --fix将持久化配置重写为providers.microsoft。
MiniMax
apiKeystring (path)- 回退到
MINIMAX_API_KEY。Token Plan 认证通过MINIMAX_OAUTH_TOKEN、MINIMAX_CODE_PLAN_KEY或MINIMAX_CODING_API_KEY。 baseUrlstring (path)- 默认
https://api.minimax.io。环境变量:MINIMAX_API_HOST。 modelstring (path)- 默认
speech-2.8-hd。环境变量:MINIMAX_TTS_MODEL。 speakerVoiceIdstring (path)- 默认
English_expressive_narrator。环境变量:MINIMAX_TTS_VOICE_ID。旧版别名:voiceId。 speednumber (path)0.5..2.0。默认1.0。volnumber (path)(0, 10]。默认1.0。pitchnumber (path)- 整数
-12..12。默认0。小数部分会在请求前被截断。
OpenAI
apiKeystring (path)- 回退到
OPENAI_API_KEY。 modelstring (path)- OpenAI TTS 模型 ID。默认
gpt-4o-mini-tts。 speakerVoicestring (path)- 语音名称(例如
alloy、cedar)。默认coral。旧版别名:voice。 instructionsstring (path)- 显式的 OpenAI
instructions字段。设置后,人设 prompt 字段将不会被自动映射。 responseFormat"mp3" | "opus" | "wav" (path)-
显式的响应格式。省略时,OpenClaw 为语音备忘录目标选择 Opus,否则选择 MP3。对于不编码压缩音频的兼容本地端点,请使用
wav。<ParamField path="extraBody / extra_body" type="Record
">生成 OpenAI TTS 字段后合并到 /audio/speech请求体中的额外 JSON 字段。将此用于需要lang等供应商专属键的 OpenAI 兼容端点(如 Kokoro);不安全的原型键会被忽略。 baseUrlstring (path)- 覆盖 OpenAI TTS 端点。解析顺序:config →
OPENAI_TTS_BASE_URL→https://api.openai.com/v1。非默认值会被视为 OpenAI 兼容的 TTS 端点,因此接受自定义模型和语音名称,且speed不再进行0.25..4.0范围检查。
OpenRouter
apiKeystring (path)- 环境变量:
OPENROUTER_API_KEY。可复用models.providers.openrouter.apiKey。
`baseUrl` *string*(路径)
: 默认 `https://openrouter.ai/api/v1`。旧版 `https://openrouter.ai/v1` 会被规范化。
`model` *string*(路径)
: 默认 `hexgrad/kokoro-82m`。别名:`modelId`。
`speakerVoice` *string*(路径)
: 默认 `af_alloy`。旧版别名:`voice`、`voiceId`。
`responseFormat` *"mp3" | "pcm"*(路径)
: 默认 `mp3`。
`speed` *number*(路径)
: 服务商原生速度覆盖。
??? note "Volcengine (BytePlus Seed Speech)"
`apiKey` *string*(路径)
: 环境变量:`VOLCENGINE_TTS_API_KEY` 或 `BYTEPLUS_SEED_SPEECH_API_KEY`。
`resourceId` *string*(路径)
: 默认 `seed-tts-1.0`。环境变量:`VOLCENGINE_TTS_RESOURCE_ID`。当你的项目拥有 TTS 2.0 权限时,请使用 `seed-tts-2.0`。
`appKey` *string*(路径)
: App key 请求头。默认 `aGjiRDfUWi`。环境变量:`VOLCENGINE_TTS_APP_KEY`。
`baseUrl` *string*(路径)
: 覆盖 Seed Speech TTS 的 HTTP 端点。环境变量:`VOLCENGINE_TTS_BASE_URL`。
`speakerVoice` *string*(路径)
: 音色类型。默认 `en_female_anna_mars_bigtts`。环境变量:`VOLCENGINE_TTS_VOICE`。旧版别名:`voice`。
`speedRatio` *number*(路径)
: 服务商原生语速比例,`0.2..3`。
`emotion` *string*(路径)
: 服务商原生情感标签。
`appId / token / cluster` *string*(路径)*已弃用*
: 旧版 Volcengine Speech 控制台字段。环境变量:`VOLCENGINE_TTS_APPID`、`VOLCENGINE_TTS_TOKEN`、`VOLCENGINE_TTS_CLUSTER`(默认 `volcano_tts`)。
??? note "xAI"
`apiKey` *string*(路径)
: 环境变量:`XAI_API_KEY`。
`baseUrl` *string*(路径)
: 默认 `https://api.x.ai/v1`。环境变量:`XAI_BASE_URL`。
`speakerVoiceId` *string*(路径)
: 默认 `eve`。有认证时,`openclaw infer tts voices --provider xai` 会获取当前内置音色目录;无认证时则列出离线回退音色 `ara`、`eve`、`leo`、`rex` 和 `sal`。账户自定义音色 ID 即使不在内置列表中,也会被转发。旧版别名:`voiceId`。
`language` *string*(路径)
: BCP-47 语言代码或 `auto`。默认 `en`。
`responseFormat` *"mp3" | "wav" | "pcm" | "mulaw" | "alaw"*(路径)
: 默认 `mp3`。
`speed` *number*(路径)
: 服务商原生速度覆盖,`0.7..1.5`。
??? note "Xiaomi MiMo"
`apiKey` *string*(路径)
: 环境变量:`XIAOMI_API_KEY`。
`baseUrl` *string*(路径)
: 默认 `https://api.xiaomimimo.com/v1`。环境变量:`XIAOMI_BASE_URL`。
`model` *string*(路径)
: 默认 `mimo-v2.5-tts`。环境变量:`XIAOMI_TTS_MODEL`。也支持 `mimo-v2.5-tts-voicedesign`。
`speakerVoice` *string*(路径)
: 预设音色模型默认使用 `mimo_default`。环境变量:`XIAOMI_TTS_VOICE`。旧版别名:`voice`。对于 `mimo-v2.5-tts-voicedesign`,不会发送该参数。
`format` *"mp3" | "wav"*(路径)
: 默认 `mp3`。环境变量:`XIAOMI_TTS_FORMAT`。
`style` *string*(路径)
: 可选的自然语言风格指令,作为用户消息发送;不会被朗读。对于 `mimo-v2.5-tts-voicedesign`,此参数为音色设计 prompt;省略时 OpenClaw 会提供默认值。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw