文本转语音 (TTS)

OpenClaw 可以使用 ElevenLabs、Microsoft 或 OpenAI 将出站回复转换为音频。在 OpenClaw 可以发送音频的任何地方，它都能工作。

支持的服务

ElevenLabs（主要或备用提供商）
Microsoft（主要或备用提供商；当前捆绑的实现使用 node-edge-tts，当没有 API 密钥时为默认值）
OpenAI（主要或备用提供商；也用于生成摘要）

Microsoft 语音说明

捆绑的 Microsoft 语音提供商当前通过 node-edge-tts 库使用 Microsoft Edge 的在线神经 TTS 服务。这是一个托管服务（非本地），使用 Microsoft 端点，并且不需要 API 密钥。 node-edge-tts 公开了语音配置选项和输出格式，但并非所有选项都受该服务支持。使用 edge 的旧版配置和指令输入仍然有效，并被标准化为 microsoft。由于此路径是一个没有发布 SLA 或配额的公共 Web 服务，请将其视为尽力而为的服务。如果您需要保证的限制和支持，请使用 OpenAI 或 ElevenLabs。

可选密钥

如果您想使用 OpenAI 或 ElevenLabs：

ELEVENLABS_API_KEY（或 XI_API_KEY）
OPENAI_API_KEY

Microsoft 语音不需要 API 密钥。如果未找到 API 密钥， OpenClaw 默认使用 Microsoft（除非通过 messages.tts.microsoft.enabled=false 或 messages.tts.edge.enabled=false 禁用）。如果配置了多个提供商，则首先使用选定的提供商，其他作为备用选项。自动摘要使用配置的 summaryModel（或 agents.defaults.model.primary），因此如果您启用摘要，该提供商也必须经过身份验证。

服务链接

默认情况下是否启用？

不。自动 TTS 默认是关闭的。在配置中通过 messages.tts.auto 启用，或通过 /tts always（别名：/tts on）在每个会话中启用。一旦启用 TTS，默认情况下会启用 Microsoft 语音，并且在没有 OpenAI 或 ElevenLabs API 密钥可用时会自动使用它。

配置

TTS 配置位于 openclaw.json 中的 messages.tts 下。完整架构在 Gateway(网关) 配置中。

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

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

OpenAI 主用，ElevenLabs 备用

{
  messages: {
    tts: {
      auto: "always",
      provider: "openai",
      summaryModel: "openai/gpt-4.1-mini",
      modelOverrides: {
        enabled: true,
      },
      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 密钥）

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

禁用 Microsoft 语音

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

自定义限制 + 偏好路径

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

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

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

对长回复禁用自动摘要

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

然后运行：

/tts summary off

字段说明

auto：自动 TTS 模式（off、always、inbound、tagged）。
- inbound 仅在收到入站语音消息后发送音频。
- tagged 仅在回复包含 [[tts]] 标签时发送音频。
enabled：旧版切换开关（doctor 会将其迁移到 auto）。
mode："final"（默认）或 "all"（包括工具/块回复）。
provider：语音提供商 ID，例如 "elevenlabs"、"microsoft" 或 "openai"（后备是自动的）。
如果 provider 未设置，OpenClaw 优先选择 openai（如果有密钥），然后是 elevenlabs（如果有密钥），否则为 microsoft。
旧版 provider: "edge" 仍然有效，并被标准化为 microsoft。
summaryModel：用于自动摘要的可选低成本模型；默认为 agents.defaults.model.primary。
- 接受 provider/model 或已配置的模型别名。
modelOverrides：允许模型发出 TTS 指令（默认开启）。
- allowProvider 默认为 false（提供商切换为选择性加入）。
maxTextLength：TTS 输入的硬上限（字符数）。如果超出，/tts audio 将失败。
timeoutMs：请求超时（毫秒）。
prefsPath：覆盖本地首选项 JSON 路径（提供商/限制/摘要）。
apiKey 值会回退到环境变量（ELEVENLABS_API_KEY/XI_API_KEY，OPENAI_API_KEY）。
elevenlabs.baseUrl：覆盖 ElevenLabs API 基础 URL。
openai.baseUrl：覆盖 OpenAI TTS 端点。
- 解析顺序：messages.tts.openai.baseUrl -> OPENAI_TTS_BASE_URL -> https://api.openai.com/v1
- 非默认值将被视为与 OpenAI 兼容的 TTS 端点，因此接受自定义模型和语音名称。
elevenlabs.voiceSettings：
- stability，similarityBoost，style：0..1
- useSpeakerBoost：true|false
- speed：0.5..2.0（1.0 = 正常）
elevenlabs.applyTextNormalization：auto|on|off
elevenlabs.languageCode：2字母 ISO 639-1 代码（例如 en，de）
elevenlabs.seed：整数 0..4294967295（尽力保证确定性）
microsoft.enabled：允许使用 Microsoft 语音（默认 true；无需 API 密钥）。
microsoft.voice：Microsoft 神经语音名称（例如 en-US-MichelleNeural）。
microsoft.lang：语言代码（例如 en-US）。
microsoft.outputFormat：Microsoft 输出格式（例如 audio-24khz-48kbitrate-mono-mp3）。
- 有关有效值，请参阅 Microsoft Speech 输出格式；并非所有格式都受捆绑的 Edge 支持传输支持。
microsoft.rate / microsoft.pitch / microsoft.volume：百分比字符串（例如 +10%，-5%）。
microsoft.saveSubtitles：在音频文件旁边写入 JSON 字幕。
microsoft.proxy：Microsoft 语音请求的代理 URL。
microsoft.timeoutMs：请求超时覆盖（毫秒）。
edge.*：相同 Microsoft 设置的旧版别名。

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

默认情况下，模型可以针对单次回复发出 TTS 指令。当 messages.tts.auto 为 tagged 时，这些指令是触发音频所必需的。启用后，模型可以发出 [[tts:...]] 指令来覆盖单次回复的声音，以及一个可选的 [[tts:text]]...[[/tts:text]] 块，用于提供仅应出现在音频中的表现标签（如笑声、歌唱提示等）。 provider=... 指令会被忽略，除非 modelOverrides.allowProvider: true。示例回复载荷：

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 或 microsoft；需要 allowProvider: true）
voice（OpenAI 语音）或 voiceId（ElevenLabs）
model（OpenAI TTS 模型或 ElevenLabs 模型 ID）
stability、similarityBoost、style、speed、useSpeakerBoost
applyTextNormalization（auto|on|off）
languageCode（ISO 639-1）
seed

禁用所有模型覆盖：

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

可选允许列表（启用提供商切换，同时保持其他旋钮可配置）：

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

每用户偏好设置

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

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

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

输出格式（固定）

飞书 / Matrix / Telegram / WhatsApp：Opus 语音消息（来自 ElevenLabs 的 opus_48000_64，来自 OpenAI 的 opus）。
- 48kHz / 64kbps 是一个不错的语音消息折衷方案。
其他频道：MP3（来自 ElevenLabs 的 mp3_44100_128，来自 OpenAI 的 mp3）。
- 44.1kHz / 128kbps 是语音清晰度的默认平衡值。
Microsoft：使用 microsoft.outputFormat（默认为 audio-24khz-48kbitrate-mono-mp3）。
- 内置传输接受 outputFormat，但并非所有格式都可从该服务获得。
- 输出格式值遵循 Microsoft 语音输出格式（包括 Ogg/WebM Opus）。
- Telegram sendVoice 接受 OGG/MP3/M4A；如果您需要确保的 Opus 语音消息，请使用 OpenAI/ElevenLabs。
- 如果配置的 Microsoft 输出格式失败，OpenClaw 将使用 MP3 重试。

OpenAI/ElevenLabs 输出格式是针对每个渠道固定的（见上文）。

自动 TTS 行为

启用后，OpenClaw：

如果回复已包含媒体或 MEDIA: 指令，则跳过 TTS。
跳过非常短的回复（< 10 个字符）。
在使用 agents.defaults.model.primary（或 summaryModel）启用时，总结长回复。
将生成的音频附加到回复中。

如果回复超过 maxLength 且摘要已关闭（或没有用于摘要模型的 API 密钥），则跳过音频并发送正常文本回复。

流程图

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 (summaryModel or agents.defaults.model.primary)
                                      -> TTS -> attach audio

斜杠命令用法

只有一个命令：/tts。有关启用详细信息，请参阅斜杠命令。 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）。

Agent 工具

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

Gateway(网关) RPC

Gateway(网关) 方法：

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

本页面源自 openclaw/openclaw，由 BeaversLab 翻译，遵循 MIT 协议发布。

概览

内置工具

浏览器

智能体协作

技能

扩展

自动化

媒体与设备

文本转语音（旧路径）

文本转语音 (TTS)

支持的服务

Microsoft 语音说明

可选密钥

服务链接

默认情况下是否启用？

配置

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

OpenAI 主用，ElevenLabs 备用

Microsoft 优先（无 API 密钥）

禁用 Microsoft 语音

自定义限制 + 偏好路径

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

对长回复禁用自动摘要

字段说明

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

每用户偏好设置

输出格式（固定）

自动 TTS 行为

流程图

斜杠命令用法

Agent 工具

Gateway(网关) RPC

概览

内置工具

浏览器

智能体协作

技能

扩展

自动化

媒体与设备

​文本转语音 (TTS)

​支持的服务

​Microsoft 语音说明

​可选密钥

​服务链接

​默认情况下是否启用？

​配置

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

​OpenAI 主用，ElevenLabs 备用

​Microsoft 优先（无 API 密钥）

​禁用 Microsoft 语音

​自定义限制 + 偏好路径

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

​对长回复禁用自动摘要

​字段说明

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

​每用户偏好设置

​输出格式（固定）

​自动 TTS 行为

​流程图

​斜杠命令用法

​Agent 工具

​Gateway(网关) RPC

文本转语音 (TTS)

支持的服务

Microsoft 语音说明

可选密钥

服务链接

默认情况下是否启用？

配置

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

OpenAI 主用，ElevenLabs 备用

Microsoft 优先（无 API 密钥）

禁用 Microsoft 语音

自定义限制 + 偏好路径

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

对长回复禁用自动摘要

字段说明

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

每用户偏好设置

输出格式（固定）

自动 TTS 行为

流程图

斜杠命令用法

Agent 工具

Gateway(网关) RPC