English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiفارسیไทย

快速开始

文本转语音

Edit source

OpenClaw 可以通过 14 个语音提供商将出站回复转换为音频，并在 Feishu、Matrix、Telegram 和 WhatsApp 上发送原生语音消息，在其他位置发送音频附件，以及为电话和 Talk 提供 PCM/Ulaw 流。

TTS 是 Talk 的 stt-tts 模式中的语音输出部分。提供商原生的 realtime Talk 会话会在实时提供商内部合成语音，而不是调用这条 TTS 路径；transcription 会话则不会合成助手语音回复。

快速开始

  • 选择提供商

    OpenAI 和 ElevenLabs 是最可靠的托管选项。Microsoft 和 Local CLI 无需 API key 即可使用。完整列表见提供商矩阵。

  • 设置 API key

    导出你的提供商对应的环境变量（例如 OPENAI_API_KEY、ELEVENLABS_API_KEY）。Microsoft 和 Local CLI 不需要密钥。

  • 在配置中启用

    设置 messages.tts.auto: "always" 和 messages.tts.provider：

    json5
    {  messages: {    tts: {      auto: "always",      provider: "elevenlabs",    },  },}

  • 在聊天中试用

    /tts status 会显示当前状态。/tts audio Hello from OpenClaw 会发送一次性音频回复。

    • 支持的提供商

    提供商 身份验证 说明
    Azure Speech AZURE_SPEECH_KEY + AZURE_SPEECH_REGION（也支持 AZURE_SPEECH_API_KEY、SPEECH_KEY、SPEECH_REGION） 原生 Ogg/Opus 语音便签输出和电话。
    DeepInfra DEEPINFRA_API_KEY OpenAI 兼容 TTS。默认使用 hexgrad/Kokoro-82M。
    ElevenLabs ELEVENLABS_API_KEY 或 XI_API_KEY 语音克隆、多语言，通过 seed 实现确定性；为 Discord 语音播放提供流式传输。
    Google Gemini GEMINI_API_KEY 或 GOOGLE_API_KEY Gemini API 批量 TTS；通过 promptTemplate: "audio-profile-v1" 感知人设。
    Gradium GRADIUM_API_KEY 语音便签和电话输出。
    Inworld INWORLD_API_KEY 流式 TTS API。原生 Opus 语音便签和 PCM 电话。
    Local CLI 无 运行已配置的本地 TTS 命令。
    Microsoft 无 通过 node-edge-tts 使用公共 Edge 神经 TTS。尽力服务，无 SLA。
    MiniMax MINIMAX_API_KEY（或 Token 方案：MINIMAX_OAUTH_TOKEN、MINIMAX_CODE_PLAN_KEY、MINIMAX_CODING_API_KEY） T2A v2 API。默认使用 speech-2.8-hd。
    OpenAI OPENAI_API_KEY 也用于自动摘要；支持人设 instructions。
    OpenRouter OPENROUTER_API_KEY（可复用 models.providers.openrouter.apiKey） 默认模型 hexgrad/kokoro-82m。
    Volcengine VOLCENGINE_TTS_API_KEY 或 BYTEPLUS_SEED_SPEECH_API_KEY（旧版 AppID/token：VOLCENGINE_TTS_APPID/_TOKEN） BytePlus Seed Speech HTTP API。
    Vydra VYDRA_API_KEY 共享的图像、视频和语音提供商。
    xAI XAI_API_KEY xAI 批量 TTS。不支持原生 Opus 语音便签。
    Xiaomi MiMo XIAOMI_API_KEY 通过 Xiaomi 聊天补全使用 MiMo TTS。

    如果配置了多个提供商，会优先使用选定的提供商，其他提供商作为回退选项。自动摘要使用 summaryModel（或 agents.defaults.model.primary），因此如果你保持摘要启用，该提供商也必须完成身份验证。

    配置

    TTS 配置位于 ~/.openclaw/openclaw.json 中的 messages.tts 下。选择一个预设并调整提供商块：

    Azure Speech

    json5
    {messages: {tts: {  auto: "always",  provider: "azure-speech",  providers: {    "azure-speech": {      apiKey: "${AZURE_SPEECH_KEY}",      region: "eastus",      voice: "en-US-JennyNeural",      lang: "en-US",      outputFormat: "audio-24khz-48kbitrate-mono-mp3",      voiceNoteOutputFormat: "ogg-24khz-16bit-mono-opus",    },  },},},}

    ElevenLabs

    json5
    {messages: {tts: {  auto: "always",  provider: "elevenlabs",  providers: {    elevenlabs: {      apiKey: "${ELEVENLABS_API_KEY}",      model: "eleven_multilingual_v2",      voiceId: "EXAVITQu4vr4xnSDxMaL",    },  },},},}

    Google Gemini

    json5
    {messages: {tts: {  auto: "always",  provider: "google",  providers: {    google: {      apiKey: "${GEMINI_API_KEY}",      model: "gemini-3.1-flash-tts-preview",      voiceName: "Kore",      // Optional natural-language style prompts:      // audioProfile: "Speak in a calm, podcast-host tone.",      // speakerName: "Alex",    },  },},},}

    Gradium

    json5
    {messages: {tts: {  auto: "always",  provider: "gradium",  providers: {    gradium: {      apiKey: "${GRADIUM_API_KEY}",      voiceId: "YTpq7expH9539ERJ",    },  },},},}

    Inworld

    json5
    {messages: {tts: {  auto: "always",  provider: "inworld",  providers: {    inworld: {      apiKey: "${INWORLD_API_KEY}",      modelId: "inworld-tts-1.5-max",      voiceId: "Sarah",      temperature: 0.7,    },  },},},}

    Local CLI

    json5
    {messages: {tts: {  auto: "always",  provider: "tts-local-cli",  providers: {    "tts-local-cli": {      command: "say",      args: ["-o", "{{OutputPath}}", "{{Text}}"],      outputFormat: "wav",      timeoutMs: 120000,    },  },},},}

    Microsoft（无密钥）

    json5
    {messages: {tts: {  auto: "always",  provider: "microsoft",  providers: {    microsoft: {      enabled: true,      voice: "en-US-MichelleNeural",      lang: "en-US",      outputFormat: "audio-24khz-48kbitrate-mono-mp3",      rate: "+0%",      pitch: "+0%",    },  },},},}

    MiniMax

    json5
    {messages: {tts: {  auto: "always",  provider: "minimax",  providers: {    minimax: {      apiKey: "${MINIMAX_API_KEY}",      model: "speech-2.8-hd",      voiceId: "English_expressive_narrator",      speed: 1.0,      vol: 1.0,      pitch: 0,    },  },},},}

    OpenAI + ElevenLabs

    json5
    {messages: {tts: {  auto: "always",  provider: "openai",  summaryModel: "openai/gpt-4.1-mini",  modelOverrides: { enabled: true },  providers: {    openai: {      apiKey: "${OPENAI_API_KEY}",      model: "gpt-4o-mini-tts",      voice: "alloy",    },    elevenlabs: {      apiKey: "${ELEVENLABS_API_KEY}",      model: "eleven_multilingual_v2",      voiceId: "EXAVITQu4vr4xnSDxMaL",      voiceSettings: { stability: 0.5, similarityBoost: 0.75, style: 0.0, useSpeakerBoost: true, speed: 1.0 },      applyTextNormalization: "auto",      languageCode: "en",    },  },},},}

    OpenRouter

    json5
    {messages: {tts: {  auto: "always",  provider: "openrouter",  providers: {    openrouter: {      apiKey: "${OPENROUTER_API_KEY}",      model: "hexgrad/kokoro-82m",      voice: "af_alloy",      responseFormat: "mp3",    },  },},},}

    Volcengine

    json5
    {messages: {tts: {  auto: "always",  provider: "volcengine",  providers: {    volcengine: {      apiKey: "${VOLCENGINE_TTS_API_KEY}",      resourceId: "seed-tts-1.0",      voice: "en_female_anna_mars_bigtts",    },  },},},}

    xAI

    json5
    {messages: {tts: {  auto: "always",  provider: "xai",  providers: {    xai: {      apiKey: "${XAI_API_KEY}",      voiceId: "eve",      language: "en",      responseFormat: "mp3",    },  },},},}

    Xiaomi MiMo

    json5
    {messages: {tts: {  auto: "always",  provider: "xiaomi",  providers: {    xiaomi: {      apiKey: "${XIAOMI_API_KEY}",      model: "mimo-v2.5-tts",      voice: "mimo_default",      format: "mp3",    },  },},},}

    每个 agent 的语音覆盖

    当某个 agent 应使用不同的提供商、语音、模型、人设或 Auto-TTS 模式时，使用 agents.list[].tts。agent 块会深度合并到 messages.tts 之上，因此提供商凭据可以保留在全局提供商配置中：

    json5
    {  messages: {    tts: {      auto: "always",      provider: "elevenlabs",      providers: {        elevenlabs: { apiKey: "${ELEVENLABS_API_KEY}", model: "eleven_multilingual_v2" },      },    },  },  agents: {    list: [      {        id: "reader",        tts: {          providers: {            elevenlabs: { voiceId: "EXAVITQu4vr4xnSDxMaL" },          },        },      },    ],  },}

    要固定每个智能体的人设，请在提供商配置旁设置 agents.list[].tts.persona，它只会为该智能体覆盖全局 messages.tts.persona。

    自动回复、/tts audio、/tts status 和 tts 智能体工具的优先级顺序：

    1. messages.tts
    2. 当前 agents.list[].tts
    3. 渠道覆盖，当该渠道支持 channels.<channel>.tts 时
    4. 账号覆盖，当该渠道传入 channels.<channel>.accounts.<id>.tts 时
    5. 此主机的本地 /tts 偏好
    6. 启用模型覆盖时的内联 [[tts:...]] 指令

    渠道和账号覆盖使用与 messages.tts 相同的结构，并会深度合并到前面的层之上，因此共享的提供商凭证可以保留在 messages.tts 中，而某个渠道或机器人账号只更改语音、模型、人设或自动模式：

    json5
    {  messages: {    tts: {      provider: "openai",      providers: {        openai: { apiKey: "${OPENAI_API_KEY}", model: "gpt-4o-mini-tts" },      },    },  },  channels: {    feishu: {      accounts: {        english: {          tts: {            providers: {              openai: { voice: "shimmer" },            },          },        },      },    },  },}

    人设

    人设是一个稳定的语音身份，可以跨提供商以确定性方式应用。它可以偏好某个提供商，定义提供商中立的提示意图，并携带针对语音、模型、提示模板、种子和语音设置的提供商特定绑定。

    最小人设

    json5
    {  messages: {    tts: {      auto: "always",      persona: "narrator",      personas: {        narrator: {          label: "Narrator",          provider: "elevenlabs",          providers: {            elevenlabs: { voiceId: "EXAVITQu4vr4xnSDxMaL", modelId: "eleven_multilingual_v2" },          },        },      },    },  },}

    完整人设（提供商中立提示）

    json5
    {  messages: {    tts: {      auto: "always",      persona: "alfred",      personas: {        alfred: {          label: "Alfred",          description: "Dry, warm British butler narrator.",          provider: "google",          fallbackPolicy: "preserve-persona",          prompt: {            profile: "A brilliant British butler. Dry, witty, warm, charming, emotionally expressive, never generic.",            scene: "A quiet late-night study. Close-mic narration for a trusted operator.",            sampleContext: "The speaker is answering a private technical request with concise confidence and dry warmth.",            style: "Refined, understated, lightly amused.",            accent: "British English.",            pacing: "Measured, with short dramatic pauses.",            constraints: ["Do not read configuration values aloud.", "Do not explain the persona."],          },          providers: {            google: {              model: "gemini-3.1-flash-tts-preview",              voiceName: "Algieba",              promptTemplate: "audio-profile-v1",            },            openai: { model: "gpt-4o-mini-tts", voice: "cedar" },            elevenlabs: {              voiceId: "voice_id",              modelId: "eleven_multilingual_v2",              seed: 42,              voiceSettings: {                stability: 0.65,                similarityBoost: 0.8,                style: 0.25,                useSpeakerBoost: true,                speed: 0.95,              },            },          },        },      },    },  },}

    人设解析

    当前人设会以确定性方式选择：

    1. /tts persona <id> 本地偏好，如果已设置。
    2. messages.tts.persona，如果已设置。
    3. 无人设。

    提供商选择按显式优先执行：

    1. 直接覆盖（CLI、Gateway 网关、Talk、允许的 TTS 指令）。
    2. /tts provider <id> 本地偏好。
    3. 当前人设的 provider。
    4. messages.tts.provider。
    5. 注册表自动选择。

    对于每次提供商尝试，OpenClaw 按以下顺序合并配置：

    1. messages.tts.providers.<id>
    2. messages.tts.personas.<persona>.providers.<id>
    3. 受信任的请求覆盖
    4. 允许的模型发出 TTS 指令覆盖

    提供商如何使用人设提示

    人设提示字段（profile、scene、sampleContext、style、accent、pacing、constraints）是提供商中立的。每个提供商自行决定如何使用它们：

    Google Gemini

    仅当有效的 Google 提供商配置设置了 promptTemplate: "audio-profile-v1" 或 personaPrompt 时，才会将人设提示字段包装进 Gemini TTS 提示结构。较旧的 audioProfile 和 speakerName 字段仍会作为 Google 特定提示文本前置。[[tts:text]] 块内的内联音频标签（例如 [whispers] 或 [laughs]）会保留在 Gemini 转录文本中；OpenClaw 不会生成这些标签。

    OpenAI

    仅当未配置显式 OpenAI instructions 时，才会将人设提示字段映射到请求的 instructions 字段。显式 instructions 始终优先。

    Other providers

    只使用 personas.<id>.providers.<provider> 下的提供商特定人设绑定。除非该提供商实现了自己的角色提示映射，否则会忽略人设提示字段。

    回退策略

    fallbackPolicy 控制当人设对尝试的提供商没有绑定时的行为：

    策略 行为
    preserve-persona 默认。 提供商中立的提示字段保持可用；提供商可以使用或忽略它们。
    provider-defaults 对该次尝试，在提示准备中省略人设；提供商使用其中立默认值，同时继续回退到其他提供商。
    fail 使用 reasonCode: "not_configured" 和 personaBinding: "missing" 跳过该提供商尝试。仍会尝试回退提供商。

    只有当每个尝试的提供商都被跳过或失败时，整个 TTS 请求才会失败。

    Talk 会话的提供商选择限定在会话范围内。Talk 客户端应从 talk.catalog 中选择提供商 ID、模型 ID、语音 ID 和区域设置，并通过 Talk 会话或交接请求传递它们。打开语音会话不应更改 messages.tts 或全局 Talk 提供商默认值。

    模型驱动指令

    默认情况下，助手可以发出 [[tts:...]] 指令，为单次回复覆盖语音、模型或速度，也可以附加一个可选的 [[tts:text]]...[[/tts:text]] 块，用于只应出现在音频中的表现性提示：

    text
    Here you go. [[tts:voiceId=pMsXgVXv3BLzUgSXRplE model=eleven_v3 speed=1.1]][[tts:text]](laughs) Read the song once more.[[/tts:text]]

    当 messages.tts.auto 为 "tagged" 时，必须有指令才会触发音频。流式块投递会在渠道看到文本之前，从可见文本中剥离指令，即使这些指令被拆分在相邻块中也是如此。

    除非 modelOverrides.allowProvider: true，否则会忽略 provider=...。当回复声明 provider=... 时，该指令中的其他键只由该提供商解析；不支持的键会被剥离，并作为 TTS 指令警告报告。

    可用指令键：

    • provider（已注册的提供商 ID；需要 allowProvider: true）
    • voice / voiceName / voice_name / google_voice / voiceId
    • model / google_model
    • stability、similarityBoost、style、speed、useSpeakerBoost
    • vol / volume（MiniMax 音量，0–10）
    • pitch（MiniMax 整数音高，−12 到 12；小数值会被截断）
    • emotion（Volcengine 情绪标签）
    • applyTextNormalization（auto|on|off）
    • languageCode（ISO 639-1）
    • seed

    完全禁用模型覆盖：

    json5
    { messages: { tts: { modelOverrides: { enabled: false } } } }

    允许切换提供商，同时保持其他调节项可配置：

    json5
    { messages: { tts: { modelOverrides: { enabled: true, allowProvider: true, allowSeed: false } } } }

    斜杠命令

    单个命令 /tts。在 Discord 上，OpenClaw 也会注册 /voice，因为 /tts 是 Discord 的内置命令；文本 /tts ... 仍然可用。

    text
    /tts off | on | status/tts chat on | off | default/tts latest/tts provider <id>/tts persona <id> | off/tts limit <chars>/tts summary off/tts audio <text>

    行为说明：

    • /tts on 会将本地 TTS 偏好写为 always；/tts off 会将其写为 off。
    • /tts chat on|off|default 会为当前聊天写入会话范围的自动 TTS 覆盖。
    • /tts persona <id> 会写入本地人设偏好；/tts persona off 会清除它。
    • /tts latest 会从当前会话转录中读取最新的助手回复，并将其作为音频发送一次。它只会在会话条目上存储该回复的哈希，用于抑制重复语音发送。
    • /tts audio 会生成一次性音频回复（不会开启 TTS）。
    • limit 和 summary 存储在本地偏好中，而不是主配置中。
    • /tts status 包含最新尝试的回退诊断信息：Fallback: <primary> -> <used>、Attempts: ...，以及每次尝试的详细信息（provider:outcome(reasonCode) latency）。
    • 启用 TTS 时，/status 会显示当前 TTS 模式以及已配置的提供商、模型、语音和经过清理的自定义端点元数据。

    每用户偏好

    斜杠命令会将本地覆盖写入 prefsPath。默认值为 ~/.openclaw/settings/tts.json；可用 OPENCLAW_TTS_PREFS 环境变量或 messages.tts.prefsPath 覆盖。

    存储字段 效果
    auto 本地自动 TTS 覆盖（always、off，等等）
    provider 本地主提供商覆盖
    persona 本地人设覆盖
    maxLength 摘要阈值（默认 1500 个字符）
    summarize 摘要开关（默认 true）

    这些会覆盖该主机上来自 messages.tts 加当前 agents.list[].tts 块的有效配置。

    输出格式（固定）

    TTS 语音投递由渠道能力驱动。渠道插件会声明语音风格的 TTS 是否应要求提供商生成原生 voice-note 目标，或者保留普通 audio-file 合成，并仅为语音投递标记兼容输出。

    • 支持语音消息的渠道：语音消息回复优先使用 Opus（ElevenLabs 的 opus_48000_64，OpenAI 的 opus）。
      • 48kHz / 64kbps 是语音消息的良好折中选择。
    • Feishu / WhatsApp：当语音消息回复生成为 MP3/WebM/WAV/M4A 或其他可能的音频文件时，渠道插件会在发送原生语音消息前，使用 ffmpeg 将其转码为 48kHz Ogg/Opus。WhatsApp 会通过 Baileys audio 载荷发送结果，并带有 ptt: true 和 audio/ogg; codecs=opus。如果转换失败，Feishu 会收到原始 文件作为附件；WhatsApp 发送会失败，而不是发布不兼容的 PTT 载荷。
    • 其他渠道：MP3（ElevenLabs 的 mp3_44100_128，OpenAI 的 mp3）。
      • 44.1kHz / 128kbps 是语音清晰度的默认平衡点。
    • MiniMax：普通音频附件使用 MP3（speech-2.8-hd 模型，32kHz 采样率）。对于渠道声明的语音消息目标，当渠道声明支持转码时，OpenClaw 会在投递前使用 ffmpeg 将 MiniMax MP3 转码为 48kHz Opus。
    • Xiaomi MiMo：默认使用 MP3，配置后也可使用 WAV。对于渠道声明的语音消息目标，当渠道声明支持转码时，OpenClaw 会在投递前使用 ffmpeg 将 Xiaomi 输出转码为 48kHz Opus。
    • Local CLI：使用配置的 outputFormat。语音消息目标会通过 ffmpeg 转换为 Ogg/Opus，电话输出会转换为原始 16 kHz 单声道 PCM。
    • Google Gemini：Gemini API TTS 返回原始 24kHz PCM。OpenClaw 会将其封装为 WAV 用于音频附件，为语音消息目标转码为 48kHz Opus，并为 Talk/电话直接返回 PCM。
    • Gradium：音频附件使用 WAV，语音消息目标使用 Opus，电话使用 8 kHz 的 ulaw_8000。
    • Inworld：普通音频附件使用 MP3，语音消息目标使用原生 OGG_OPUS，Talk/电话使用 22050 Hz 的原始 PCM。
    • xAI：默认使用 MP3；responseFormat 可以是 mp3、wav、pcm、mulaw 或 alaw。OpenClaw 使用 xAI 的批量 REST TTS 端点，并返回完整的音频附件；此提供商路径不会使用 xAI 的流式 TTS WebSocket。此路径不支持原生 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 重试。

    OpenAI/ElevenLabs 输出格式按渠道固定（见上文）。

    Auto-TTS 行为

    启用 messages.tts.auto 时，OpenClaw：

    • 如果回复已包含媒体或 MEDIA: 指令，则跳过 TTS。
    • 跳过很短的回复（少于 10 个字符）。
    • 当启用摘要时，使用 summaryModel（或 agents.defaults.model.primary）汇总较长回复。
    • 将生成的音频附加到回复。
    • 在 mode: "final" 中，对于流式最终回复，仍会在文本流完成后发送仅音频的 TTS； 生成的媒体会经过与普通回复附件相同的 渠道媒体规范化处理。

    如果回复超过 maxLength 且摘要关闭（或摘要模型没有 API key），则会跳过音频并发送普通文本回复。

    text
    Reply -> TTS enabled?  no  -> send text  yes -> has media / MEDIA: / short?          yes -> send text          no  -> length > limit?                   no  -> TTS -> attach audio                   yes -> summary enabled?                            no  -> send text                            yes -> summarize -> TTS -> attach audio

    按渠道划分的输出格式

    目标 格式
    Feishu / Matrix / Telegram / WhatsApp 语音消息回复优先使用 Opus（ElevenLabs 的 opus_48000_64，OpenAI 的 opus）。48 kHz / 64 kbps 可在清晰度和大小之间取得平衡。
    其他渠道 MP3（ElevenLabs 的 mp3_44100_128，OpenAI 的 mp3）。44.1 kHz / 128 kbps 是语音默认值。
    Talk / 电话 提供商原生 PCM（Inworld 22050 Hz，Google 24 kHz），或电话使用 Gradium 的 ulaw_8000。

    按提供商说明：

    • Feishu / WhatsApp 转码： 当语音消息回复落地为 MP3/WebM/WAV/M4A 时，渠道插件会使用 ffmpeg 转码为 48 kHz Ogg/Opus。WhatsApp 会通过 Baileys 发送，并带有 ptt: true 和 audio/ogg; codecs=opus。如果转换失败：Feishu 会回退为附加原始文件；WhatsApp 发送会失败，而不是发布不兼容的 PTT 载荷。
    • MiniMax / Xiaomi MiMo： 默认 MP3（MiniMax speech-2.8-hd 为 32 kHz）；语音消息目标会通过 ffmpeg 转码为 48 kHz Opus。
    • Local CLI： 使用配置的 outputFormat。语音消息目标会转换为 Ogg/Opus，电话输出会转换为原始 16 kHz 单声道 PCM。
    • Google Gemini： 返回原始 24 kHz PCM。OpenClaw 会将其封装为 WAV 用于附件，为语音消息目标转码为 48 kHz Opus，并为 Talk/电话直接返回 PCM。
    • Inworld： MP3 附件、原生 OGG_OPUS 语音消息、Talk/电话使用 22050 Hz 原始 PCM。
    • xAI： 默认使用 MP3；responseFormat 可以是 mp3|wav|pcm|mulaw|alaw。使用 xAI 的批量 REST 端点——不会使用流式 WebSocket TTS。不支持原生 Opus 语音消息格式。
    • Microsoft： 使用 microsoft.outputFormat（默认 audio-24khz-48kbitrate-mono-mp3）。Telegram sendVoice 接受 OGG/MP3/M4A；如果你需要保证使用 Opus 语音消息，请使用 OpenAI/ElevenLabs。如果配置的 Microsoft 格式失败，OpenClaw 会使用 MP3 重试。

    OpenAI 和 ElevenLabs 输出格式按上方列出的渠道固定。

    字段参考

    Top-level messages.tts.*
    auto"off" | "always" | "inbound" | "tagged"

    Auto-TTS 模式。inbound 仅在入站语音消息后发送音频；tagged 仅在回复包含 [[tts:...]] 指令或 [[tts:text]] 块时发送音频。

    enabledboolean

    旧版开关。openclaw doctor --fix 会将其迁移到 auto。

    mode"final" | "all"default: final

    "all" 除最终回复外，还包含工具/块回复。

    providerstring

    语音提供商 ID。未设置时，OpenClaw 会按注册表自动选择顺序使用第一个已配置的提供商。旧版 provider: "edge" 会由 openclaw doctor --fix 重写为 "microsoft"。

    personastring

    来自 personas 的活跃 persona ID。会规范化为小写。

    OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9InBlcnNvbmFzLjxpZA " type="object"> 稳定的语音身份。字段：label、description、provider、fallbackPolicy、prompt、providers.<provider>。请参阅 Personas。

    summaryModelstring

    用于自动摘要的低成本模型；默认为 agents.defaults.model.primary。接受 provider/model 或已配置的模型别名。

    modelOverridesobject

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

    OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9InByb3ZpZGVycy48aWQ " type="object"> 由提供商拥有的设置，按语音提供商 ID 键控。旧版直接块（messages.tts.openai、.elevenlabs、.microsoft、.edge）会由 openclaw doctor --fix 重写；只提交 messages.tts.providers.<id>。

    maxTextLengthnumber

    TTS 输入字符的硬性上限。超过时 /tts audio 会失败。

    timeoutMsnumber

    请求超时，单位为毫秒。

    prefsPathstring

    覆盖本地偏好 JSON 路径（provider/limit/summary）。默认 ~/.openclaw/settings/tts.json。

    Azure Speech

    OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9ImFwaUtleSIgdHlwZT0ic3RyaW5nIg 环境变量：AZURE_SPEECH_KEY、AZURE_SPEECH_API_KEY 或 SPEECH_KEY。 OPENCLAW_DOCS_MARKER:paramClose:

    OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9InJlZ2lvbiIgdHlwZT0ic3RyaW5nIg Azure Speech 区域（例如 eastus）。环境变量：AZURE_SPEECH_REGION 或 SPEECH_REGION。 OPENCLAW_DOCS_MARKER:paramClose:

    OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9ImVuZHBvaW50IiB0eXBlPSJzdHJpbmci 可选的 Azure Speech 端点覆盖（别名 baseUrl）。 OPENCLAW_DOCS_MARKER:paramClose:

    OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9InZvaWNlIiB0eXBlPSJzdHJpbmci Azure 语音 ShortName。默认 en-US-JennyNeural。 OPENCLAW_DOCS_MARKER:paramClose:

    OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9ImxhbmciIHR5cGU9InN0cmluZyI SSML 语言代码。默认 en-US。 OPENCLAW_DOCS_MARKER:paramClose:

    OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Im91dHB1dEZvcm1hdCIgdHlwZT0ic3RyaW5nIg 标准音频的 Azure X-Microsoft-OutputFormat。默认 audio-24khz-48kbitrate-mono-mp3。 OPENCLAW_DOCS_MARKER:paramClose:

    OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9InZvaWNlTm90ZU91dHB1dEZvcm1hdCIgdHlwZT0ic3RyaW5nIg 语音消息输出的 Azure X-Microsoft-OutputFormat。默认 ogg-24khz-16bit-mono-opus。 OPENCLAW_DOCS_MARKER:paramClose:

    ElevenLabs

    OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9ImFwaUtleSIgdHlwZT0ic3RyaW5nIg 回退到 ELEVENLABS_API_KEY 或 XI_API_KEY。 OPENCLAW_DOCS_MARKER:paramClose:

    OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Im1vZGVsIiB0eXBlPSJzdHJpbmci 模型 ID（例如 eleven_multilingual_v2、eleven_v3）。 OPENCLAW_DOCS_MARKER:paramClose:

    voiceIdstring
    voiceSettingsobject

    stability、similarityBoost、style（各为 0..1）、useSpeakerBoost（true|false）、speed（0.5..2.0，1.0 = 正常）。

    applyTextNormalization"auto" | "on" | "off"

    OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Imxhbmd1YWdlQ29kZSIgdHlwZT0ic3RyaW5nIg 2 字母 ISO 639-1（例如 en、de）。 OPENCLAW_DOCS_MARKER:paramClose:

    OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9InNlZWQiIHR5cGU9Im51bWJlciI 整数 0..4294967295，用于尽力实现确定性。 OPENCLAW_DOCS_MARKER:paramClose:

    baseUrlstring
    Google Gemini

    OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9ImFwaUtleSIgdHlwZT0ic3RyaW5nIg 回退到 GEMINI_API_KEY / GOOGLE_API_KEY。如果省略，TTS 可以在回退到环境变量前复用 models.providers.google.apiKey。 OPENCLAW_DOCS_MARKER:paramClose:

    OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Im1vZGVsIiB0eXBlPSJzdHJpbmci Gemini TTS 模型。默认 gemini-3.1-flash-tts-preview。 OPENCLAW_DOCS_MARKER:paramClose:

    OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9InZvaWNlTmFtZSIgdHlwZT0ic3RyaW5nIg Gemini 预置语音名称。默认 Kore。别名：voice。 OPENCLAW_DOCS_MARKER:paramClose:

    audioProfilestring
    speakerNamestring

    OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9InByb21wdFRlbXBsYXRlIiB0eXBlPSciYXVkaW8tcHJvZmlsZS12MSIn 设置为 audio-profile-v1，以将活跃 persona 提示词字段包装在确定性的 Gemini TTS 提示词结构中。 OPENCLAW_DOCS_MARKER:paramClose:

    personaPromptstring

    OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9ImJhc2VVcmwiIHR5cGU9InN0cmluZyI 仅接受 https://generativelanguage.googleapis.com。 OPENCLAW_DOCS_MARKER:paramClose:

    Gradium

    OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9ImFwaUtleSIgdHlwZT0ic3RyaW5nIg 环境变量：GRADIUM_API_KEY。 OPENCLAW_DOCS_MARKER:paramClose:

    OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9ImJhc2VVcmwiIHR5cGU9InN0cmluZyI 默认值为 https://api.gradium.ai。 OPENCLAW_DOCS_MARKER:paramClose:

    OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9InZvaWNlSWQiIHR5cGU9InN0cmluZyI 默认值为 Emma（YTpq7expH9539ERJ）。 OPENCLAW_DOCS_MARKER:paramClose:

    Inworld

    Inworld 主配置

    OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9ImFwaUtleSIgdHlwZT0ic3RyaW5nIg 环境变量：INWORLD_API_KEY。 OPENCLAW_DOCS_MARKER:paramClose:

    OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9ImJhc2VVcmwiIHR5cGU9InN0cmluZyI 默认值为 https://api.inworld.ai。 OPENCLAW_DOCS_MARKER:paramClose:

    OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Im1vZGVsSWQiIHR5cGU9InN0cmluZyI 默认值为 inworld-tts-1.5-max。另有：inworld-tts-1.5-mini、inworld-tts-1-max、inworld-tts-1。 OPENCLAW_DOCS_MARKER:paramClose:

    OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9InZvaWNlSWQiIHR5cGU9InN0cmluZyI 默认值为 Sarah。 OPENCLAW_DOCS_MARKER:paramClose:

    OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9InRlbXBlcmF0dXJlIiB0eXBlPSJudW1iZXIi 采样温度 0..2。 OPENCLAW_DOCS_MARKER:paramClose:

    Local CLI (tts-local-cli)
    commandstring

    OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9ImFyZ3MiIHR5cGU9InN0cmluZ1tdIg 命令参数。支持 {{Text}}、{{OutputPath}}、{{OutputDir}}、{{OutputBase}} 占位符。 OPENCLAW_DOCS_MARKER:paramClose:

    OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Im91dHB1dEZvcm1hdCIgdHlwZT0nIm1wMyIgfCAib3B1cyIgfCAid2F2Iic 预期 CLI 输出格式。音频附件的默认值为 mp3。 OPENCLAW_DOCS_MARKER:paramClose:

    OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9InRpbWVvdXRNcyIgdHlwZT0ibnVtYmVyIg 命令超时时间，单位为毫秒。默认值为 120000。 OPENCLAW_DOCS_MARKER:paramClose:

    cwdstring
    env"Record<string,
    Microsoft (no API key)
    enabledbooleandefault: true

    OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9InZvaWNlIiB0eXBlPSJzdHJpbmci Microsoft 神经语音名称（例如 en-US-MichelleNeural）。 OPENCLAW_DOCS_MARKER:paramClose:

    OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9ImxhbmciIHR5cGU9InN0cmluZyI 语言代码（例如 en-US）。 OPENCLAW_DOCS_MARKER:paramClose:

    OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Im91dHB1dEZvcm1hdCIgdHlwZT0ic3RyaW5nIg Microsoft 输出格式。默认值为 audio-24khz-48kbitrate-mono-mp3。内置的 Edge 支持传输并不支持所有格式。 OPENCLAW_DOCS_MARKER:paramClose:

    OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9InJhdGUgLyBwaXRjaCAvIHZvbHVtZSIgdHlwZT0ic3RyaW5nIg 百分比字符串（例如 +10%、-5%）。 OPENCLAW_DOCS_MARKER:paramClose:

    saveSubtitlesboolean
    proxystring
    timeoutMsnumber

    OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9ImVkZ2UuKiIgdHlwZT0ib2JqZWN0IiBkZXByZWNhdGVk 旧版别名。运行 openclaw doctor --fix 将持久化配置重写为 providers.microsoft。 OPENCLAW_DOCS_MARKER:paramClose:

    MiniMax

    OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9ImFwaUtleSIgdHlwZT0ic3RyaW5nIg 回退到 MINIMAX_API_KEY。Token Plan 通过 MINIMAX_OAUTH_TOKEN、MINIMAX_CODE_PLAN_KEY 或 MINIMAX_CODING_API_KEY 进行认证。 OPENCLAW_DOCS_MARKER:paramClose:

    OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9ImJhc2VVcmwiIHR5cGU9InN0cmluZyI 默认值为 https://api.minimax.io。环境变量：MINIMAX_API_HOST。 OPENCLAW_DOCS_MARKER:paramClose:

    OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Im1vZGVsIiB0eXBlPSJzdHJpbmci 默认值为 speech-2.8-hd。环境变量：MINIMAX_TTS_MODEL。 OPENCLAW_DOCS_MARKER:paramClose:

    OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9InZvaWNlSWQiIHR5cGU9InN0cmluZyI 默认值为 English_expressive_narrator。环境变量：MINIMAX_TTS_VOICE_ID。 OPENCLAW_DOCS_MARKER:paramClose:

    OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9InNwZWVkIiB0eXBlPSJudW1iZXIi 0.5..2.0。默认值为 1.0。 OPENCLAW_DOCS_MARKER:paramClose:

    OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9InZvbCIgdHlwZT0ibnVtYmVyIg (0, 10]。默认值为 1.0。 OPENCLAW_DOCS_MARKER:paramClose:

    OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9InBpdGNoIiB0eXBlPSJudW1iZXIi 整数 -12..12。默认值为 0。请求前会截断小数值。 OPENCLAW_DOCS_MARKER:paramClose:

    OpenAI

    OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9ImFwaUtleSIgdHlwZT0ic3RyaW5nIg 回退到 OPENAI_API_KEY。 OPENCLAW_DOCS_MARKER:paramClose:

    OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Im1vZGVsIiB0eXBlPSJzdHJpbmci OpenAI TTS 模型 ID（例如 gpt-4o-mini-tts）。 OPENCLAW_DOCS_MARKER:paramClose:

    OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9InZvaWNlIiB0eXBlPSJzdHJpbmci 语音名称（例如 alloy、cedar）。 OPENCLAW_DOCS_MARKER:paramClose:

    OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Imluc3RydWN0aW9ucyIgdHlwZT0ic3RyaW5nIg 显式 OpenAI instructions 字段。设置后，persona 提示字段不会自动映射。 OPENCLAW_DOCS_MARKER:paramClose:

    OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9ImV4dHJhQm9keSAvIGV4dHJhX2JvZHkiIHR5cGU9IlJlY29yZDxzdHJpbmcsIHVua25vd24 ">在生成的 OpenAI TTS 字段之后合并到 /audio/speech 请求正文中的额外 JSON 字段。用于 Kokoro 等 OpenAI 兼容端点，这些端点需要 lang 等提供商特定键；不安全的原型键会被忽略。 OPENCLAW_DOCS_MARKER:paramClose:

    baseUrlstring

    覆盖 OpenAI TTS 端点。解析顺序：配置 → OPENAI_TTS_BASE_URL → https://api.openai.com/v1。非默认值会被视为 OpenAI 兼容的 TTS 端点，因此会接受自定义模型和语音名称。

    OpenRouter

    OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9ImFwaUtleSIgdHlwZT0ic3RyaW5nIg 环境变量：OPENROUTER_API_KEY。可复用 models.providers.openrouter.apiKey。 OPENCLAW_DOCS_MARKER:paramClose:

    OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9ImJhc2VVcmwiIHR5cGU9InN0cmluZyI 默认值为 https://openrouter.ai/api/v1。旧版 https://openrouter.ai/v1 会被规范化。 OPENCLAW_DOCS_MARKER:paramClose:

    OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Im1vZGVsIiB0eXBlPSJzdHJpbmci 默认值为 hexgrad/kokoro-82m。别名：modelId。 OPENCLAW_DOCS_MARKER:paramClose:

    OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9InZvaWNlIiB0eXBlPSJzdHJpbmci 默认值为 af_alloy。别名：voiceId。 OPENCLAW_DOCS_MARKER:paramClose:

    OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9InJlc3BvbnNlRm9ybWF0IiB0eXBlPScibXAzIiB8ICJwY20iJw 默认值为 mp3。 OPENCLAW_DOCS_MARKER:paramClose:

    speednumber
    Volcengine (BytePlus Seed Speech)

    OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9ImFwaUtleSIgdHlwZT0ic3RyaW5nIg 环境变量：VOLCENGINE_TTS_API_KEY 或 BYTEPLUS_SEED_SPEECH_API_KEY。 OPENCLAW_DOCS_MARKER:paramClose:

    OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9InJlc291cmNlSWQiIHR5cGU9InN0cmluZyI 默认值为 seed-tts-1.0。环境变量：VOLCENGINE_TTS_RESOURCE_ID。当你的项目拥有 TTS 2.0 权益时使用 seed-tts-2.0。 OPENCLAW_DOCS_MARKER:paramClose:

    OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9ImFwcEtleSIgdHlwZT0ic3RyaW5nIg 应用密钥请求头。默认值为 aGjiRDfUWi。环境变量：VOLCENGINE_TTS_APP_KEY。 OPENCLAW_DOCS_MARKER:paramClose:

    OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9ImJhc2VVcmwiIHR5cGU9InN0cmluZyI 覆盖 Seed Speech TTS HTTP 端点。环境变量：VOLCENGINE_TTS_BASE_URL。 OPENCLAW_DOCS_MARKER:paramClose:

    OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9InZvaWNlIiB0eXBlPSJzdHJpbmci 语音类型。默认值为 en_female_anna_mars_bigtts。环境变量：VOLCENGINE_TTS_VOICE。 OPENCLAW_DOCS_MARKER:paramClose:

    speedRationumber
    emotionstring

    OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9ImFwcElkIC8gdG9rZW4gLyBjbHVzdGVyIiB0eXBlPSJzdHJpbmciIGRlcHJlY2F0ZWQ 旧版 Volcengine Speech Console 字段。环境变量：VOLCENGINE_TTS_APPID、VOLCENGINE_TTS_TOKEN、VOLCENGINE_TTS_CLUSTER（默认值为 volcano_tts）。 OPENCLAW_DOCS_MARKER:paramClose:

    xAI

    OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9ImFwaUtleSIgdHlwZT0ic3RyaW5nIg 环境变量：XAI_API_KEY。 OPENCLAW_DOCS_MARKER:paramClose:

    OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9ImJhc2VVcmwiIHR5cGU9InN0cmluZyI 默认值为 https://api.x.ai/v1。环境变量：XAI_BASE_URL。 OPENCLAW_DOCS_MARKER:paramClose:

    OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9InZvaWNlSWQiIHR5cGU9InN0cmluZyI 默认值为 eve。实时语音：ara、eve、leo、rex、sal、una。 OPENCLAW_DOCS_MARKER:paramClose:

    OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Imxhbmd1YWdlIiB0eXBlPSJzdHJpbmci BCP-47 语言代码或 auto。默认值为 en。 OPENCLAW_DOCS_MARKER:paramClose:

    OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9InJlc3BvbnNlRm9ybWF0IiB0eXBlPScibXAzIiB8ICJ3YXYiIHwgInBjbSIgfCAibXVsYXciIHwgImFsYXciJw 默认值为 mp3。 OPENCLAW_DOCS_MARKER:paramClose:

    speednumber
    Xiaomi MiMo

    OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9ImFwaUtleSIgdHlwZT0ic3RyaW5nIg 环境变量：XIAOMI_API_KEY。 OPENCLAW_DOCS_MARKER:paramClose:

    OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9ImJhc2VVcmwiIHR5cGU9InN0cmluZyI 默认值为 https://api.xiaomimimo.com/v1。环境变量：XIAOMI_BASE_URL。 OPENCLAW_DOCS_MARKER:paramClose:

    OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Im1vZGVsIiB0eXBlPSJzdHJpbmci 默认值为 mimo-v2.5-tts。环境变量：XIAOMI_TTS_MODEL。还支持 mimo-v2-tts。 OPENCLAW_DOCS_MARKER:paramClose:

    OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9InZvaWNlIiB0eXBlPSJzdHJpbmci 默认值为 mimo_default。环境变量：XIAOMI_TTS_VOICE。 OPENCLAW_DOCS_MARKER:paramClose:

    OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9ImZvcm1hdCIgdHlwZT0nIm1wMyIgfCAid2F2Iic 默认值为 mp3。环境变量：XIAOMI_TTS_FORMAT。 OPENCLAW_DOCS_MARKER:paramClose:

    stylestring

    Agent 工具

    tts 工具会将文本转换为语音，并返回用于回复投递的音频附件。在 Feishu、Matrix、Telegram 和 WhatsApp 上，音频会作为语音消息而不是文件附件投递。Feishu 和 WhatsApp 在 ffmpeg 可用时，可以在此路径上转码非 Opus TTS 输出。

    WhatsApp 会通过 Baileys 将音频作为 PTT 语音便签（带有 ptt: true 的 audio）发送，并且会将可见文本与 PTT 音频分开发送，因为客户端不会一致地在语音便签上渲染字幕。

    该工具接受可选的 channel 和 timeoutMs 字段；timeoutMs 是每次调用的提供商请求超时时间，单位为毫秒。

    Gateway RPC

    方法 用途
    tts.status 读取当前 TTS 状态和上次尝试。
    tts.enable 将本地自动偏好设置为 always。
    tts.disable 将本地自动偏好设置为 off。
    tts.convert 一次性文本 → 音频。
    tts.setProvider 设置本地提供商偏好。
    tts.setPersona 设置本地 persona 偏好。
    tts.providers 列出已配置的提供商和状态。

    服务链接

    相关

    Was this useful?