OpenClaw TTS（文字转语音）默认关闭，通过 messages.tts.auto: "always" 或 /tts always 即可开启。Microsoft Edge TTS 无需 API Key，其他提供商需配置对应密钥。支持 [[tts:voiceId=...]] 模型驱动覆盖单次回复，长文本自动摘要可开关。输出格式按频道固定：Telegram、WhatsApp 等为 Opus 语音消息，其余为 MP3。配置项完整，包含备用切换和 /tts status 诊断。

OpenClaw TTS 配置与启用完整指南

OpenClaw 支持将出站回复自动转为语音（TTS），在 Telegram、WhatsApp、飞书等渠道以音频形式发送。本页涵盖快速启用、所有提供商配置、模型覆盖、输出格式、Slash 命令和常见问题。

5 分钟快速开启

最快方式：用 Microsoft Edge TTS（无需 API Key），在 openclaw.json 中加入以下配置：

json5

{
  messages: {
    tts: {
      auto: "always",
      provider: "microsoft",
      providers: {
        microsoft: {
          voice: "zh-CN-XiaoxiaoNeural",
          lang: "zh-CN",
        },
      },
    },
  },
}

保存后重启网关，每条回复自动附带语音。运行 /tts off 关闭。

v0.9+ 配置说明：旧版使用 provider: "edge" 配置 Microsoft 语音，新版统一为 provider: "microsoft"。旧配置仍可用（自动规范化），推荐更新。

支持的服务

ElevenLabs（主或备用）
Microsoft（主或备用；通过 node-edge-tts 使用 Edge 在线 TTS，无需 API Key）
MiniMax（主或备用；T2A v2 API）
OpenAI（主或备用；也用于摘要）

Microsoft 语音注意事项

当前捆绑的 Microsoft 提供商通过 node-edge-tts 库调用 Microsoft Edge 的在线神经 TTS 服务。这是一个托管服务，不需要 API Key，但无公开 SLA 或配额限制，请视为尽力而为。若需要有保证的限制，使用 OpenAI 或 ElevenLabs。

所需密钥

使用 OpenAI、ElevenLabs 或 MiniMax 需配置对应 API Key：

ELEVENLABS_API_KEY（或 XI_API_KEY）
MINIMAX_API_KEY
OPENAI_API_KEY

Microsoft 语音不需要。

若启用自动摘要，摘要模型使用 summaryModel（默认 agents.defaults.model.primary），该提供商也必须通过认证。

服务链接

默认是否启用？

否。Auto-TTS 默认关闭。通过 messages.tts.auto 或会话命令 /tts always（别名 /tts on）启用。若未设置 messages.tts.provider，OpenClaw 按注册表选择第一个已配置的语音提供商。

配置详解

TTS 配置位于 openclaw.json 的 messages.tts 下。完整 schema 见网关配置。

最小配置（仅启用 + 提供商）

json5

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

OpenAI 主提供商 + ElevenLabs 备用

json5

{
  messages: {
    tts: {
      auto: "always",
      provider: "openai",
      summaryModel: "openai/gpt-4.1-mini",
      modelOverrides: {
        enabled: true,
      },
      providers: {
        openai: {
          apiKey: "openai_api_key",
          baseUrl: "https://api.openai.com/v1",
          model: "gpt-4o-mini-tts",
          voice: "alloy",
        },
        elevenlabs: {
          apiKey: "elevenlabs_api_key",
          baseUrl: "https://api.elevenlabs.io",
          voiceId: "voice_id",
          modelId: "eleven_multilingual_v2",
          seed: 42,
          applyTextNormalization: "auto",
          languageCode: "en",
          voiceSettings: {
            stability: 0.5,
            similarityBoost: 0.75,
            style: 0.0,
            useSpeakerBoost: true,
            speed: 1.0,
          },
        },
      },
    },
  },
}

Microsoft 主提供商（无 API Key）

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: "+10%",
          pitch: "-5%",
        },
      },
    },
  },
}

MiniMax 主提供商

json5

{
  messages: {
    tts: {
      auto: "always",
      provider: "minimax",
      providers: {
        minimax: {
          apiKey: "minimax_api_key",
          baseUrl: "https://api.minimax.io",
          model: "speech-2.8-hd",
          voiceId: "English_expressive_narrator",
          speed: 1.0,
          vol: 1.0,
          pitch: 0,
        },
      },
    },
  },
}

禁用 Microsoft 语音

json5

{
  messages: {
    tts: {
      providers: {
        microsoft: {
          enabled: false,
        },
      },
    },
  },
}

自定义限制与偏好路径

json5

{
  messages: {
    tts: {
      auto: "always",
      maxTextLength: 4000,
      timeoutMs: 30000,
      prefsPath: "~/.openclaw/settings/tts.json",
    },
  },
}

仅在收到语音消息后回复音频

json5

{
  messages: {
    tts: {
      auto: "inbound",
    },
  },
}

禁用长回复的自动摘要

json5

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

然后运行：

/tts summary off

字段说明

auto：Auto-TTS 模式（off、always、inbound、tagged）。
- inbound 仅在收到入站语音消息后发送音频。
- tagged 仅在回复包含 [[tts]] 标签时发送音频。
enabled：旧版开关（doctor 会将其迁移到 auto）。
mode："final"（默认）或 "all"（包含工具/块回复）。
provider：语音提供商 ID，如 "elevenlabs"、"microsoft"、"minimax" 或 "openai"（备用自动）。
若 provider 未设置，OpenClaw 按注册表自动选择顺序使用第一个已配置的语音提供商。
旧版 provider: "edge" 仍有效，规范化为 microsoft。
summaryModel：Auto-摘要的可选低廉模型；默认为 agents.defaults.model.primary。接受 provider/model 或已配置的模型别名。
modelOverrides：允许模型发出 TTS 指令（默认开启）。allowProvider 默认为 false（提供商切换为可选项）。
providers.<id>：按语音提供商 ID 键控的提供商自有设置。
旧版直接提供商块（messages.tts.openai、messages.tts.elevenlabs、messages.tts.microsoft、messages.tts.edge）在加载时自动迁移到 messages.tts.providers.<id>。
maxTextLength：TTS 输入的硬性字符上限。/tts audio 超出时失败。
timeoutMs：请求超时（毫秒）。
prefsPath：覆盖本地偏好 JSON 路径（提供商/限制/摘要）。
apiKey 值回退到环境变量（ELEVENLABS_API_KEY/XI_API_KEY、MINIMAX_API_KEY、OPENAI_API_KEY）。
providers.elevenlabs.baseUrl：覆盖 ElevenLabs API 基础 URL。
providers.openai.baseUrl：覆盖 OpenAI TTS 端点。解析顺序：messages.tts.providers.openai.baseUrl → OPENAI_TTS_BASE_URL → https://api.openai.com/v1。非默认值视为 OpenAI 兼容 TTS 端点，接受自定义模型和语音名称。
providers.elevenlabs.voiceSettings：stability、similarityBoost、style：0..1；useSpeakerBoost：true|false；speed：0.5..2.0（1.0 = 正常）。
providers.elevenlabs.applyTextNormalization：auto|on|off。
providers.elevenlabs.languageCode：2 字母 ISO 639-1（如 en、de）。
providers.elevenlabs.seed：整数 0..4294967295（尽力确定性）。
providers.minimax.baseUrl：覆盖 MiniMax API 基础 URL（默认 https://api.minimax.io，环境变量：MINIMAX_API_HOST）。
providers.minimax.model：TTS 模型（默认 speech-2.8-hd，环境变量：MINIMAX_TTS_MODEL）。
providers.minimax.voiceId：语音标识符（默认 English_expressive_narrator，环境变量：MINIMAX_TTS_VOICE_ID）。
providers.minimax.speed：播放速度 0.5..2.0（默认 1.0）。
providers.minimax.vol：音量 (0, 10]（默认 1.0；必须大于 0）。
providers.minimax.pitch：音调偏移 -12..12（默认 0）。
providers.microsoft.enabled：允许使用 Microsoft 语音（默认 true；无 API Key）。
providers.microsoft.voice：Microsoft 神经语音名称（如 en-US-MichelleNeural）。
providers.microsoft.lang：语言代码（如 en-US）。
providers.microsoft.outputFormat：Microsoft 输出格式（如 audio-24khz-48kbitrate-mono-mp3）。有效值见 Microsoft 语音输出格式文档；并非所有格式都受捆绑的 Edge 传输支持。
providers.microsoft.rate / providers.microsoft.pitch / providers.microsoft.volume：百分比字符串（如 +10%、-5%）。
providers.microsoft.saveSubtitles：在音频文件旁写入 JSON 字幕。
providers.microsoft.proxy：Microsoft 语音请求的代理 URL。
providers.microsoft.timeoutMs：请求超时覆盖（毫秒）。
edge.*：相同 Microsoft 设置的旧版别名。

模型驱动覆盖（默认开启）

模型可以针对单次回复发出 [[tts:...]] 指令。当 messages.tts.auto 为 tagged 时，这些指令是触发音频所必需的。

启用时，模型可以发出 [[tts:...]] 指令覆盖单次回复的语音，以及可选的 [[tts:text]]...[[/tts:text]] 块提供仅出现在音频中的表达性标签。

除非 modelOverrides.allowProvider: true，否则 provider=... 指令会被忽略。

示例回复载荷：

Here you go.

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

可用指令键：

provider（注册的语音提供商 ID，如 openai、elevenlabs、minimax 或 microsoft；需要 allowProvider: true）
voice（OpenAI 语音）或 voiceId（ElevenLabs / MiniMax）
model（OpenAI TTS 模型、ElevenLabs 模型 ID 或 MiniMax 模型）
stability、similarityBoost、style、speed、useSpeakerBoost
vol / volume（MiniMax 音量，0-10）
pitch（MiniMax 音调，-12 到 12）
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,
      },
    },
  },
}

每用户偏好

Slash 命令将本地覆盖写入 prefsPath（默认：~/.openclaw/settings/tts.json，通过 OPENCLAW_TTS_PREFS 或 messages.tts.prefsPath 覆盖）。

存储字段：

enabled
provider
maxLength（摘要阈值；默认 1500 字符）
summarize（默认 true）

这些设置覆盖该主机的 messages.tts.*。

输出格式（固定）

Feishu / Matrix / Telegram / WhatsApp：Opus 语音消息（ElevenLabs 的 opus_48000_64，OpenAI 的 opus）。48kHz / 64kbps。
其他频道：MP3（ElevenLabs 的 mp3_44100_128，OpenAI 的 mp3）。44.1kHz / 128kbps。
MiniMax：MP3（speech-2.8-hd 模型，32kHz）。原生不支持语音消息格式；若需要 Opus 语音消息，使用 OpenAI 或 ElevenLabs。
Microsoft：使用 microsoft.outputFormat（默认 audio-24khz-48kbitrate-mono-mp3）。Telegram sendVoice 接受 OGG/MP3/M4A；若需要 Opus 语音消息，使用 OpenAI/ElevenLabs。若配置的 Microsoft 输出格式失败，OpenClaw 以 MP3 重试。

Auto-TTS 行为

启用时，OpenClaw：

若回复已包含媒体或 MEDIA: 指令，跳过 TTS。
跳过非常短的回复（< 10 字符）。
启用时使用 agents.defaults.model.primary（或 summaryModel）对长回复进行摘要。
将生成的音频附加到回复中。

若回复超过 maxLength 且摘要关闭（或摘要模型无 API Key），则跳过音频，发送普通文本回复。

流程图

回复 -> TTS 已启用？
  否  -> 发送文本
  是  -> 包含媒体 / MEDIA: / 太短？
          是 -> 发送文本
          否  -> 长度 > 限制？
                   否  -> TTS -> 附加音频
                   是  -> 摘要已启用？
                            否  -> 发送文本
                            是  -> 摘要（summaryModel 或 agents.defaults.model.primary）
                                      -> TTS -> 附加音频

Slash 命令用法

单一命令：/tts。启用细节见 Slash 命令。

Discord 注意：/tts 是 Discord 内置命令，因此 OpenClaw 在那里注册 /voice 作为原生命令。文本 /tts ... 仍有效。

/tts off
/tts always
/tts inbound
/tts tagged
/tts status
/tts provider openai
/tts limit 2000
/tts summary off
/tts audio Hello from OpenClaw

注意：

命令需要已授权的发件人（白名单/所有者规则仍适用）。
必须启用 commands.text 或原生命令注册。
off|always|inbound|tagged 是每会话开关（/tts on 是 /tts always 的别名）。
limit 和 summary 存储在本地偏好中，而非主配置。
/tts audio 生成一次性音频回复（不切换 TTS 开启状态）。
/tts status 包含最近一次尝试的备用可见性：成功备用显示 Fallback: <primary> -> <used> 加 Attempts: ...；失败显示 Error: ... 加 Attempts: ...；详细诊断显示 Attempt details: provider:outcome(reasonCode) latency。
OpenAI 和 ElevenLabs API 失败现在包含解析的提供商错误详情和请求 ID，显示在 TTS 错误/日志中。

代理工具

tts 工具将文本转换为语音，并返回用于回复投递的音频附件。当频道为 Feishu、Matrix、Telegram 或 WhatsApp 时，音频以语音消息而非文件附件的形式投递。

网关 RPC

网关方法：

tts.status
tts.enable
tts.disable
tts.convert
tts.setProvider
tts.providers

常见问题

MiniMax TTS 和 OpenAI/ElevenLabs 的主要区别是什么？

MiniMax 使用 T2A v2 API，输出 MP3（32kHz），不原生支持 Opus 语音消息格式。若在 Telegram/WhatsApp 等需要语音消息的频道使用，推荐 OpenAI 或 ElevenLabs——它们输出有保证的 Opus 格式。MiniMax 的优势在于中文语音质量好、国内访问快。

多个提供商都配置了 API Key，OpenClaw 怎么选主提供商？

通过 messages.tts.provider 显式指定主提供商。若该提供商请求失败，自动切换到其他已配置的提供商作为备用（备用顺序由注册表决定）。/tts status 可显示最近一次的备用切换情况（Fallback: <primary> -> <used>）。

为什么我配置了 Microsoft 语音但 Telegram 收到的却是 MP3 不是语音消息？

Microsoft 的默认输出格式是 MP3（audio-24khz-48kbitrate-mono-mp3），并非 Opus。若需要 Opus 语音消息，需将 outputFormat 改为 Ogg/WebM Opus 格式（如 audio-24khz-96kbitrate-mono-mp3 无效，需参考 Microsoft 文档选择合适的 Ogg Opus 格式），或改用 OpenAI/ElevenLabs。若配置的 Microsoft 输出格式失败，OpenClaw 会自动以 MP3 重试。

OpenClaw TTS 配置与启用完整指南 ​

5 分钟快速开启 ​

支持的服务 ​

Microsoft 语音注意事项 ​

所需密钥 ​

服务链接 ​

默认是否启用？ ​

配置详解 ​

最小配置（仅启用 + 提供商） ​

OpenAI 主提供商 + ElevenLabs 备用 ​

Microsoft 主提供商（无 API Key） ​

MiniMax 主提供商 ​

禁用 Microsoft 语音 ​

自定义限制与偏好路径 ​

仅在收到语音消息后回复音频 ​

禁用长回复的自动摘要 ​

字段说明 ​

模型驱动覆盖（默认开启） ​

每用户偏好 ​

输出格式（固定） ​

Auto-TTS 行为 ​

流程图 ​

Slash 命令用法 ​

代理工具 ​

网关 RPC ​

常见问题 ​

MiniMax TTS 和 OpenAI/ElevenLabs 的主要区别是什么？ ​

多个提供商都配置了 API Key，OpenClaw 怎么选主提供商？ ​

为什么我配置了 Microsoft 语音但 Telegram 收到的却是 MP3 不是语音消息？ ​

OpenClaw TTS 配置与启用完整指南

5 分钟快速开启

支持的服务

Microsoft 语音注意事项

所需密钥

服务链接

默认是否启用？

配置详解

最小配置（仅启用 + 提供商）

OpenAI 主提供商 + ElevenLabs 备用

Microsoft 主提供商（无 API Key）

MiniMax 主提供商

禁用 Microsoft 语音

自定义限制与偏好路径

仅在收到语音消息后回复音频

禁用长回复的自动摘要

字段说明

模型驱动覆盖（默认开启）

每用户偏好

输出格式（固定）

Auto-TTS 行为

流程图

Slash 命令用法

代理工具

网关 RPC

常见问题

MiniMax TTS 和 OpenAI/ElevenLabs 的主要区别是什么？

多个提供商都配置了 API Key，OpenClaw 怎么选主提供商？

为什么我配置了 Microsoft 语音但 Telegram 收到的却是 MP3 不是语音消息？