文本转语音

OpenClaw 通过 14 个语音提供商将出站回复转换为音频： 在 Feishu、Matrix、Telegram 和 WhatsApp 上使用原生语音消息；在其他所有渠道使用音频 附件；并为电话和 Talk 提供 PCM/Ulaw 流。

TTS 是 Talk 的 stt-tts 模式中的语音输出部分（talk.speak 调用相同的 合成路径）。提供商原生的 realtime Talk 会话改为在实时提供商内部 合成语音；transcription 会话从不 合成助手语音回复。

快速开始

选择提供商

OpenAI 和 ElevenLabs 是最可靠的托管选项。Microsoft 和 Local CLI 无需 API key 即可工作。完整列表请参阅提供商矩阵。

设置 API key

导出你的提供商所需的环境变量（例如 OPENAI_API_KEY、 ELEVENLABS_API_KEY）。Microsoft 和 Local CLI 无需 API key。

在配置中启用

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

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

在聊天中试用

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

支持的提供商

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

配置

TTS 配置位于 ~/.openclaw/openclaw.json 中的 tts 下。选择一个 预设并调整提供商配置块。下方显示的 speakerVoice/speakerVoiceId 字段是规范字段；每个提供商自己的 voice/voiceId/ voiceName 字段名仍可作为旧版别名使用。

Azure Speech

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

ElevenLabs

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

Google Gemini

{
  tts: {
    auto: "always",
    provider: "google",
    providers: {
      google: {
        apiKey: "${GEMINI_API_KEY}",
        model: "gemini-3.1-flash-tts-preview",
        speakerVoice: "Kore",
        // 可选的自然语言风格提示：
        // audioProfile: "以平静的播客主持人口吻说话。",
        // speakerName: "Alex",
      },
    },
  },
}

Gradium

{
  tts: {
    auto: "always",
    provider: "gradium",
    providers: {
      gradium: {
        apiKey: "${GRADIUM_API_KEY}",
        speakerVoiceId: "YTpq7expH9539ERJ",
      },
    },
  },
}

Inworld

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

Local CLI

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

Microsoft（无需 API key）

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

MiniMax

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

OpenAI + ElevenLabs

{
  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",
        speakerVoice: "alloy",
      },
      elevenlabs: {
        apiKey: "${ELEVENLABS_API_KEY}",
        model: "eleven_multilingual_v2",
        speakerVoiceId: "EXAVITQu4vr4xnSDxMaL",
        voiceSettings: { stability: 0.5, similarityBoost: 0.75, style: 0.0, useSpeakerBoost: true, speed: 1.0 },
        applyTextNormalization: "auto",
        languageCode: "en",
      },
    },
  },
}

OpenRouter

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

Volcengine

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

xAI

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

Xiaomi MiMo

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

对于 Xiaomi mimo-v2.5-tts-voicedesign，请省略 speakerVoice，并将 style 设置为 语音设计提示。OpenClaw 会将该提示作为 TTS 的 user 消息发送， 并且不会为 voicedesign 模型发送 audio.voice。

每个 Agent 的语音覆盖配置

当某个 Agent 应使用不同的提供商、语音、模型、角色设定或自动 TTS 模式时， 请使用 agents.entries.*.tts。Agent 配置块会深度合并并覆盖 tts，因此提供商凭据可以保留在全局提供商配置中：

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

要为每个智能体固定一个 persona，请将 agents.entries.*.tts.persona 与提供商配置一同设置——它仅为该智能体覆盖全局 tts.persona。

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

1. tts
2. 活动的 agents.entries.*.tts
3. 渠道覆盖（当渠道支持 channels.<channel>.tts 时）
4. 账号覆盖（当渠道传递 channels.<channel>.accounts.<id>.tts 时）
5. 此主机的本地 /tts 偏好设置
6. 启用模型驱动指令时的内联 [[tts:...]] 指令

渠道和账号覆盖使用与 tts 相同的结构，并在之前的层级之上进行深度合并，因此共享的提供商凭据可以保留在 tts 中，而渠道或 Bot 账号只需更改说话声音、模型、persona 或自动模式：

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

Persona

Persona 是一种稳定的语音身份，可以确定性地应用于不同提供商。 它可以首选某个提供商、定义与提供商无关的提示意图，并携带声音、模型、提示模板、种子和声音设置等提供商专属绑定。

最小 persona

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

完整 persona（提供商专属塑形）

{
  tts: {
    auto: "always",
    persona: "alfred",
    personas: {
      alfred: {
        label: "Alfred",
        description: "Dry, warm British butler narrator.",
        provider: "google",
        fallbackPolicy: "preserve-persona",
        providers: {
          google: {
            model: "gemini-3.1-flash-tts-preview",
            speakerVoice: "Algieba",
            promptTemplate: "audio-profile-v1",
          },
          openai: { model: "gpt-4o-mini-tts", speakerVoice: "cedar" },
          elevenlabs: {
            speakerVoiceId: "voice_id",
            modelId: "eleven_multilingual_v2",
            seed: 42,
            voiceSettings: {
              stability: 0.65,
              similarityBoost: 0.8,
              style: 0.25,
              useSpeakerBoost: true,
              speed: 0.95,
            },
          },
        },
      },
    },
  },
}

Persona 解析

活动 persona 按以下确定性顺序选择：

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

提供商选择遵循显式设置优先：

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

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

1. tts.providers.<id>
2. tts.personas.<persona>.providers.<id>
3. 可信请求覆盖
4. 允许的模型生成 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:speakerVoiceId=pMsXgVXv3BLzUgSXRplE model=eleven_v3 speed=1.1]]
[[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_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

完全禁用模型覆盖：

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

允许切换提供商，同时保持其他参数可配置：

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

斜杠命令

单个命令 /tts。在 Discord 上，OpenClaw 还会注册 /voice，因为 /tts 是 Discord 内置命令——文本 /tts ... 仍然有效。

/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> 写入本地 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 通过 Baileys audio 载荷发送结果，并设置 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 区域设置）。

OpenAI 和 ElevenLabs 的输出格式按上述列表针对各渠道固定。

自动 TTS 行为

启用 tts.auto 后，OpenClaw 会：

• 如果回复已包含结构化媒体，则跳过 TTS。
• 跳过非常短的回复（少于 10 个字符）。
• 启用摘要时，使用 summaryModel（或 agents.defaults.model.primary）概括较长的回复。
• 将生成的音频附加到回复中。
• 在 mode: "final" 中，文本流完成后，仍会为流式最终回复发送纯音频 TTS； 生成的媒体会像普通回复附件一样经过相同的 渠道媒体标准化处理。

如果回复超过 maxLength，OpenClaw 绝不会直接跳过音频：

• 启用摘要（默认）且摘要模型可用：将文本概括为大约 maxLength 个字符，然后合成摘要。
• 关闭摘要、摘要生成失败，或摘要模型没有可用的 API key： 将文本截断为 maxLength 个字符，然后合成 截断后的文本。

回复 -> 已启用 TTS？
  否  -> 发送文本
  是 -> 包含媒体 / 过短？
          是 -> 发送文本
          否  -> 长度 > 限制？
                   否  -> TTS -> 附加音频
                   是 -> 摘要已启用且可用？
                            否  -> 截断 -> TTS -> 附加音频
                            是 -> 生成摘要 -> TTS -> 附加音频

字段参考

提供商的 apiKey 字段可以是原始字符串或 SecretRef。在 Gateway 网关 冷启动期间，不可用的 TTS SecretRef 会将内置 TTS 能力标记为 “已配置但不可用”，而不会阻止 Gateway 网关启动。随后，tts.speak 返回 UNAVAILABLE，原因为 SECRET_SURFACE_UNAVAILABLE，并且不会 发送提供商请求。状态和 Doctor 会列出降级的 TTS 所有者及其配置路径。显式 引用会保留在运行时快照中，因此环境或配置文件中的 凭据无法静默选择其他账户。重新加载和配置写入 预检会应用可感知所有者的降级策略：未更改且符合条件的 TTS 所有者可以继续使用其最后已知有效的凭据作为过期凭据，而新的或已更改的 故障会转为冷状态，且不会阻止正常的所有者。结构无效的引用 和解析后的值仍会导致启动失败或更新被拒绝。

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 文本转语音

相关内容

• 媒体概览
• 音乐生成
• 视频生成
• 斜杠命令
• 语音通话插件