文本转语音（TTS）

支持的服务

• ✦ElevenLabs（主要或备用提供商）
• ✦OpenAI（主要或备用提供商；也用于摘要）
• ✦Edge TTS（主要或备用提供商；使用 node-edge-tts，无 API 密钥时为默认）

Edge TTS 注意事项

可选密钥

• ✦ELEVENLABS_API_KEY（或 XI_API_KEY）
• ✦OPENAI_API_KEY

服务链接

• ✦OpenAI 文本转语音指南
• ✦OpenAI 音频 API 参考
• ✦ElevenLabs 文本转语音
• ✦ElevenLabs 认证
• ✦node-edge-tts
• ✦Microsoft 语音输出格式

默认启用吗？

配置

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

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

SH
/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 语音输出格式；并非所有格式都被 Edge 支持。
• ✦edge.rate / edge.pitch / edge.volume：百分比字符串（例如 +10%、-5%）。
• ✦edge.saveSubtitles：在音频文件旁边写入 JSON 字幕。
• ✦edge.proxy：Edge TTS 请求的代理 URL。
• ✦edge.timeoutMs：请求超时覆盖（毫秒）。

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

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

单用户偏好

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

输出格式（固定）

• ✦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 语音输出格式（包括 Ogg/WebM Opus）。citeturn1search0
  • ✦Telegram sendVoice 接受 OGG/MP3/M4A；如果你需要有保证的 Opus 语音消息，请使用 OpenAI/ElevenLabs。citeturn1search1
  • ✦如果配置的 Edge 输出格式失败，OpenClaw 会使用 MP3 重试。

自动 TTS 行为

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

流程图

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

斜杠命令用法

SH
/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）。

智能体工具

Gateway 网关 RPC

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