文本转语音 (TTS)

OpenClaw 可以使用 ElevenLabs、OpenAI 或 Edge TTS 将出站回复转换为音频。它适用于 OpenClaw 可以发送音频的任何地方;Telegram 会获得一个圆形语音消息气泡。

支持的服务

ElevenLabs(主要或备用提供商)
OpenAI(主要或备用提供商;也用于摘要)
Edge TTS(主要或备用提供商;使用 node-edge-tts,在没有 API 密钥时为默认)

Edge TTS 注意事项

Edge TTS 通过 node-edge-tts 库使用 Microsoft Edge 的在线神经 TTS 服务。它是一个托管服务(非本地),使用 Microsoft 的端点,不需要 API 密钥。 node-edge-tts 公开了语音配置选项和输出格式,但并非所有选项都受 Edge 服务支持。citeturn2search0

由于 Edge TTS 是一个没有发布 SLA 或配额的公共 Web 服务,请将其视为尽力而为。如果您需要有保证的限制和支持,请使用 OpenAI 或 ElevenLabs。 Microsoft 的 Speech REST API 记录了每个请求 10 分钟的音频限制;Edge TTS 不发布限制,因此假定类似或更低的限制。citeturn0search3

可选密钥

如果您想要 OpenAI 或 ElevenLabs:

ELEVENLABS_API_KEY(或 XI_API_KEY)
OPENAI_API_KEY

Edge TTS 不需要 API 密钥。如果找不到 API 密钥,OpenClaw 默认使用 Edge TTS(除非通过 messages.tts.edge.enabled=false 禁用)。

如果配置了多个提供商,则首先使用所选提供商,其他提供商作为备用选项。自动摘要使用配置的 summaryModel(或 agents.defaults.model.primary), 因此如果启用摘要,该提供商也必须经过身份验证。

服务链接

默认启用吗?

否。自动 TTS 默认关闭。在配置中使用 messages.tts.auto 启用它,或使用 /tts always(别名:/tts on)按会话启用。

一旦 TTS 开启,Edge TTS 默认启用,并且在没有 OpenAI 或 ElevenLabs API 密钥可用时自动使用。

配置

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

最小配置(启用 + 提供商)

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,
      },
      openai: {
        apiKey: "openai_api_key",
        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,
        },
      },
    },
  },
}

Edge TTS 主要提供商(无 API 密钥)

json5

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

禁用 Edge TTS

json5

{
  messages: {
    tts: {
      edge: {
        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:自动 TTS 模式(off、always、inbound、tagged)。
- inbound 仅在收到入站语音消息后发送音频。
- tagged 仅在回复包含 [[tts]] 标签时发送音频。
enabled:旧版切换(doctor 将其迁移到 auto)。
mode:"final"(默认)或 "all"(包括工具/块回复)。
provider:"elevenlabs"、"openai" 或 "edge"(自动备用)。
如果 provider 未设置,OpenClaw 优先选择 openai(如果有密钥),然后是 elevenlabs(如果有密钥), 否则使用 edge。
summaryModel:用于自动摘要的可选廉价模型;默认为 agents.defaults.model.primary。
- 接受 provider/model 或配置的模型别名。
modelOverrides:允许模型发出 TTS 指令(默认开启)。
maxTextLength:TTS 输入的硬上限(字符)。如果超出则 /tts audio 失败。
timeoutMs:请求超时(毫秒)。
prefsPath:覆盖本地首选项 JSON 路径(提供商/限制/摘要)。
apiKey 值会回退到环境变量(ELEVENLABS_API_KEY/XI_API_KEY、OPENAI_API_KEY)。
elevenlabs.baseUrl:覆盖 ElevenLabs API 基础 URL。
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(尽力确定性)
edge.enabled:允许使用 Edge TTS(默认 true;无需 API 密钥)。
edge.voice:Edge 神经语音名称(例如 en-US-MichelleNeural)。
edge.lang:语言代码(例如 en-US)。
edge.outputFormat:Edge 输出格式(例如 audio-24khz-48kbitrate-mono-mp3)。
- 有关有效值,请参阅 Microsoft Speech 输出格式;并非所有格式都受 Edge 支持。
edge.rate / edge.pitch / edge.volume:百分比字符串(例如 +10%、-5%)。
edge.saveSubtitles:在音频文件旁边写入 JSON 字幕。
edge.proxy:Edge TTS 请求的代理 URL。
edge.timeoutMs:请求超时覆盖(毫秒)。

模型驱动覆盖(默认开启)

默认情况下,模型可以为单个回复发出 TTS 指令。当 messages.tts.auto 为 tagged 时,需要这些指令来触发音频。

启用后,模型可以发出 [[tts:...]] 指令来覆盖单个回复的语音, 以及可选的 [[tts:text]]...[[/tts:text]] 块来提供表达标签 (笑声、唱歌提示等),这些标签应该只出现在音频中。

示例回复载荷:

Here you go.

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

可用的指令键(启用时):

provider(openai | elevenlabs | edge)
voice(OpenAI 语音)或 voiceId(ElevenLabs)
model(OpenAI TTS 模型或 ElevenLabs 模型 ID)
stability、similarityBoost、style、speed、useSpeakerBoost
applyTextNormalization(auto|on|off)
languageCode(ISO 639-1)
seed

禁用所有模型覆盖:

json5

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

可选白名单(在保持标签启用的同时禁用特定覆盖):

json5

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

每用户首选项

斜杠命令将本地覆盖写入 prefsPath(默认: ~/.openclaw/settings/tts.json,使用 OPENCLAW_TTS_PREFS 或 messages.tts.prefsPath 覆盖)。

存储的字段:

enabled
provider
maxLength(摘要阈值;默认 1500 字符)
summarize(默认 true)

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

输出格式(固定)

Telegram:Opus 语音消息(来自 ElevenLabs 的 opus_48000_64,来自 OpenAI 的 opus)。
- 48kHz / 64kbps 是一个很好的语音消息折衷方案,圆形气泡需要此格式。
其他频道:MP3(来自 ElevenLabs 的 mp3_44100_128,来自 OpenAI 的 mp3)。
- 44.1kHz / 128kbps 是语音清晰度的默认平衡。
Edge TTS:使用 edge.outputFormat(默认 audio-24khz-48kbitrate-mono-mp3)。
- node-edge-tts 接受 outputFormat,但并非所有格式都可从 Edge 服务获得。citeturn2search0
- 输出格式值遵循 Microsoft Speech 输出格式(包括 Ogg/WebM Opus)。citeturn1search0
- Telegram sendVoice 接受 OGG/MP3/M4A;如果需要有保证的 Opus 语音消息, 请使用 OpenAI/ElevenLabs。citeturn1search1
- 如果配置的 Edge 输出格式失败,OpenClaw 会使用 MP3 重试。

OpenAI/ElevenLabs 格式是固定的;Telegram 需要 Opus 才能获得语音消息用户体验。

自动 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)。

代理工具

tts 工具将文本转换为语音并返回 MEDIA: 路径。当结果与 Telegram 兼容时, 该工具包含 [[audio_as_voice]],以便 Telegram 发送语音气泡。

网关 RPC

网关方法:

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

文本转语音 (TTS) ​

支持的服务 ​

Edge TTS 注意事项 ​

可选密钥 ​

服务链接 ​

默认启用吗? ​

配置 ​

最小配置(启用 + 提供商) ​

OpenAI 主要提供商,ElevenLabs 备用 ​

Edge TTS 主要提供商(无 API 密钥) ​

禁用 Edge TTS ​

自定义限制 + 首选项路径 ​

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

禁用长回复的自动摘要 ​

字段说明 ​

模型驱动覆盖(默认开启) ​

每用户首选项 ​

输出格式(固定) ​

自动 TTS 行为 ​

流程图 ​

斜杠命令用法 ​

代理工具 ​

网关 RPC ​

文本转语音 (TTS)

支持的服务

Edge TTS 注意事项

可选密钥

服务链接

默认启用吗?

配置

最小配置(启用 + 提供商)

OpenAI 主要提供商,ElevenLabs 备用

Edge TTS 主要提供商(无 API 密钥)

禁用 Edge TTS

自定义限制 + 首选项路径

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

禁用长回复的自动摘要

字段说明

模型驱动覆盖(默认开启)

每用户首选项

输出格式(固定)

自动 TTS 行为

流程图

斜杠命令用法

代理工具

网关 RPC