OpenClaw 文本转语音（TTS）完整指南：ElevenLabs / OpenAI / Edge TTS 配置、自动朗读与 /tts 命令实战

• 人工智能
• AI Agent
• 即时通讯
• 后端
• 本地部署
• 语音

本文以 OpenClaw（仓库gh_mirrors/op/openclaw-cn，中文社区版）的 TTS 模块为核心，系统讲解如何让机器人的出站回复自动转换为语音：支持哪些服务商、如何配置openclaw.json中的messages.tts、模型驱动的[[tts:...]]指令如何工作、/tts斜杠命令的每种用法，以及 Gateway RPC 与 Agent 工具的调用方式。读完本文，你将能独立完成从"启用自动 TTS"到"为单条回复指定音色、语速与表达标签"的全套实战配置。

功能概览与默认行为

OpenClaw 可以把出站回复转换为音频，底层可选ElevenLabs、OpenAI或Edge TTS三个服务商，并且可以在任何能发送音频的渠道工作——在 Telegram 上会直接以圆形语音气泡（voice note）的形式送达。核心实现集中在 src/tts/tts.ts（约 1500 行），配置类型定义在 src/config/types.tts.ts，完整的单元测试见 src/tts/tts.test.ts。

需要特别注意的默认行为：

• 自动 TTS 默认关闭：需要手动在配置中设置messages.tts.auto，或用/tts always（别名/tts on）按会话开启。
• Edge TTS 默认开启：一旦 TTS 总开关打开，在没有任何 OpenAI / ElevenLabs API Key 时会自动回退到 Edge TTS（除非显式设置messages.tts.edge.enabled=false）。
• 服务商优先级：若配置了provider则以其为主；未配置时按"OpenAI（有 Key）→ ElevenLabs（有 Key）→ Edge"的顺序自动选择，这一逻辑在源码 resolveTtsProviderOrder 与 getTtsProvider 中有明确实现，测试用例 getTtsProvider 也逐一验证了三种 Key 组合下的选择结果。

支持的三种服务商

Edge TTS 的注意事项

Edge TTS 通过node-edge-tts库调用微软 Edge 浏览器的在线神经语音服务（托管服务，非本地合成），无需 API Key。node-edge-tts暴露了语音与输出格式配置项，但并非所有选项都被 Edge 服务支持。

由于 Edge TTS 是面向公众的 Web 服务，没有公开的 SLA 或配额承诺，应当将其视为 best-effort 方案。如果业务需要"保证的限额与技术支持"，请使用 OpenAI 或 ElevenLabs。微软 Speech REST API 文档给出单次请求约 10 分钟音频的上限；Edge TTS 未公布自己的限制，可按相同或更低标准估算。

可选 Key 的配置方式（两种都接受）：

• ELEVENLABS_API_KEY（或旧名XI_API_KEY）
• OPENAI_API_KEY

源码层面，Key 的解析逻辑位于 resolveTtsApiKey：ElevenLabs 依次读取config.elevenlabs.apiKey→ 环境变量ELEVENLABS_API_KEY→XI_API_KEY；OpenAI 依次读取config.openai.apiKey→ 环境变量OPENAI_API_KEY。Edge 则完全不检查 Key。

自动摘要（auto-summary）使用的是配置的summaryModel（未设置时回退到agents.defaults.model.primary），因此如果你开启了摘要，该摘要模型对应的服务商也必须完成认证，否则长回复的摘要流程会失败。

配置：messages.tts 全参数详解

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", 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 Key）

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

源码中inbound模式的判定位于 maybeApplyTtsToPayload：当autoMode === "inbound"且params.inboundAudio !== true时直接返回原文回复，测试 maybeApplyTtsToPayload 的 inbound 用例 验证了"无入站音频不调用 TTS、有入站音频才转换"的行为。

字段说明（含取值范围与默认值）

其中默认值大多定义在 src/tts/tts.ts 的常量区，resolveTtsConfig（src/tts/tts.ts）负责把原始配置与默认值合并成最终生效的ResolvedTtsConfig。

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

默认情况下，模型可以在单条回复内发出 TTS 指令。当messages.tts.auto设为tagged时，这些指令是触发音频的必要条件。

开启后，模型可以输出两类结构：

1. [[tts:...]]指令：为单条回复覆盖音色等参数；
2. [[tts:text]]...[[/tts:text]]块：提供只出现在音频里的表达性标注（笑声、唱歌提示等）。

示例回复负载：

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

可用的指令键（在modelOverrides.enabled时）：

• 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

指令解析的完整实现位于 parseTtsDirectives，测试用例 parseTtsDirectives 验证了：指令会被剥离出可见文本、[[tts:text]]内容被提取为朗读文本、非法值会进入 warnings 而不导致转换失败。

关闭全部模型覆盖：

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

按需放行（保持标签启用，但禁用特定覆盖项）：

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

配置类型中完整的放行开关包括allowText、allowProvider、allowVoice、allowModelId、allowVoiceSettings、allowNormalization、allowSeed（见 src/config/types.tts.ts），策略解析见 resolveModelOverridePolicy。模型还会在系统提示中获得语音提示（buildTtsSystemPromptHint），告知其当前 TTS 状态与摘要阈值。

每用户偏好（prefsPath）

斜杠命令会把本地覆盖写入prefsPath（默认~/.openclaw/settings/tts.json，可用环境变量OPENCLAW_TTS_PREFS或messages.tts.prefsPath覆盖；路径解析见 resolveTtsPrefsPath）。

存储字段：

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

这些字段对该主机（host）上的messages.tts.*配置形成覆盖。偏好文件的读写采用原子写入（atomicWriteFileSync），避免并发写坏文件。

输出格式（固定规则）

• Telegram：Opus 语音气泡（ElevenLabs 用opus_48000_64，OpenAI 用opus）。48kHz / 64kbps 是语音气泡的较优平衡，且只有 Opus 才支持圆形气泡。
• 其他渠道：MP3（ElevenLabs 用mp3_44100_128，OpenAI 用mp3）。44.1kHz / 128kbps 是清晰度的默认平衡。
• Edge TTS：使用edge.outputFormat（默认audio-24khz-48kbitrate-mono-mp3）。node-edge-tts接受outputFormat，但并非所有格式 Edge 服务都提供；格式值遵循微软 Speech 输出格式（含 Ogg/WebM Opus）。Telegram 的sendVoice支持 OGG/MP3/M4A，如需保证 Opus 语音气泡请使用 OpenAI/ElevenLabs。若配置的 Edge 输出格式失败，OpenClaw 会自动回退重试默认 MP3 格式（实现见 textToSpeech 中的 Edge 回退分支）。

OpenAI/ElevenLabs 的格式是固定的，Telegram 的语音气泡体验依赖 Opus。格式选择逻辑在 resolveOutputFormat 中按channelId === "telegram"分流，测试 resolveOutputFormat 用例 覆盖了 Telegram 与 Discord 两种情况。

自动 TTS 行为与决策流程

启用自动 TTS 后，OpenClaw 会：

• 若回复已包含媒体或MEDIA:指令，跳过 TTS；
• 跳过过短的回复（少于 10 个字符）；
• 长回复在开启摘要时，使用agents.defaults.model.primary（或summaryModel）先做摘要；
• 把生成的音频附加到回复上。

如果回复超过maxLength且摘要被关闭（或摘要模型无可用 Key），则跳过音频、正常发送文本回复。

完整决策流程：

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

上述逻辑在 maybeApplyTtsToPayload 中逐条实现：先是模式门控（tagged需含指令、inbound需有入站音频、mode==="final"时跳过工具/块级回复），再是媒体/长度过滤，最后是摘要与合成。摘要由 summarizeText 调用completeSimple完成，测试 summarizeText 用例 验证了摘要调用的目标长度约束（100~10000 字符）、temperature: 0.3、maxTokens计算以及summaryModel覆盖行为。

/tts 斜杠命令用法

OpenClaw 提供单一命令/tts，命令详情可参考 斜杠命令文档。Discord 注意：/tts是 Discord 内置命令，因此 OpenClaw 在 Discord 上以原生命令/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 Clawdbot

说明：

• 命令需要授权发送者（仍受 allowlist / owner 规则约束）；
• 需要启用commands.text或原生命令注册；
• off|always|inbound|tagged是按会话的开关（/tts on是/tts always的别名）；
• limit与summary写入本地 prefs，不写入主配置；
• /tts audio生成一次性音频回复（不会开启 TTS 总开关）。

命令的具体实现位于 src/auto-reply/reply/commands-tts.ts：解析逻辑见 parseTtsCommand（/tts无参数视为status），会话级开关写入sessionEntry.ttsAuto并持久化到 session store；limit的合法范围是 100~10000 字符（commands-tts.ts）；status会展示当前模式、提供商、Key 状态、文本限制、摘要开关以及最近一次尝试的延迟与结果。

Agent 工具 tts

ttsAgent 工具可以把文本转成语音并返回MEDIA:路径；当结果与 Telegram 兼容时，工具会附加[[audio_as_voice]]，让 Telegram 以语音气泡发送。

工具定义见 src/agents/tools/tts-tool.ts：参数为text（必填）、voice（Edge 语音名，格式{lang}-{region}-{name}Neural）、lang（与语音匹配的语言码，如zh-CN、en-US、ja-JP）、channel（可选渠道 ID）。工具描述特别强调：必须按文本语言选择语音（中文建议zh-CN-XiaoxiaoNeural女声 /zh-CN-YunxiNeural男声，英文建议en-US-JennyNeural女声 /en-US-GuyNeural男声，日文ja-JP-NanamiNeural，韩文ko-KR-SunHiNeural），语音与文本不匹配会产生空音频。执行时会把voice/lang转换为 Edge overrides 传入 textToSpeech，成功则返回MEDIA:路径，Telegram 场景附[[audio_as_voice]]。

Gateway RPC

TTS 能力同样通过 Gateway RPC 暴露，处理器实现在 src/gateway/server-methods/tts.ts，方法列表：

• tts.status：返回当前enabled、auto模式、主提供商、回退提供商列表、prefsPath、三家服务商的 Key/启用状态（tts.status）
• tts.enable/tts.disable：开关自动 TTS（写入 prefs）
• tts.convert：一次性把文本转为语音，返回audioPath、provider、outputFormat、voiceCompatible
• tts.setProvider：切换主提供商（仅接受openai/elevenlabs/edge）
• tts.providers：列出三家服务商的配置状态、OpenAI 可用模型与音色列表、ElevenLabs 模型列表，以及当前活跃提供商

tts.providers返回的 ElevenLabs 模型包括eleven_multilingual_v2、eleven_turbo_v2_5、eleven_monolingual_v1（tts.providers）。这些 RPC 与斜杠命令共享同一套 prefs 写入逻辑，因此通过任一入口修改的偏好会保持一致。

常见问题与建议

• 没有 Key 时如何快速体验：只需设置messages.tts.auto: "always"，不配任何 Key，即自动走 Edge TTS（默认edge.enabled: true）。
• Telegram 想要语音气泡：确保使用 OpenAI 或 ElevenLabs（Opus 格式），Edge 默认 MP3 不保证气泡形态；若坚持 Edge，可尝试outputFormat: "audio-24khz-48kbitrate-mono-ogg-opus"一类 Ogg/Opus 格式，失败时会自动回退 MP3。
• 长文本朗读成本控制：用summaryModel指定廉价摘要模型，或/tts summary off直接关闭摘要（此时超限回复不发音频）。
• 希望模型自主选音色：保持modelOverrides.enabled: true，并利用[[tts:...]]指令；如需收紧权限，用allowProvider、allowSeed等开关做细粒度放行。
• 自定义 OpenAI 兼容端点：可通过环境变量OPENAI_TTS_BASE_URL（如http://localhost:8880/v1）指向 Kokoro、LocalAI 等自建端点，此时模型与音色校验会放宽以兼容非 OpenAI 模型（见 OPENAI_TTS_BASE_URL）。

更完整的配置参考请见 Gateway 配置参考的 TTS 章节，命令总览见 斜杠命令文档。

• 人工智能
• AI Agent
• 即时通讯
• 后端
• 本地部署
• 语音