Text-to-speech（TTS）

Text-to-speech（TTS）

OpenClaw 可以使用 ElevenLabs、Microsoft 或 OpenAI 将出站回复转换为音频。只要 OpenClaw 所在渠道支持发送音频，它就可以工作；在 Telegram 中则会显示为圆形语音气泡。

支持的服务

ElevenLabs（主 provider 或 fallback provider）
Microsoft（主 provider 或 fallback provider；当前内置实现使用 node-edge-tts，在没有 API keys 时为默认选项）
OpenAI（主 provider 或 fallback provider；也用于 summaries）

Microsoft speech 说明

当前内置的 Microsoft speech provider 通过 node-edge-tts 库使用 Microsoft Edge 的在线 neural TTS 服务。这是一项托管服务（不是本地服务），使用 Microsoft 的 endpoints，并且不需要 API key。 node-edge-tts 暴露了语音配置选项和输出格式，但并非所有选项都受到该服务支持。旧版配置和 directive 输入中的 edge 仍然可用，并会被规范化为 microsoft。

由于这一路径依赖的是公共 web service，且没有公开的 SLA 或 quota，应将其视为 best-effort。如果你需要有保障的限额和支持，请使用 OpenAI 或 ElevenLabs。

可选 keys

如果你想使用 OpenAI 或 ElevenLabs：

ELEVENLABS_API_KEY（或 XI_API_KEY）
OPENAI_API_KEY

Microsoft speech 不需要 API key。如果没有找到任何 API keys，OpenClaw 会默认使用 Microsoft（除非通过 messages.tts.microsoft.enabled=false 或 messages.tts.edge.enabled=false 禁用）。

如果配置了多个 providers，会先使用选中的 provider，其他 providers 作为 fallback。自动摘要会使用配置的 summaryModel（或 agents.defaults.model.primary），因此如果你启用了 summaries，该 provider 也必须已经完成鉴权。

服务链接

默认启用吗？

不是。Auto-TTS 默认关闭。你可以在配置中通过 messages.tts.auto 启用，或者在每个 session 中使用 /tts always（别名：/tts on）启用。

一旦 TTS 被启用，Microsoft speech 默认是启用状态，并且会在没有 OpenAI 或 ElevenLabs API keys 时自动使用。

配置

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

最小配置（启用 + provider）

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

OpenAI 作为主 provider，ElevenLabs 作为 fallback

{
  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 作为主 provider（无 API key）

{
  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 speech

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

自定义 limits + prefs path

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

仅在收到入站 voice note 后才回复音频

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

为长回复禁用 auto-summary

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

然后运行：

/tts summary off

字段说明

auto：auto-TTS 模式（off、always、inbound、tagged）
- inbound 仅在收到入站 voice note 后发送音频
- tagged 仅在回复中包含 [[tts]] tags 时发送音频
enabled：旧版开关（doctor 会将其迁移到 auto）
mode："final"（默认）或 "all"（包含 tool/block replies）
provider：speech provider id，例如 "elevenlabs"、"microsoft" 或 "openai"（fallback 自动处理）
如果 provider 未设置，OpenClaw 会优先选择 openai（如果有 key），然后 elevenlabs（如果有 key），否则使用 microsoft
旧版 provider: "edge" 仍然可用，并会被规范化为 microsoft
summaryModel：用于 auto-summary 的可选低成本 model，默认是 agents.defaults.model.primary
- 接受 provider/model 或已配置的 model alias
modelOverrides：允许 model 输出 TTS directives（默认开启）
- allowProvider 默认是 false（切换 provider 需要显式开启）
maxTextLength：TTS 输入的硬上限（字符数）；超过时 /tts audio 会失败
timeoutMs：请求超时（毫秒）
prefsPath：覆盖本地 prefs JSON 路径（provider/limit/summary）
apiKey 值会回退到环境变量（ELEVENLABS_API_KEY / XI_API_KEY、OPENAI_API_KEY）
elevenlabs.baseUrl：覆盖 ElevenLabs API base URL
openai.baseUrl：覆盖 OpenAI TTS endpoint
- 解析顺序：messages.tts.openai.baseUrl → OPENAI_TTS_BASE_URL → https://api.openai.com/v1
- 非默认值会被视为 OpenAI-compatible TTS endpoints，因此允许自定义 model 和 voice 名称
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（best-effort determinism）
microsoft.enabled：允许使用 Microsoft speech（默认 true；无需 API key）
microsoft.voice：Microsoft neural voice 名称（例如 en-US-MichelleNeural）
microsoft.lang：语言代码（例如 en-US）
microsoft.outputFormat：Microsoft 输出格式（例如 audio-24khz-48kbitrate-mono-mp3）
- 有效值请参见 Microsoft Speech output formats；但内置的 Edge transport 并不支持所有格式
microsoft.rate / microsoft.pitch / microsoft.volume：百分比字符串（例如 +10%、-5%）
microsoft.saveSubtitles：在音频文件旁边写出 JSON subtitles
microsoft.proxy：Microsoft speech 请求使用的 proxy URL
microsoft.timeoutMs：请求超时覆盖值（毫秒）
edge.*：同一组 Microsoft 设置的旧版别名

Model-driven overrides（默认开启）

默认情况下，model 可以为单次回复输出 TTS directives。当 messages.tts.auto 为 tagged 时，必须有这些 directives 才会触发音频。

启用后，model 可以输出 [[tts:...]] directives 来为单条回复覆盖 voice，此外还可以使用可选的 [[tts:text]]...[[/tts:text]] block，提供只应出现在音频中的表现性标签（如笑声、唱歌提示等）。

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

示例回复 payload：

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

可用的 directive keys（启用时）：

provider（已注册的 speech provider id，例如 openai、elevenlabs 或 microsoft；需要 allowProvider: true）
voice（OpenAI voice）或 voiceId（ElevenLabs）
model（OpenAI TTS model 或 ElevenLabs model id）
stability、similarityBoost、style、speed、useSpeakerBoost
applyTextNormalization（auto|on|off）
languageCode（ISO 639-1）
seed

禁用所有 model overrides：

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

可选 allowlist（允许切换 provider，同时保留其他参数可配置）：

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

Per-user preferences

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

存储字段包括：

enabled
provider
maxLength（summary threshold，默认 1500 chars）
summarize（默认 true）

这些字段会覆盖该主机上的 messages.tts.* 配置。

输出格式（固定）

Telegram：Opus voice note（ElevenLabs 使用 opus_48000_64，OpenAI 使用 opus）
- 48kHz / 64kbps 是适合 voice note 的折中方案，也是圆形语音气泡所必需的
其他渠道：MP3（ElevenLabs 使用 mp3_44100_128，OpenAI 使用 mp3）
- 44.1kHz / 128kbps 是语音清晰度的默认平衡点
Microsoft：使用 microsoft.outputFormat（默认 audio-24khz-48kbitrate-mono-mp3）
- 内置 transport 接受 outputFormat，但并非所有格式都能从该服务获取
- 输出格式值遵循 Microsoft Speech output formats（包括 Ogg/WebM Opus）
- Telegram 的 sendVoice 接受 OGG/MP3/M4A；如果你需要保证 Opus voice notes，请使用 OpenAI 或 ElevenLabs
- 如果配置的 Microsoft 输出格式失败，OpenClaw 会回退重试 MP3

OpenAI / ElevenLabs 的输出格式是固定的；Telegram 的 voice-note UX 需要 Opus。

Auto-TTS 行为

启用后，OpenClaw 会：

如果回复中已经包含 media 或 MEDIA: directive，则跳过 TTS
跳过非常短的回复（少于 10 个字符）
在启用的情况下，对长回复使用 agents.defaults.model.primary（或 summaryModel）进行摘要
将生成的音频作为附件附加到回复中

如果回复长度超过 maxLength，且 summary 关闭（或 summary model 没有 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 (summaryModel or agents.defaults.model.primary)
                                      -> TTS -> attach audio

Slash command 用法

只有一个命令：/tts。启用方式见 Slash commands。

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

说明：

命令需要授权发送者（allowlist / owner 规则仍然适用）
必须启用 commands.text 或 native command registration
off|always|inbound|tagged 是按 session 生效的切换（/tts on 是 /tts always 的别名）
limit 和 summary 会存储在本地 prefs 中，而不是主配置中
/tts audio 会生成一次性的音频回复（不会开启持续 TTS）

Agent tool

tts tool 会将文本转换为语音，并返回一个 MEDIA: 路径。当结果兼容 Telegram 时，该 tool 还会包含 [[audio_as_voice]]，使 Telegram 以语音气泡形式发送。

Gateway RPC

Gateway methods：

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

如果你愿意，我可以把你前面这些 OpenClaw 文档片段继续统一整理成一份风格一致的中文版技术文档。

OpenClaw 开发文档 - 帮助手册 - 教程

文本转语音