文本转语音

​

快速开始

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

​

支持的提供商

​

配置

{
  messages: {
    tts: {
      auto: "always",
      provider: "azure-speech",
      providers: {
        "azure-speech": {
          apiKey: "${AZURE_SPEECH_KEY}",
          region: "eastus",
          speakerVoice: "en-US-JennyNeural",
          lang: "en-US",
          outputFormat: "audio-24khz-48kbitrate-mono-mp3",
          voiceNoteOutputFormat: "ogg-24khz-16bit-mono-opus",
        },
      },
    },
  },
}

{
  messages: {
    tts: {
      auto: "always",
      provider: "elevenlabs",
      providers: {
        elevenlabs: {
          apiKey: "${ELEVENLABS_API_KEY}",
          model: "eleven_multilingual_v2",
          speakerVoiceId: "EXAVITQu4vr4xnSDxMaL",
        },
      },
    },
  },
}

{
  messages: {
    tts: {
      auto: "always",
      provider: "google",
      providers: {
        google: {
          apiKey: "${GEMINI_API_KEY}",
          model: "gemini-3.1-flash-tts-preview",
          speakerVoice: "Kore",
          // 可选的自然语言风格提示：
          // audioProfile: "以平静、播客主持人般的语气说话。",
          // speakerName: "Alex",
        },
      },
    },
  },
}

{
  messages: {
    tts: {
      auto: "always",
      provider: "gradium",
      providers: {
        gradium: {
          apiKey: "${GRADIUM_API_KEY}",
          speakerVoiceId: "YTpq7expH9539ERJ",
        },
      },
    },
  },
}

{
  messages: {
    tts: {
      auto: "always",
      provider: "inworld",
      providers: {
        inworld: {
          apiKey: "${INWORLD_API_KEY}",
          modelId: "inworld-tts-1.5-max",
          speakerVoiceId: "Sarah",
          temperature: 0.7,
        },
      },
    },
  },
}

{
  messages: {
    tts: {
      auto: "always",
      provider: "tts-local-cli",
      providers: {
        "tts-local-cli": {
          command: "say",
          args: ["-o", "{{OutputPath}}", "{{Text}}"],
          outputFormat: "wav",
          timeoutMs: 120000,
        },
      },
    },
  },
}

{
  messages: {
    tts: {
      auto: "always",
      provider: "microsoft",
      providers: {
        microsoft: {
          enabled: true,
          speakerVoice: "en-US-MichelleNeural",
          lang: "en-US",
          outputFormat: "audio-24khz-48kbitrate-mono-mp3",
          rate: "+0%",
          pitch: "+0%",
        },
      },
    },
  },
}

{
  messages: {
    tts: {
      auto: "always",
      provider: "minimax",
      providers: {
        minimax: {
          apiKey: "${MINIMAX_API_KEY}",
          model: "speech-2.8-hd",
          speakerVoiceId: "English_expressive_narrator",
          speed: 1.0,
          vol: 1.0,
          pitch: 0,
        },
      },
    },
  },
}

{
  messages: {
    tts: {
      auto: "always",
      provider: "openai",
      summaryModel: "openai/gpt-4.1-mini",
      modelOverrides: { enabled: true },
      providers: {
        openai: {
          apiKey: "${OPENAI_API_KEY}",
          model: "gpt-4o-mini-tts",
          speakerVoice: "alloy",
        },
        elevenlabs: {
          apiKey: "${ELEVENLABS_API_KEY}",
          model: "eleven_multilingual_v2",
          speakerVoiceId: "EXAVITQu4vr4xnSDxMaL",
          voiceSettings: { stability: 0.5, similarityBoost: 0.75, style: 0.0, useSpeakerBoost: true, speed: 1.0 },
          applyTextNormalization: "auto",
          languageCode: "en",
        },
      },
    },
  },
}

{
  messages: {
    tts: {
      auto: "always",
      provider: "openrouter",
      providers: {
        openrouter: {
          apiKey: "${OPENROUTER_API_KEY}",
          model: "hexgrad/kokoro-82m",
          speakerVoice: "af_alloy",
          responseFormat: "mp3",
        },
      },
    },
  },
}

{
  messages: {
    tts: {
      auto: "always",
      provider: "volcengine",
      providers: {
        volcengine: {
          apiKey: "${VOLCENGINE_TTS_API_KEY}",
          resourceId: "seed-tts-1.0",
          speakerVoice: "en_female_anna_mars_bigtts",
        },
      },
    },
  },
}

{
  messages: {
    tts: {
      auto: "always",
      provider: "xai",
      providers: {
        xai: {
          apiKey: "${XAI_API_KEY}",
          speakerVoiceId: "eve",
          language: "en",
          responseFormat: "mp3",
        },
      },
    },
  },
}

{
  messages: {
    tts: {
      auto: "always",
      provider: "xiaomi",
      providers: {
        xiaomi: {
          apiKey: "${XIAOMI_API_KEY}",
          model: "mimo-v2.5-tts",
          speakerVoice: "mimo_default",
          format: "mp3",
        },
      },
    },
  },
}

​

Per-agent voice overrides

{
  messages: {
    tts: {
      auto: "always",
      provider: "elevenlabs",
      providers: {
        elevenlabs: { apiKey: "${ELEVENLABS_API_KEY}", model: "eleven_multilingual_v2" },
      },
    },
  },
  agents: {
    list: [
      {
        id: "reader",
        tts: {
          providers: {
            elevenlabs: { speakerVoiceId: "EXAVITQu4vr4xnSDxMaL" },
          },
        },
      },
    ],
  },
}

1. messages.tts
2. 当前激活的 agents.list[].tts
3. 频道覆盖，当频道支持 channels.<channel>.tts 时
4. 账号覆盖，当频道传入 channels.<channel>.accounts.<id>.tts 时
5. 本地机器上的 /tts 本地偏好设置
6. 启用 模型驱动指令 时的内联 [[tts:...]] 指令

{
  messages: {
    tts: {
      provider: "openai",
      providers: {
        openai: { apiKey: "${OPENAI_API_KEY}", model: "gpt-4o-mini-tts" },
      },
    },
  },
  channels: {
    feishu: {
      accounts: {
        english: {
          tts: {
            providers: {
              openai: { speakerVoice: "shimmer" },
            },
          },
        },
      },
    },
  },
}

​

人设

​

最小 persona

{
  messages: {
    tts: {
      auto: "always",
      persona: "narrator",
      personas: {
        narrator: {
          label: "旁白",
          provider: "elevenlabs",
          providers: {
            elevenlabs: {
              speakerVoiceId: "EXAVITQu4vr4xnSDxMaL",
              modelId: "eleven_multilingual_v2",
            },
          },
        },
      },
    },
  },
}

​

完整 persona（提供商无关提示）

{
  messages: {
    tts: {
      auto: "always",
      persona: "alfred",
      personas: {
        alfred: {
          label: "Alfred",
          description: "一位干练、温暖的英式管家叙述者。",
          provider: "google",
          fallbackPolicy: "preserve-persona",
          prompt: {
            profile: "一位出色的英国管家。干练、机智、温暖、迷人、情感表达丰富，绝不千篇一律。",
            scene: "安静的深夜书房。为一位可信赖的操作员进行近距离麦克风叙述。",
            sampleContext: "说话者正在以简洁的自信和干爽的温暖回应一项私人的技术请求。",
            style: "优雅、克制、略带轻松的幽默感。",
            accent: "英式英语。",
            pacing: "节奏适中，带有短暂的戏剧性停顿。",
            constraints: ["不要大声读出配置值。", "不要解释这个 persona。"],
          },
          providers: {
            google: {
              model: "gemini-3.1-flash-tts-preview",
              speakerVoice: "Algieba",
              promptTemplate: "audio-profile-v1",
            },
            openai: { model: "gpt-4o-mini-tts", speakerVoice: "cedar" },
            elevenlabs: {
              speakerVoiceId: "voice_id",
              modelId: "eleven_multilingual_v2",
              seed: 42,
              voiceSettings: {
                stability: 0.65,
                similarityBoost: 0.8,
                style: 0.25,
                useSpeakerBoost: true,
                speed: 0.95,
              },
            },
          },
        },
      },
    },
  },
}

​

Persona 解析

1. /tts persona <id> 本地偏好（如果已设置）。
2. messages.tts.persona（如果已设置）。
3. 不使用 persona。

1. 直接覆盖（CLI、gateway、Talk、允许的 TTS 指令）。
2. /tts provider <id> 本地偏好。
3. 活动 persona 的 provider。
4. messages.tts.provider。
5. 注册表自动选择。

1. messages.tts.providers.<id>
2. messages.tts.personas.<persona>.providers.<id>
3. 可信请求覆盖
4. 允许的模型生成的 TTS 指令覆盖

​

提供商如何使用 persona 提示

​

回退策略

​

模型驱动的指令

给你。

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

• provider (registered provider id; requires allowProvider: true)
• speakerVoice / speakerVoiceId (legacy aliases: voice, voiceName, voice_name, google_voice, voiceId)
• model / google_model
• stability、similarityBoost、style、speed、useSpeakerBoost
• vol / volume（MiniMax 音量，0–10）
• pitch（MiniMax 整数音高，−12 到 12；小数值会被截断）
• emotion（Volcengine 情感标签）
• applyTextNormalization（auto|on|off）
• languageCode（ISO 639-1）
• seed

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

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

​

Slash 命令

/tts off | on | status
/tts chat on | off | default
/tts latest
/tts provider <id>
/tts persona <id> | off
/tts limit <chars>
/tts summary off
/tts audio <text>

• /tts on 会将本地 TTS 偏好写为 always；/tts off 会将其写为 off。
• /tts chat on|off|default 会为当前聊天写入一个会话范围的自动 TTS 覆盖。
• /tts persona <id> 会写入本地 persona 偏好；/tts persona off 会清除它。
• /tts latest 会读取当前会话 transcript 中最新的助手回复，并将其一次性作为音频发送。它只会在会话条目上保存该回复的哈希，以抑制重复的语音发送。
• /tts audio 会生成一次性的音频回复（不会切换 TTS 为开启）。
• limit 和 summary 存储在本地偏好中，而不是主配置里。
• /tts status 会包含最近一次尝试的回退诊断信息——Fallback: <primary> -> <used>、Attempts: ...，以及每次尝试的细节（provider:outcome(reasonCode) latency）。
• 当 TTS 启用时，/status 会显示活动 TTS 模式，以及已配置的提供商、模型、语音和已清理的自定义端点元数据。

​

每用户偏好

​

输出格式（固定）

• 支持语音消息的通道：语音消息回复优先使用 Opus（ElevenLabs 用 opus_48000_64，OpenAI 用 opus）。
  • 48kHz / 64kbps 是语音消息的良好折中。
• Feishu / WhatsApp：当语音消息回复以 MP3/WebM/WAV/M4A 或其他可能的音频文件形式生成时，通道插件会在发送原生语音消息前，使用 ffmpeg 将其转码为 48kHz 的 Ogg/Opus。WhatsApp 会通过 Baileys 的 audio 负载发送结果， 并设置 ptt: true 和 audio/ogg; codecs=opus。如果转换失败，Feishu 会将原始 文件作为附件接收；WhatsApp 则发送失败，而不是发布不兼容的 PTT 负载。
• 其他通道：MP3（ElevenLabs 用 mp3_44100_128，OpenAI 用 mp3）。
  • 44.1kHz / 128kbps 是语音清晰度的默认平衡。
• MiniMax：用于普通音频附件时使用 MP3（speech-2.8-hd 模型，32kHz 采样率）。对于通道声明支持的语音消息目标，当通道支持转码时，OpenClaw 会在发送前使用 ffmpeg 将 MiniMax 的 MP3 转码为 48kHz Opus。
• Xiaomi MiMo：默认使用 MP3，或在配置时使用 WAV。对于通道声明支持的语音消息目标，当通道支持转码时，OpenClaw 会在发送前使用 ffmpeg 将 Xiaomi 输出转码为 48kHz Opus。
• 本地 CLI：使用已配置的 outputFormat。语音消息目标 会转换为 Ogg/Opus，而电话输出会使用 ffmpeg 转换为原始 16 kHz 单声道 PCM。
• Google Gemini：Gemini API TTS 返回原始 24kHz PCM。OpenClaw 会将其包装为 WAV 用于音频附件，将其转码为 48kHz Opus 用于语音消息目标，并为 Talk/电话直接返回 PCM。
• Gradium：音频附件使用 WAV，语音消息目标使用 Opus，电话使用 8 kHz 的 ulaw_8000。
• Inworld：普通音频附件使用 MP3，语音消息目标使用原生 OGG_OPUS，Talk/电话使用 22050 Hz 的原始 PCM。
• xAI：默认使用 MP3；responseFormat 可以是 mp3、wav、pcm、mulaw 或 alaw。OpenClaw 使用 xAI 的批量 REST TTS 端点并返回完整的音频附件；此提供商路径不使用 xAI 的流式 TTS WebSocket。此路径不支持原生 Opus 语音消息格式。
• Microsoft：使用 microsoft.outputFormat（默认 audio-24khz-48kbitrate-mono-mp3）。
  • 捆绑的传输层接受 outputFormat，但并非所有格式都可从服务中获得。
  • 输出格式值遵循 Microsoft Speech 输出格式（包括 Ogg/WebM Opus）。
  • Telegram sendVoice 接受 OGG/MP3/M4A；如果你需要 保证的 Opus 语音消息，请使用 OpenAI/ElevenLabs。
  • 如果配置的 Microsoft 输出格式失败，OpenClaw 会重试 MP3。

​

Auto-TTS 行为

• 如果回复已经包含结构化媒体，则跳过 TTS。
• 跳过非常短的回复（少于 10 个字符）。
• 在启用摘要时，对长回复进行摘要，使用 summaryModel（或 agents.defaults.model.primary）。
• 将生成的音频附加到回复中。
• 在 mode: "final" 下，即使对于流式最终回复，在文本流完成后仍会发送仅音频的 TTS；生成的媒体会像普通回复附件一样经过相同的通道媒体规范化。

Reply -> TTS enabled?
  no  -> send text
  yes -> has media / short?
          yes -> send text
          no -> length > limit?
                   no  -> TTS -> attach audio
                   yes -> summary enabled?
                            no  -> send text
                            yes -> summarize -> TTS -> attach audio

​

各 channel 的输出格式

• Feishu / WhatsApp 转码： 当语音笔记回复以 MP3/WebM/WAV/M4A 形式落地时，channel 插件会使用 ffmpeg 转码为 48 kHz Ogg/Opus。WhatsApp 通过 Baileys 发送，使用 ptt: true 和 audio/ogg; codecs=opus。如果转换失败：Feishu 会回退为附加原始文件；WhatsApp 则发送失败，而不是发布不兼容的 PTT payload。
• MiniMax / Xiaomi MiMo： 默认输出 MP3（MiniMax 的 speech-2.8-hd 为 32 kHz）；针对语音笔记目标会通过 ffmpeg 转码为 48 kHz Opus。
• 本地 CLI： 使用配置的 outputFormat。语音笔记目标会转换为 Ogg/Opus，telephony 输出会转换为原始 16 kHz 单声道 PCM。
• Google Gemini： 返回原始 24 kHz PCM。OpenClaw 会将其包装为 WAV 用于附件，对语音笔记目标转码为 48 kHz Opus，对 Talk/telephony 则直接返回 PCM。
• Inworld： MP3 附件，原生 OGG_OPUS 语音笔记，Talk/telephony 使用原始 PCM 22050 Hz。
• xAI： 默认 MP3；responseFormat 可为 mp3|wav|pcm|mulaw|alaw。使用 xAI 的批量 REST 端点——不使用 streaming WebSocket TTS。不支持原生 Opus 语音笔记格式。
• Microsoft： 使用 microsoft.outputFormat（默认 audio-24khz-48kbitrate-mono-mp3）。Telegram 的 sendVoice 接受 OGG/MP3/M4A；如果你需要保证获得 Opus 语音消息，请使用 OpenAI/ElevenLabs。如果配置的 Microsoft 格式失败，OpenClaw 会重试 MP3。

​

Agent 工具

​

网关 RPC

​

服务链接

• OpenAI 文本转语音指南
• OpenAI 音频 API 参考
• Azure Speech REST 文本转语音
• Azure Speech 提供方
• ElevenLabs 文本转语音
• ElevenLabs 认证
• Gradium
• Inworld TTS API
• MiniMax T2A v2 API
• Volcengine TTS HTTP API
• Xiaomi MiMo 语音合成
• node-edge-tts
• Microsoft Speech 音频输出格式
• xAI 文本转语音

​

相关内容

• 媒体概览
• 音乐生成
• 视频生成
• 斜杠命令
• 语音通话插件