文字转语音（TTS）

OpenClaw 可以用 ElevenLabs、OpenAI 或 Edge TTS 把回复消息转成语音。只要 OpenClaw 能发送音频的地方都能用；在 Telegram 里会显示成圆形的语音气泡。

支持的服务

ElevenLabs（主要或备用 Provider）
OpenAI（主要或备用 Provider；也用于摘要生成）
Edge TTS（主要或备用 Provider；使用 node-edge-tts，没有 API 密钥时的默认选项）

Edge TTS 说明

Edge TTS 通过 node-edge-tts 库使用 Microsoft Edge 的在线神经网络 TTS 服务。这是一个托管服务（不是本地的），使用微软的端点，不需要 API 密钥。node-edge-tts 提供了语音配置选项和输出格式，但不是所有选项都被 Edge 服务支持。citeturn2search0

因为 Edge TTS 是一个没有公开 SLA 或配额的公共网络服务，所以只能尽力而为。如果你需要有保障的限制和支持，请使用 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 禁用）。

如果配置了多个 Provider，会先使用选定的 Provider，其他的作为备用选项。自动摘要使用配置的 summaryModel（或 agents.defaults.model.primary），所以如果启用摘要，那个 Provider 也必须通过认证。

服务链接

默认启用吗？

不。自动 TTS 默认是关闭的。在配置中用 messages.tts.auto 启用，或者在 Session 中用 /tts always（别名：/tts on）启用。

Edge TTS 在 TTS 开启后默认启用，当没有 OpenAI 或 ElevenLabs API 密钥时会自动使用。

配置

TTS 配置在 openclaw.json 的 messages.tts 下。完整的配置结构在 Gateway 配置。

最小配置（启用 + Provider）

{
  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",
        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 指令（默认开启）。
maxTextLength：TTS 输入的硬性上限（字符数）。超过时 /tts audio 会失败。
timeoutMs：请求超时（毫秒）。
prefsPath：覆盖本地偏好设置 JSON 路径（provider/limit/summary）。
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]] 块提供表现力标签（笑声、唱歌提示等），这些只会出现在音频中。

示例回复内容：

给你。

[[tts:provider=elevenlabs voiceId=pMsXgVXv3BLzUgSXRplE model=eleven_v3 speed=1.1]]
[[tts:text]](笑声) 再读一遍这首歌。[[/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

禁用所有模型覆盖：

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

可选的白名单（禁用特定覆盖，同时保持标签启用）：

{
  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 是语音消息的良好平衡，圆形气泡需要这个格式。
其他 Channel：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 密钥），会跳过音频，发送正常的文本回复。

流程图

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

斜杠命令使用

只有一个命令：/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

注意：

命令需要授权发送者（Allowlist/所有者规则仍然适用）。
必须启用 commands.text 或原生命令注册。
off|always|inbound|tagged 是 Session 级别的开关（/tts on 是 /tts always 的别名）。
limit 和 summary 存储在本地偏好设置中，不在主配置中。
/tts audio 生成一次性音频回复（不会开启 TTS）。

Agent 工具

tts 工具把文本转成语音并返回 MEDIA: 路径。当结果与 Telegram 兼容时，工具会包含 [[audio_as_voice]]，这样 Telegram 会发送语音气泡。

Gateway RPC

Gateway 方法：

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