跳转至

文本转语音字段参考

字段参考

提供商 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]] 块时发送音频。
enabled boolean (路径) 已弃用
旧版开关。openclaw doctor --fix 会将其迁移为 auto。
mode "final" | "all" (路径) 默认:final
"all" 在最终回复之外还包含工具/块回复。
provider string (路径)
语音提供商 ID。未设置时,OpenClaw 使用注册表自动选择顺序中的第一个已配置提供商。旧版 provider: "edge" 会被 openclaw doctor --fix 重写为 "microsoft"。
persona string (路径)

来自 personas 的当前使用 persona ID。规范化为小写。

<ParamField path="personas." type="object"> 稳定的语音身份。字段:label、description、provider、fallbackPolicy、providers.<provider>。参见 Personas。

summaryModel string (路径)
用于自动摘要的低成本模型;默认为 agents.defaults.model.primary。接受 provider/model 或已配置的模型别名。
modelOverrides object (路径)

允许模型发出 TTS 指令。enabled 默认为 true;allowProvider 默认为 false。

<ParamField path="providers." type="object"> 按语音提供商 ID 键控的提供商自有设置。旧版直接块(tts.openai、.elevenlabs、.microsoft、.edge)会被 openclaw doctor --fix 重写;只提交 tts.providers.<id>。

maxTextLength number (路径) 默认:4096
TTS 输入字符的硬上限。如果超过,/tts audio、tts.convert 和 tts.speak 将失败。
timeoutMs number (路径) 默认:30000
以毫秒为单位的请求超时时间。设置后,每次调用的 timeoutMs(智能体工具、gateway)优先;否则,显式配置的 tts.timeoutMs 优先于任何插件编写的提供商默认值。
Azure Speech
apiKey string (路径)
环境变量:AZURE_SPEECH_KEY、AZURE_SPEECH_API_KEY 或 SPEECH_KEY。
region string (路径)
Azure Speech 区域(例如 eastus)。环境变量:AZURE_SPEECH_REGION 或 SPEECH_REGION。
endpoint string (路径)
可选的 Azure Speech 端点覆盖(别名:baseUrl)。
speakerVoice string (路径)
Azure 语音 ShortName。默认为 en-US-JennyNeural。旧版别名:voice。
lang string (路径)
SSML 语言代码。默认为 en-US。
outputFormat string (路径)
标准音频的 Azure X-Microsoft-OutputFormat。默认为 audio-24khz-48kbitrate-mono-mp3。
voiceNoteOutputFormat string (路径)
语音留言输出的 Azure X-Microsoft-OutputFormat。默认为 ogg-24khz-16bit-mono-opus。
ElevenLabs
apiKey string (路径)
回退使用 ELEVENLABS_API_KEY 或 XI_API_KEY。
modelId string (路径)
模型 ID。默认为 eleven_multilingual_v2;使用 v3 请设置 modelId: "eleven_v3"。配置键 model 会被忽略。旧版 ID eleven_turbo_v2_5/eleven_turbo_v2 会被规范化为匹配的 flash 模型。
speakerVoiceId string (路径)
ElevenLabs 语音 ID。默认为 pMsXgVXv3BLzUgSXRplE。旧版别名:voiceId。
voiceSettings object (路径)
参数: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" (路径)
文本规范化模式。
languageCode string (路径)
两位 ISO 639-1 语言代码(例如 en、de)。
seed number (路径)
整数 0..4294967295,用于尽力而为的确定性。
baseUrl string (路径)
覆盖 ElevenLabs API 基础 URL。
Google Gemini
apiKey string (路径)
回退使用 GEMINI_API_KEY / GOOGLE_API_KEY。如果省略,TTS 在环境变量回退之前可以复用 models.providers.google.apiKey。
model string (路径)
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 也同样可用。
speakerVoice string (路径)
Gemini 预置语音名称。默认为 Kore。旧版别名:voiceName、voice。
audioProfile string (路径)
自然语言表达风格。Gemini 3.8 会将其作为 speech_metadata.style 发送。Gemini 3.1 和 2.5 预览模型会将其添加到朗读文本之前。
speakerName string (路径)
可选的说话人标签。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
apiKey string (path)
环境变量:GRADIUM_API_KEY。
baseUrl string (path)
api.gradium.ai 上的 HTTPS Gradium API URL。默认 https://api.gradium.ai。
speakerVoiceId string (path)
默认 Emma(YTpq7expH9539ERJ)。旧版别名:voiceId。
Inworld
<a id="inworld-primary" />
apiKey string (path)
环境变量:INWORLD_API_KEY。
baseUrl string (path)
默认 https://api.inworld.ai。
modelId string (path)
默认 inworld-tts-1.5-max。也可用:inworld-tts-1.5-mini、inworld-tts-1-max、inworld-tts-1。
speakerVoiceId string (path)
默认 Sarah。旧版别名:voiceId。
temperature number (path)
采样温度 0..2(不含 0)。
本地 CLI(tts-local-cli)
command string (path)
用于 CLI TTS 的本地可执行文件或命令字符串。
args string[] (path)
命令参数。支持 {{Text}}、{{OutputPath}}、{{OutputDir}}、{{OutputBase}} 占位符。
outputFormat "mp3" | "opus" | "wav" (path)
预期的 CLI 输出格式。音频附件默认 mp3。
timeoutMs number (path)
命令超时时间(毫秒)。设置后会覆盖已解析的 TTS 请求超时时间。省略时遵循请求超时;插件默认为 120000。
cwd string (path)

可选的命令工作目录。

<ParamField path="env" type="Record">命令的可选环境变量覆盖。

命令的 stdout 以及生成或转换后的音频限制为 50 MiB。诊断用 stderr 限制为 1 MiB。当任一限制被超过时,OpenClaw 会终止命令并使合成失败。

Microsoft(无需 API 密钥)
enabled boolean (path)
允许使用 Microsoft 语音。
speakerVoice string (path)
Microsoft 神经语音名称(例如 en-US-MichelleNeural)。旧版别名:voice。如果默认英文语音生效且回复文本以 CJK 为主,OpenClaw 会自动切换到 zh-CN-XiaoxiaoNeural。
lang string (path)
语言代码(例如 en-US)。
outputFormat string (path)
Microsoft 输出格式。默认 audio-24khz-48kbitrate-mono-mp3。并非所有格式都受捆绑的 Edge 后端传输支持。
rate / pitch / volume string (path)
百分比字符串(例如 +10%、-5%)。
saveSubtitles boolean (path)
在音频文件旁写入 JSON 字幕。
proxy string (path)
用于 Microsoft 语音请求的代理 URL。
timeoutMs number (path)
请求超时覆盖(毫秒)。
edge.* object (path) 已弃用
旧版别名。运行 openclaw doctor --fix 将持久化配置重写为 providers.microsoft。
MiniMax
apiKey string (path)
回退到 MINIMAX_API_KEY。Token Plan 认证通过 MINIMAX_OAUTH_TOKEN、MINIMAX_CODE_PLAN_KEY 或 MINIMAX_CODING_API_KEY。
baseUrl string (path)
默认 https://api.minimax.io。环境变量:MINIMAX_API_HOST。
model string (path)
默认 speech-2.8-hd。环境变量:MINIMAX_TTS_MODEL。
speakerVoiceId string (path)
默认 English_expressive_narrator。环境变量:MINIMAX_TTS_VOICE_ID。旧版别名:voiceId。
speed number (path)
0.5..2.0。默认 1.0。
vol number (path)
(0, 10]。默认 1.0。
pitch number (path)
整数 -12..12。默认 0。小数部分会在请求前被截断。
OpenAI
apiKey string (path)
回退到 OPENAI_API_KEY。
model string (path)
OpenAI TTS 模型 ID。默认 gpt-4o-mini-tts。
speakerVoice string (path)
语音名称(例如 alloy、cedar)。默认 coral。旧版别名:voice。
instructions string (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);不安全的原型键会被忽略。

baseUrl string (path)
覆盖 OpenAI TTS 端点。解析顺序:config → OPENAI_TTS_BASE_URL → https://api.openai.com/v1。非默认值会被视为 OpenAI 兼容的 TTS 端点,因此接受自定义模型和语音名称,且 speed 不再进行 0.25..4.0 范围检查。
OpenRouter
apiKey string (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