文字转语音（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 服务。它是托管服务（不是本地运行），使用的是微软的端点，不需要 API 密钥。node-edge-tts 提供了语音配置选项和输出格式，但并非所有选项都被 Edge 服务支持。citeturn2search0

Edge TTS 是一个没有公开 SLA 或配额的公共 Web 服务，只能当作尽力而为。如果你需要有保障的限额和支持，请使用 OpenAI 或 ElevenLabs。微软的 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）。

Edge TTS 本身默认是启用的——一旦 TTS 打开，在没有 OpenAI 或 ElevenLabs API 密钥时会自动使用。

配置

TTS 配置在 openclaw.json 的 messages.tts 下。 完整 schema 参见 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,
        },
      },
    },
  },
}

Edge TTS 为主（无需 API 密钥）

{
  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

{
  messages: {
    tts: {
      edge: {
        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："elevenlabs"、"openai" 或 "edge"（备选是自动的）。
  • 如果 provider 未设置，OpenClaw 优先用 openai（有密钥时），其次 elevenlabs（有密钥时），否则用 edge。
  • 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（尽力保证确定性）
  • 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 output formats；不是所有格式都被 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]] 块提供表现力标签（笑声、歌唱提示等），这些只会出现在音频中。

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（openai | elevenlabs | edge，需要 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.* 配置。

输出格式（固定）

  • 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 output formats（包括 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 发送语音气泡。

Gateway RPC

Gateway 方法：

  • tts.status
  • tts.enable
  • tts.disable
  • tts.convert
  • tts.setProvider
  • tts.providers
arrow_back
上一页
Location Command
下一页
Providers
arrow_forward