文本转语音

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

TTS 是 Talk 的 stt-tts 模式中负责语音输出的一半。提供商原生的 realtime Talk 会话会在 realtime 提供商内部合成语音， 而不是调用这条 TTS 路径；transcription 会话则不会合成 助手语音响应。

# 快速开始

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

# 支持的提供商

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

# 配置

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

{
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",
    },
  },
},
},
}

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

{
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",
    },
  },
},
},
}

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

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

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

{
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%",
    },
  },
},
},
}

{
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,
    },
  },
},
},
}

{
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",
    },
  },
},
},
}

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

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

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

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

# 按 agent 覆盖语音

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

{
  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 中，而某个渠道或机器人账号只更改语音、模型、角色设定或自动模式：

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

# 角色设定

角色设定是一种稳定的语音身份，可以跨提供商确定性地应用。它可以偏好某个提供商，定义提供商中立的提示意图，并携带面向语音、模型、提示模板、种子和语音设置的提供商专属绑定。

# 最小角色设定

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

# 完整角色设定（提供商中立提示）

{
  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）是提供商中立的。每个提供商决定如何使用它们：

# 回退策略

当某个角色设定对尝试的提供商没有绑定时，fallbackPolicy 控制行为：

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

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

# 模型驱动指令

默认情况下，助手可以发出 [[tts:...]] 指令，为单次回复覆盖语音、模型或速度，还可以附加可选的 [[tts:text]]...[[/tts: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

完全禁用模型覆盖：

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

# 每用户偏好设置

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

这些会覆盖来自 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 负载。
• BlueBubbles：让提供商合成继续走普通音频文件路径；MP3 和 CAF 输出会标记用于 iMessage 语音备忘录投递。
• 其他渠道：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，再投递。
• 本地 CLI：使用已配置的 outputFormat。语音消息目标会 转换为 Ogg/Opus，电话音频输出会用 ffmpeg 转换为原始 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），则会跳过音频并发送普通文本回复。

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 / 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。
• 本地 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 输出格式按上面列出的渠道固定。

# 字段参考

# 智能体工具

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

WhatsApp 通过 Baileys 将音频作为 PTT 语音消息（带有 ptt: true 的 audio）发送，并将可见文本与 PTT 音频分开发送，因为客户端并不总是在语音消息上渲染说明文字。

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

# 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
• Xiaomi MiMo 语音合成
• node-edge-tts
• Microsoft Speech 输出格式
• xAI 文本转语音

# 相关内容

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