古法编程

Appearance

OpenClaw TTS 可将出站回复转为语音，支持 14 个提供商，默认关闭。需设置 messages.tts.auto 为 always 并指定 provider 或通过 /tts on 开启。Microsoft 和 Local CLI 无需 API Key，其他需对应环境变量。配置位于 ~/.openclaw/openclaw.json 的 messages.tts 下，支持按智能体、渠道、账号逐层覆盖，也可定义 Persona 角色确定说话风格。自动摘要使用 summaryModel，长文本超出限制或摘要禁用时回退纯文本。

OpenClaw TTS：文字转语音完整配置与故障排查 ​

OpenClaw 支持 14 个语音提供商，可将出站回复转为音频，并在 Feishu、Matrix、Telegram、WhatsApp 上发送原生语音消息，其他渠道发送音频附件，Talk/电话输出 PCM 或 Ulaw 流。

快速启用 ​

选提供商

OpenAI 和 ElevenLabs 是最稳定的托管选项。Microsoft 和 Local CLI 无需 API Key。完整列表见[提供商表格](#支持的提供商)。

设置 API Key

导出对应环境变量（如 `OPENAI_API_KEY`、`ELEVENLABS_API_KEY`）。Microsoft 和 Local CLI 无需 Key。

配置启用

修改 `messages.tts.auto: "always"` 和 `messages.tts.provider`：

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

在聊天中测试

`/tts status` 查看当前状态。`/tts audio Hello from OpenClaw` 发送一次音频回复。

INFO

Auto-TTS 默认关闭。若未设 messages.tts.provider，OpenClaw 按注册表自动选择顺序选取第一个已配置的提供商。内置 tts 智能体工具仅显式意图触发：普通聊天保持文本，除非用户要求音频、使用 /tts 或启用 Auto-TTS/指令语音。

支持的提供商 ​

提供商认证方式说明
Azure SpeechAZURE_SPEECH_KEY + AZURE_SPEECH_REGION（也支持 AZURE_SPEECH_API_KEY、SPEECH_KEY、SPEECH_REGION）原生 Ogg/Opus 语音消息输出和电话。
DeepInfraDEEPINFRA_API_KEYOpenAI 兼容 TTS，默认模型 hexgrad/Kokoro-82M。
ElevenLabsELEVENLABS_API_KEY 或 XI_API_KEY语音克隆、多语言、可设 seed 确定性；流式用于 Discord 语音播放。
Google GeminiGEMINI_API_KEY 或 GOOGLE_API_KEYGemini API 批量 TTS；通过 promptTemplate: "audio-profile-v1" 感知 Persona。
GradiumGRADIUM_API_KEY语音消息和电话输出。
InworldINWORLD_API_KEY流式 TTS API。原生 Opus 语音消息和 PCM 电话。
Local CLI无运行已配置的本地 TTS 命令。
Microsoft无通过 node-edge-tts 调用公共 Edge 神经 TTS，尽力而为，无 SLA。
MiniMaxMINIMAX_API_KEY（或 Token Plan：MINIMAX_OAUTH_TOKEN、MINIMAX_CODE_PLAN_KEY、MINIMAX_CODING_API_KEY）T2A v2 API，默认模型 speech-2.8-hd。
OpenAIOPENAI_API_KEY也用于自动摘要；支持 person a instructions。
OpenRouterOPENROUTER_API_KEY（也可复用 models.providers.openrouter.apiKey）默认模型 hexgrad/kokoro-82m。
VolcengineVOLCENGINE_TTS_API_KEY 或 BYTEPLUS_SEED_SPEECH_API_KEY（旧版 AppID/token：VOLCENGINE_TTS_APPID/_TOKEN）BytePlus Seed Speech HTTP API。
VydraVYDRA_API_KEY共享图像、视频和语音提供商。
xAIXAI_API_KEYxAI 批量 TTS。不支持原生 Opus 语音消息。
Xiaomi MiMoXIAOMI_API_KEY小米 MiMo TTS。

若配置了多个提供商，选中者优先，其余作为备用。自动摘要使用 summaryModel（或 agents.defaults.model.primary），因此若摘要开启，该提供商也必须已认证。

WARNING

捆绑的 Microsoft 提供商通过 node-edge-tts 使用微软 Edge 的在线神经 TTS 服务，这是一个无 SLA/配额的公共 Web 服务，请视为尽力而为。旧版提供商 ID edge 已规范化为 microsoft，运行 openclaw doctor --fix 重写持久化配置；新配置始终使用 microsoft。

配置 ​

TTS 配置位于 ~/.openclaw/openclaw.json 的 messages.tts 下。选择一个预设并适配供应商块：

Azure Speech

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

ElevenLabs

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

Google Gemini

json5
{
  messages: {
    tts: {
      auto: "always",
      provider: "google",
      providers: {
        google: {
          apiKey: "${GEMINI_API_KEY}",
          model: "gemini-3.1-flash-tts-preview",
          voiceName: "Kore",
          // 可选自然语言风格提示：
          // audioProfile: "Speak in a calm, podcast-host tone.",
          // speakerName: "Alex",
        },
      },
    },
  },
}

Gradium

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

Inworld

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

Local CLI

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

Microsoft（免 Key）

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

MiniMax

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

OpenAI + ElevenLabs 备用

json5
{
  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",
          voice: "alloy",
        },
        elevenlabs: {
          apiKey: "${ELEVENLABS_API_KEY}",
          model: "eleven_multilingual_v2",
          voiceId: "EXAVITQu4vr4xnSDxMaL",
          voiceSettings: { stability: 0.5, similarityBoost: 0.75, style: 0.0, useSpeakerBoost: true, speed: 1.0 },
          applyTextNormalization: "auto",
          languageCode: "en",
        },
      },
    },
  },
}

OpenRouter

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

Volcengine

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

xAI

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

Xiaomi MiMo

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

按智能体覆盖语音 ​

使用 agents.list[].tts 让某个智能体使用不同的提供商、语音、模型、Persona 或 auto-TTS 模式。该块会与 messages.tts 深度合并，因此提供商凭证可保留在全局配置中：

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

要为某个智能体固定 Persona，设置 agents.list[].tts.persona，它会覆盖全局 messages.tts.persona。

回复、/tts audio、/tts status 和 tts 智能体工具的优先级顺序：

  1. messages.tts
  2. 当前 agents.list[].tts
  3. 渠道覆盖（若渠道支持 channels.<channel>.tts）
  4. 账号覆盖（若渠道传递 channels.<channel>.accounts.<id>.tts）
  5. 本地 /tts 偏好
  6. 内联 [[tts:...]] 指令（当模型覆盖启用时）

渠道和账号覆盖使用与 messages.tts 相同的结构，并会与上层深度合并，因此共享的提供商凭证可留在 messages.tts，而渠道或机器人账号只变更语音、模型、Persona 或 auto 模式：

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

Persona ​

Persona 是一个身份稳定的口语角色，可跨提供商确定性应用。它可以指定一个首选提供商，定义提供商无关的提示意图，并携带每个提供商的语音、模型、提示模板、种子和语音设置绑定。

最小 Persona 配置 ​

json5
{
  messages: {
    tts: {
      auto: "always",
      persona: "narrator",
      personas: {
        narrator: {
          label: "Narrator",
          provider: "elevenlabs",
          providers: {
            elevenlabs: { voiceId: "EXAVITQu4vr4xnSDxMaL", modelId: "eleven_multilingual_v2" },
          },
        },
      },
    },
  },
}

完整 Persona（含提供商无关提示） ​

json5
{
  messages: {
    tts: {
      auto: "always",
      persona: "alfred",
      personas: {
        alfred: {
          label: "Alfred",
          description: "Dry, warm British butler narrator.",
          provider: "google",
          fallbackPolicy: "preserve-persona",
          prompt: {
            profile: "A brilliant British butler. Dry, witty, warm, charming, emotionally expressive, never generic.",
            scene: "A quiet late-night study. Close-mic narration for a trusted operator.",
            sampleContext: "The speaker is answering a private technical request with concise confidence and dry warmth.",
            style: "Refined, understated, lightly amused.",
            accent: "British English.",
            pacing: "Measured, with short dramatic pauses.",
            constraints: ["Do not read configuration values aloud.", "Do not explain the persona."],
          },
          providers: {
            google: { model: "gemini-3.1-flash-tts-preview", voiceName: "Algieba", promptTemplate: "audio-profile-v1" },
            openai: { model: "gpt-4o-mini-tts", voice: "cedar" },
            elevenlabs: { voiceId: "voice_id", modelId: "eleven_multilingual_v2", seed: 42, voiceSettings: { stability: 0.65, similarityBoost: 0.8, style: 0.25, useSpeakerBoost: true, speed: 0.95 } },
          },
        },
      },
    },
  },
}

Persona 解析顺序 ​

活动 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. 注册表自动选择

对于每个提供商尝试，OpenClaw 按以下顺序合并配置：

  1. messages.tts.providers.<id>
  2. messages.tts.personas.<persona>.providers.<id>
  3. 受信任请求覆盖
  4. 允许的模型发出的 TTS 指令覆盖

各提供商如何使用 Persona 提示 ​

Persona 提示字段（profile、scene、sampleContext、style、accent、pacing、constraints）是提供商无关的。每个提供商决定如何使用：

Google Gemini

仅在 Google 提供商配置设置 `promptTemplate: "audio-profile-v1"` 或 `personaPrompt` 时，将 Persona 提示字段包装成 Gemini TTS 提示结构。旧的 `audioProfile` 和 `speakerName` 字段仍作为 Google 特定提示文本前置。`[[tts:text]]` 块内的内联音频标签（如 `[whispers]`、`[laughs]`）会保留在 Gemini 转录中；OpenClaw 不生成这些标签。

OpenAI

仅当没有显式配置 OpenAI `instructions` 时，将 Persona 提示字段映射到请求的 `instructions` 字段。显式 `instructions` 始终覆盖。

其他提供商

仅使用 `personas.<id>.providers.<provider>` 下的提供商特定 Persona 绑定。除非提供商实现了自己的 Persona 提示映射，否则忽略 Persona 提示字段。

回退策略 ​

fallbackPolicy 控制当 Persona 没有对尝试的提供商绑定时的行为：

策略行为
preserve-persona默认。提供商无关提示字段仍然可用，提供商可选择使用或忽略。
provider-defaults该尝试的提示准备中忽略 Persona；提供商使用其中性默认值，同时继续回退到其他提供商。
fail跳过该提供商尝试，返回 reasonCode: "not_configured" 和 personaBinding: "missing"。但仍会尝试回退提供商。

只有 所有 尝试的提供商都被跳过或失败时，整个 TTS 请求才失败。

Talk 会话的提供商选择是会话范围的。Talk 客户端应从 talk.catalog 中选择提供商 ID、模型 ID、语音 ID 和区域设置，并通过 Talk 会话或移交请求传递。打开语音会话不应变更 messages.tts 或全局 Talk 提供商默认值。

模型驱动指令 ​

默认情况下，智能体可以发出 [[tts:...]] 指令来覆盖单次回复的语音、模型或速度，以及可选的 [[tts:text]]...[[/tts:text]] 块（只出现在音频中的表达性提示）：

text
Here you go.

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

当 messages.tts.auto 为 "tagged" 时，指令是必须的才能触发音频。流式块交付会从可见文本中去除指令，即使它们被相邻块拆分。

provider=... 会被忽略，除非 modelOverrides.allowProvider: true。当回复声明 provider=... 时，该指令的其他键仅由该提供商解析；不支持的键会被剥离并报告为 TTS 指令警告。

可用指令键：

  • provider（注册的提供商 ID；需要 allowProvider: true）
  • 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

完全禁用模型覆盖：

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

允许提供商切换同时保持其他开关可配置：

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

Slash 命令 ​

单一命令 /tts。在 Discord 上，由于 /tts 是 Discord 内置命令，OpenClaw 会注册 /voice 原生命令，但文本 /tts ... 仍然有效。

text
/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>

INFO

命令需要授权发送者（白名单/所有者规则适用），必须启用 commands.text 或原生命令注册。

行为说明：

  • /tts on 将本地 TTS 偏好写为 always；/tts off 写为 off。
  • /tts chat on|off|default 对当前聊天的 auto-TTS 写入会话级覆盖。
  • /tts persona &lt;id&gt; 写入本地 Persona 偏好；/tts persona off 清除。
  • /tts latest 从当前会话记录中读取最新智能体回复并发送一次音频。它在会话条目上仅存储该回复的哈希值以抑制重复语音发送。
  • /tts audio 生成一次性音频回复（不切换 TTS 开启状态）。
  • limit 和 summary 存储在本地偏好中，而非主配置。
  • /tts status 包含最近一次尝试的回退诊断——Fallback: &lt;primary&gt; -> &lt;used&gt;、Attempts: ... 以及每次尝试的详情（provider:outcome(reasonCode) latency）。
  • /status 显示活动 TTS 模式以及配置的提供商、模型、语音和已清理的自定义端点元数据（当 TTS 启用时）。

每用户偏好 ​

Slash 命令将本地覆盖写入 prefsPath。默认路径 ~/.openclaw/settings/tts.json；通过环境变量 OPENCLAW_TTS_PREFS 或配置 messages.tts.prefsPath 覆盖。

存储字段效果
auto本地 auto-TTS 覆盖（always、off 等）
provider本地主要提供商覆盖
persona本地 Persona 覆盖
maxLength摘要阈值（默认 1500 字符）
summarize摘要开关（默认 true）

这些覆盖 messages.tts 加上当前 agents.list[].tts 块的有效配置。

输出格式（固定） ​

TTS 语音交付由渠道能力驱动。渠道插件通告语音风格的 TTS 应向提供商请求原生 voice-note 目标还是保持普通 audio-file 合成，并仅标记兼容输出为语音交付。

  • 支持语音消息的渠道：Feishu / Matrix / Telegram / WhatsApp 的语音消息首选 Opus（ElevenLabs 的 opus_48000_64，OpenAI 的 opus）。48 kHz / 64 kbps 是语音消息的良好权衡。
  • Feishu / WhatsApp 转码：当语音消息回复以 MP3/WebM/WAV/M4A 等格式产生时，渠道插件使用 ffmpeg 转码为 48 kHz Ogg/Opus 再发送原生语音消息。WhatsApp 通过 Baileys 发送 audio 载荷，ptt: true 和 audio/ogg; codecs=opus。若转换失败，Feishu 将原始文件作为附件发送；WhatsApp 发送失败而非发送不兼容的 PTT 载荷。
  • 其他渠道：MP3（ElevenLabs 的 mp3_44100_128，OpenAI 的 mp3）。44.1 kHz / 128 kbps 是语音清晰度的默认平衡。
  • MiniMax：MP3（speech-2.8-hd 模型，32 kHz 采样率）用于普通音频附件。对于渠道通告的语音消息目标，OpenClaw 在渠道通告转码时使用 ffmpeg 将 MiniMax 的 MP3 转码为 48 kHz Opus 再交付。
  • Xiaomi MiMo：默认 MP3 或配置为 WAV。对于渠道通告的语音消息目标，OpenClaw 在渠道通告转码时使用 ffmpeg 将小米输出转码为 48 kHz Opus 再交付。
  • Local CLI：使用配置的 outputFormat。语音消息目标转换为 Ogg/Opus，电话输出转换为原始 16 kHz 单声道 PCM，使用 ffmpeg。
  • Google Gemini：Gemini API TTS 返回原始 24 kHz PCM。OpenClaw 将其包装为 WAV 用于音频附件，转码为 48 kHz Opus 用于语音消息目标，直接返回 PCM 用于 Talk/电话。
  • Gradium：WAV 用于音频附件，Opus 用于语音消息目标，ulaw_8000 8 kHz 用于电话。
  • Inworld：MP3 用于普通音频附件，原生 OGG_OPUS 用于语音消息目标，原始 PCM 22050 Hz 用于 Talk/电话。
  • 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，但并非所有格式都可从服务获取。Telegram sendVoice 接受 OGG/MP3/M4A；若需有保证的 Opus 语音消息，使用 OpenAI/ElevenLabs。若配置的 Microsoft 输出格式失败，OpenClaw 以 MP3 重试。

OpenAI/ElevenLabs 的输出格式按渠道固定（见上）。

Auto-TTS 行为 ​

当 messages.tts.auto 启用时，OpenClaw：

  • 若回复已包含媒体或 MEDIA: 指令，跳过 TTS。
  • 跳过极短回复（少于 10 字符）。
  • 当摘要启用时，使用 summaryModel（或 agents.defaults.model.primary）对长回复摘要。
  • 将生成的音频附加到回复。
  • 在 mode: "final" 时，仍为流式最终回复在文本流完成后发送纯音频 TTS；生成的媒体通过同一条渠道媒体归一化处理。

若回复超过 maxLength 且摘要关闭（或摘要模型无 API Key），则跳过音频，发送正常文本回复。

text
回复 -> TTS 启用？
  否  -> 发送文本
  是  -> 包含媒体 / MEDIA: / 太短？
          是 -> 发送文本
          否  -> 长度 > 限制？
                   否  -> TTS -> 附加音频
                   是  -> 摘要启用？
                            否  -> 发送文本
                            是  -> 摘要 -> TTS -> 附加音频

字段参考 ​

顶层 messages.tts.*

auto

  Auto-TTS 模式。`inbound` 仅在有入站语音消息后发送音频；`tagged` 仅在回复包含 `[[tts:...]]` 指令或 `[[tts:text]]` 块时发送音频。

enabled boolean

  旧版开关。`openclaw doctor --fix` 会将其迁移为 `auto`。

mode

  `"all"` 包含工具/块回复，而不仅仅是最终回复。

provider string

  语音提供商 ID。未设置时，OpenClaw 使用注册表中第一个已配置的提供商。旧版 `provider: "edge"` 会被 `openclaw doctor --fix` 重写为 `"microsoft"`。

persona string

  活动 Persona ID，来自 `personas`。统一转为小写。

personas.&lt;id&gt; object

  稳定的口语身份。字段：`label`、`description`、`provider`、`fallbackPolicy`、`prompt`、`providers.&lt;provider&gt;`。详见 [Personas](#persona)。

summaryModel string

  自动摘要使用的低价模型；默认 `agents.defaults.model.primary`。接受 `provider/model` 或配置的模型别名。

modelOverrides object

  允许智能体发出 TTS 指令。`enabled` 默认 `true`；`allowProvider` 默认 `false`。

providers.&lt;id&gt; object

  按语音提供商 ID 键控的提供商拥有设置。旧版直接块（`messages.tts.openai`、`.elevenlabs`、`.microsoft`、`.edge`）由 `openclaw doctor --fix` 重写；新配置只提交 `messages.tts.providers.&lt;id&gt;`。

maxTextLength number

  TTS 输入字符硬上限。`/tts audio` 超出时失败。

timeoutMs number

  请求超时（毫秒）。

prefsPath string

  覆盖本地偏好 JSON 路径（provider/limit/summary）。默认 `~/.openclaw/settings/tts.json`。

Azure Speech

apiKey string

region string

endpoint string

voice string

lang string

outputFormat string

voiceNoteOutputFormat string

ElevenLabs

apiKey string

model string

voiceId string

voiceSettings object

  `stability`、`similarityBoost`、`style`（均为 `0..1`），`useSpeakerBoost`（`true|false`），`speed`（`0.5..2.0`，`1.0` 正常）。

applyTextNormalization

languageCode string

seed number

baseUrl string

Google Gemini

apiKey string

model string

voiceName string

audioProfile string

speakerName string

promptTemplate

personaPrompt string

baseUrl string

Gradium

apiKey string

baseUrl string

voiceId string

Inworld

apiKey string

baseUrl string

modelId string

voiceId string

temperature number

Local CLI (tts-local-cli)

command string

args string[]

outputFormat

timeoutMs number

cwd string

env Record<string, string>

Microsoft（无 API Key）

enabled boolean

voice string

lang string

outputFormat string

rate / pitch / volume string

saveSubtitles boolean

proxy string

timeoutMs number

edge.* object

MiniMax

apiKey string

baseUrl string

model string

voiceId string

speed number

vol number

pitch number

OpenAI

apiKey string

model string

voice string

instructions string

extraBody / extra_body Record<string, unknown>

baseUrl string

  覆盖 OpenAI TTS 端点。解析顺序：配置 → `OPENAI_TTS_BASE_URL` → `https://api.openai.com/v1`。非默认值视为 OpenAI 兼容 TTS 端点，接受自定义模型和语音名称。

OpenRouter

apiKey string

baseUrl string

model string

voice string

responseFormat

speed number

Volcengine（BytePlus Seed Speech）

apiKey string

resourceId string

appKey string

baseUrl string

voice string

speedRatio number

emotion string

appId / token / cluster string

xAI

apiKey string

baseUrl string

voiceId string

language string

responseFormat

speed number

Xiaomi MiMo

apiKey string

baseUrl string

model string

voice string

format

style string

智能体工具 ​

tts 工具将文本转为语音并返回用于回复交付的音频附件。在 Feishu、Matrix、Telegram 和 WhatsApp 上，音频以语音消息而非文件附件交付。Feishu 和 WhatsApp 可在 ffmpeg 可用时对此路径的 TTS 输出进行转码。

WhatsApp 通过 Baileys 将音频作为 PTT 语音消息发送（audio 带 ptt: true），并将可见文本单独发送，因为客户端在语音消息上渲染字幕不一致。

工具接受可选 channel 和 timeoutMs 字段；timeoutMs 是每次调用的提供商请求超时（毫秒）。每次调用值覆盖 messages.tts.timeoutMs；已配置的 TTS 超时覆盖任何插件编写的提供商默认值。

Gateway RPC ​

方法目的
tts.status读取当前 TTS 状态和上次尝试。
tts.enable将本地 auto 偏好设为 always。
tts.disable将本地 auto 偏好设为 off。
tts.convert一次性文本转音频。
tts.setProvider设置本地提供商偏好。
tts.setPersona设置本地 Persona 偏好。
tts.providers列出已配置的提供商及其状态。

外部链接 ​

相关文档 ​

常见问题 ​

为什么我在聊天中说话没有自动转语音？ ​

先检查 messages.tts.auto 是否设为 "always"，或用 /tts on 开启。默认关闭。同时确认已设置提供商和对应的 API Key（Microsoft 无需 Key）。用 /tts status 查看当前状态和错误信息。

TTS 对长回复不生效怎么办？ ​

Auto-TTS 会在文本超过 maxLength（默认 1500 字符）时尝试摘要。若摘要模型（如 OpenAI）未配置 API Key，摘要会失败，导致音频跳过——文本正常发送。可设置 summaryModel 为一个可用的低价模型，或用 /tts summary off 关闭摘要（此时长回复会直接发送文本）。

如何在 Telegram 上获得 Opus 语音消息，而不是 MP3 附件？ ​

Telegram 原生支持 OGG/MP3/M4A 作为语音消息。若使用 OpenAI 或 ElevenLabs，它们会自动输出 Opus 格式语音消息。若使用 Microsoft，需将 outputFormat 设为 ogg-24khz-16bit-mono-opus 或其他 Opus 格式，否则可能回退 MP3，此时 Telegram 会作为文件附件而非语音消息发送。若需要保证的 Opus 语音消息，建议用 OpenAI 或 ElevenLabs。

友情链接： 能跑吗 · 打工算 · 车主算 · 开发工具 · 人工不智能

Copyright © 2026 古法编程 | 蜀ICP备2021007188号 | 关于本站 | 隐私政策