人工智能AI Agent即时通讯后端本地部署语音【免费下载链接】openclaw-cn中文社区版OpenClaw同原版保持定期更新已内置钉钉、企业微信、飞书、QQ、微信以及国内网络环境优化。你的专属个人AI助手。支持所有操作系统和平台。项目地址https://gitcode.com/gh_mirrors/op/openclaw-cn点击查看免费下载本文以 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.enabledfalse。服务商优先级若配置了provider则以其为主未配置时按OpenAI有 Key→ ElevenLabs有 Key→ Edge的顺序自动选择这一逻辑在源码 resolveTtsProviderOrder 与 getTtsProvider 中有明确实现测试用例 getTtsProvider 也逐一验证了三种 Key 组合下的选择结果。支持的三种服务商服务商是否需要 API Key定位说明ElevenLabs需要主提供商或回退音色/声学参数最丰富支持stability、similarityBoost等语音设置OpenAI需要主提供商或回退也用于自动摘要走 OpenAI 官方/v1/audio/speech接口Edge TTS不需要主提供商或回退默认兜底基于node-edge-tts库调用微软 Edge 在线神经语音服务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_KEYOPENAI_API_KEY源码层面Key 的解析逻辑位于 resolveTtsApiKeyElevenLabs 依次读取config.elevenlabs.apiKey→ 环境变量ELEVENLABS_API_KEY→XI_API_KEYOpenAI 依次读取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、有入站音频才转换的行为。字段说明含取值范围与默认值字段说明取值范围 / 默认值auto自动 TTS 模式off/always/inbound/taggedinbound仅在收到入站语音后回复音频tagged仅在回复含[[tts]]标签时朗读enabled旧版开关兼容遗留配置doctor 会将其迁移到auto见 normalizeTtsAutoMode 与 resolveTtsConfigmodeTTS 作用范围final默认仅最终回复/all含工具、块级回复provider主提供商elevenlabs/openai/edge未设置时自动回退summaryModel自动摘要用廉价模型接受provider/model或已配置的模型别名默认agents.defaults.model.primarymodelOverrides是否允许模型发出 TTS 指令默认开启maxTextLengthTTS 输入硬上限字符数默认 4000/tts audio超出即失败timeoutMs请求超时默认 30000源码 DEFAULT_TIMEOUT_MSprefsPath本地偏好 JSON 路径默认~/.openclaw/settings/tts.jsonelevenlabs.apiKeyElevenLabs Key回退ELEVENLABS_API_KEY/XI_API_KEYelevenlabs.baseUrl覆盖 API 基地址默认https://api.elevenlabs.ioelevenlabs.voiceId音色 ID默认pMsXgVXv3BLzUgSXRplE合法格式见 isValidVoiceId10~40 位字母数字elevenlabs.modelId合成模型默认eleven_multilingual_v2elevenlabs.seed尽力确定性种子整数0..4294967295elevenlabs.applyTextNormalization文本归一化auto/on/offelevenlabs.languageCode双字母语言码ISO 639-1如en、de校验见 normalizeLanguageCodeelevenlabs.voiceSettings.stability/similarityBoost/style声学参数0..1越界会抛错assertElevenLabsVoiceSettingselevenlabs.voiceSettings.useSpeakerBoost扬声器增强true/falseelevenlabs.voiceSettings.speed语速0.5..2.01.0为正常openai.apiKeyOpenAI Key回退OPENAI_API_KEYopenai.modelOpenAI TTS 模型默认gpt-4o-mini-tts完整列表见 OPENAI_TTS_MODELSgpt-4o-mini-tts、tts-1、tts-1-hdopenai.voiceOpenAI 音色默认alloy完整列表见 OPENAI_TTS_VOICESalloy、ash、coral、echo、fable、onyx、nova、sage、shimmeredge.enabled是否允许使用 Edge TTS默认trueedge.voiceEdge 神经语音名如en-US-MichelleNeuraledge.lang语言码如en-USedge.outputFormatEdge 输出格式如audio-24khz-48kbitrate-mono-mp3取值遵循微软 Speech 输出格式但并非所有格式 Edge 服务都支持edge.rate/edge.pitch/edge.volume语速/音调/音量百分比字符串如10%、-5%edge.saveSubtitles同时写出 JSON 字幕默认falseedge.proxyEdge 请求代理 URL可选edge.timeoutMsEdge 请求超时覆盖可选其中默认值大多定义在 src/tts/tts.ts 的常量区resolveTtsConfigsrc/tts/tts.ts负责把原始配置与默认值合并成最终生效的ResolvedTtsConfig。模型驱动的 TTS 覆盖默认开启默认情况下模型可以在单条回复内发出 TTS 指令。当messages.tts.auto设为tagged时这些指令是触发音频的必要条件。开启后模型可以输出两类结构[[tts:...]]指令为单条回复覆盖音色等参数[[tts:text]]...[[/tts:text]]块提供只出现在音频里的表达性标注笑声、唱歌提示等。示例回复负载Here you go. [[tts:providerelevenlabs voiceIdpMsXgVXv3BLzUgSXRplE modeleleven_v3 speed1.1]] [[tts:text]](laughs) Read the song once more.[[/tts:text]]可用的指令键在modelOverrides.enabled时provideropenai/elevenlabs/edgevoiceOpenAI 音色或voiceIdElevenLabs 音色modelOpenAI TTS 模型或 ElevenLabs 模型 IDstability、similarityBoost、style、speed、useSpeakerBoostapplyTextNormalizationauto|on|offlanguageCodeISO 639-1seed指令解析的完整实现位于 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。存储字段enabledprovidermaxLength摘要阈值默认 1500 字符summarize默认true这些字段对该主机host上的messages.tts.*配置形成覆盖。偏好文件的读写采用原子写入atomicWriteFileSync避免并发写坏文件。输出格式固定规则TelegramOpus 语音气泡ElevenLabs 用opus_48000_64OpenAI 用opus。48kHz / 64kbps 是语音气泡的较优平衡且只有 Opus 才支持圆形气泡。其他渠道MP3ElevenLabs 用mp3_44100_128OpenAI 用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需有入站音频、modefinal时跳过工具/块级回复再是媒体/长度过滤最后是摘要与合成。摘要由 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 storelimit的合法范围是 100~10000 字符commands-tts.tsstatus会展示当前模式、提供商、Key 状态、文本限制、摘要开关以及最近一次尝试的延迟与结果。Agent 工具 ttsttsAgent 工具可以把文本转成语音并返回MEDIA:路径当结果与 Telegram 兼容时工具会附加[[audio_as_voice]]让 Telegram 以语音气泡发送。工具定义见 src/agents/tools/tts-tool.ts参数为text必填、voiceEdge 语音名格式{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 RPCTTS 能力同样通过 Gateway RPC 暴露处理器实现在 src/gateway/server-methods/tts.ts方法列表tts.status返回当前enabled、auto模式、主提供商、回退提供商列表、prefsPath、三家服务商的 Key/启用状态tts.statustts.enable/tts.disable开关自动 TTS写入 prefstts.convert一次性把文本转为语音返回audioPath、provider、outputFormat、voiceCompatibletts.setProvider切换主提供商仅接受openai/elevenlabs/edgetts.providers列出三家服务商的配置状态、OpenAI 可用模型与音色列表、ElevenLabs 模型列表以及当前活跃提供商tts.providers返回的 ElevenLabs 模型包括eleven_multilingual_v2、eleven_turbo_v2_5、eleven_monolingual_v1tts.providers。这些 RPC 与斜杠命令共享同一套 prefs 写入逻辑因此通过任一入口修改的偏好会保持一致。常见问题与建议没有 Key 时如何快速体验只需设置messages.tts.auto: always不配任何 Key即自动走 Edge TTS默认edge.enabled: true。Telegram 想要语音气泡确保使用 OpenAI 或 ElevenLabsOpus 格式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即时通讯后端本地部署语音【免费下载链接】openclaw-cn中文社区版OpenClaw同原版保持定期更新已内置钉钉、企业微信、飞书、QQ、微信以及国内网络环境优化。你的专属个人AI助手。支持所有操作系统和平台。项目地址https://gitcode.com/gh_mirrors/op/openclaw-cn点击查看免费下载相关推荐让my-translator开口说话Edge TTS、Google Chirp 3 HD、ElevenLabs与Piper本地朗读四大TTS方案完整指南让my translator开口说话Edge TTS、Google Chirp 3 HD、ElevenLabs与Piper本地朗读四大TTS方案完整指南 myWin11Debloat 完整指南三步清理 Windows 11 预装应用并关闭遥测Win11Debloat 完整指南三步清理 Windows 11 预装应用并关闭遥测 当你想在新装的 Windows 11 电脑上批量移除预装应用、关掉遥测与桌面应用CLI如何快速实现文本转语音Edge TTS零配置跨平台完整方案如何快速实现文本转语音Edge TTS零配置跨平台完整方案 Edge TTS是一款强大的Python模块让你无需安装Microsoft Edge浏览器、无需语音音频AI 应用上一篇MeshCentral终极指南10分钟搭建免费开源远程设备管理平台下一篇gsd-core 发布流程版本校验加固实战拒绝前导零与 npm 重复版本预检ADR-218 全解析创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/10/14 2:46:40 · 阅读 1.2k OpenClaw 文本转语音（TTS）完整指南：ElevenLabs / OpenAI / Edge TTS 配置、自动朗读与 /tts 命令实战
人工智能AI Agent即时通讯后端本地部署语音【免费下载链接】openclaw-cn中文社区版OpenClaw同原版保持定期更新已内置钉钉、企业微信、飞书、QQ、微信以及国内网络环境优化。你的专属个人AI助手。支持所有操作系统和平台。项目地址https://gitcode.com/gh_mirrors/op/openclaw-cn点击查看免费下载本文以 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.enabledfalse。服务商优先级若配置了provider则以其为主未配置时按OpenAI有 Key→ ElevenLabs有 Key→ Edge的顺序自动选择这一逻辑在源码 resolveTtsProviderOrder 与 getTtsProvider 中有明确实现测试用例 getTtsProvider 也逐一验证了三种 Key 组合下的选择结果。支持的三种服务商服务商是否需要 API Key定位说明ElevenLabs需要主提供商或回退音色/声学参数最丰富支持stability、similarityBoost等语音设置OpenAI需要主提供商或回退也用于自动摘要走 OpenAI 官方/v1/audio/speech接口Edge TTS不需要主提供商或回退默认兜底基于node-edge-tts库调用微软 Edge 在线神经语音服务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_KEYOPENAI_API_KEY源码层面Key 的解析逻辑位于 resolveTtsApiKeyElevenLabs 依次读取config.elevenlabs.apiKey→ 环境变量ELEVENLABS_API_KEY→XI_API_KEYOpenAI 依次读取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、有入站音频才转换的行为。字段说明含取值范围与默认值字段说明取值范围 / 默认值auto自动 TTS 模式off/always/inbound/taggedinbound仅在收到入站语音后回复音频tagged仅在回复含[[tts]]标签时朗读enabled旧版开关兼容遗留配置doctor 会将其迁移到auto见 normalizeTtsAutoMode 与 resolveTtsConfigmodeTTS 作用范围final默认仅最终回复/all含工具、块级回复provider主提供商elevenlabs/openai/edge未设置时自动回退summaryModel自动摘要用廉价模型接受provider/model或已配置的模型别名默认agents.defaults.model.primarymodelOverrides是否允许模型发出 TTS 指令默认开启maxTextLengthTTS 输入硬上限字符数默认 4000/tts audio超出即失败timeoutMs请求超时默认 30000源码 DEFAULT_TIMEOUT_MSprefsPath本地偏好 JSON 路径默认~/.openclaw/settings/tts.jsonelevenlabs.apiKeyElevenLabs Key回退ELEVENLABS_API_KEY/XI_API_KEYelevenlabs.baseUrl覆盖 API 基地址默认https://api.elevenlabs.ioelevenlabs.voiceId音色 ID默认pMsXgVXv3BLzUgSXRplE合法格式见 isValidVoiceId10~40 位字母数字elevenlabs.modelId合成模型默认eleven_multilingual_v2elevenlabs.seed尽力确定性种子整数0..4294967295elevenlabs.applyTextNormalization文本归一化auto/on/offelevenlabs.languageCode双字母语言码ISO 639-1如en、de校验见 normalizeLanguageCodeelevenlabs.voiceSettings.stability/similarityBoost/style声学参数0..1越界会抛错assertElevenLabsVoiceSettingselevenlabs.voiceSettings.useSpeakerBoost扬声器增强true/falseelevenlabs.voiceSettings.speed语速0.5..2.01.0为正常openai.apiKeyOpenAI Key回退OPENAI_API_KEYopenai.modelOpenAI TTS 模型默认gpt-4o-mini-tts完整列表见 OPENAI_TTS_MODELSgpt-4o-mini-tts、tts-1、tts-1-hdopenai.voiceOpenAI 音色默认alloy完整列表见 OPENAI_TTS_VOICESalloy、ash、coral、echo、fable、onyx、nova、sage、shimmeredge.enabled是否允许使用 Edge TTS默认trueedge.voiceEdge 神经语音名如en-US-MichelleNeuraledge.lang语言码如en-USedge.outputFormatEdge 输出格式如audio-24khz-48kbitrate-mono-mp3取值遵循微软 Speech 输出格式但并非所有格式 Edge 服务都支持edge.rate/edge.pitch/edge.volume语速/音调/音量百分比字符串如10%、-5%edge.saveSubtitles同时写出 JSON 字幕默认falseedge.proxyEdge 请求代理 URL可选edge.timeoutMsEdge 请求超时覆盖可选其中默认值大多定义在 src/tts/tts.ts 的常量区resolveTtsConfigsrc/tts/tts.ts负责把原始配置与默认值合并成最终生效的ResolvedTtsConfig。模型驱动的 TTS 覆盖默认开启默认情况下模型可以在单条回复内发出 TTS 指令。当messages.tts.auto设为tagged时这些指令是触发音频的必要条件。开启后模型可以输出两类结构[[tts:...]]指令为单条回复覆盖音色等参数[[tts:text]]...[[/tts:text]]块提供只出现在音频里的表达性标注笑声、唱歌提示等。示例回复负载Here you go. [[tts:providerelevenlabs voiceIdpMsXgVXv3BLzUgSXRplE modeleleven_v3 speed1.1]] [[tts:text]](laughs) Read the song once more.[[/tts:text]]可用的指令键在modelOverrides.enabled时provideropenai/elevenlabs/edgevoiceOpenAI 音色或voiceIdElevenLabs 音色modelOpenAI TTS 模型或 ElevenLabs 模型 IDstability、similarityBoost、style、speed、useSpeakerBoostapplyTextNormalizationauto|on|offlanguageCodeISO 639-1seed指令解析的完整实现位于 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。存储字段enabledprovidermaxLength摘要阈值默认 1500 字符summarize默认true这些字段对该主机host上的messages.tts.*配置形成覆盖。偏好文件的读写采用原子写入atomicWriteFileSync避免并发写坏文件。输出格式固定规则TelegramOpus 语音气泡ElevenLabs 用opus_48000_64OpenAI 用opus。48kHz / 64kbps 是语音气泡的较优平衡且只有 Opus 才支持圆形气泡。其他渠道MP3ElevenLabs 用mp3_44100_128OpenAI 用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需有入站音频、modefinal时跳过工具/块级回复再是媒体/长度过滤最后是摘要与合成。摘要由 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 storelimit的合法范围是 100~10000 字符commands-tts.tsstatus会展示当前模式、提供商、Key 状态、文本限制、摘要开关以及最近一次尝试的延迟与结果。Agent 工具 ttsttsAgent 工具可以把文本转成语音并返回MEDIA:路径当结果与 Telegram 兼容时工具会附加[[audio_as_voice]]让 Telegram 以语音气泡发送。工具定义见 src/agents/tools/tts-tool.ts参数为text必填、voiceEdge 语音名格式{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 RPCTTS 能力同样通过 Gateway RPC 暴露处理器实现在 src/gateway/server-methods/tts.ts方法列表tts.status返回当前enabled、auto模式、主提供商、回退提供商列表、prefsPath、三家服务商的 Key/启用状态tts.statustts.enable/tts.disable开关自动 TTS写入 prefstts.convert一次性把文本转为语音返回audioPath、provider、outputFormat、voiceCompatibletts.setProvider切换主提供商仅接受openai/elevenlabs/edgetts.providers列出三家服务商的配置状态、OpenAI 可用模型与音色列表、ElevenLabs 模型列表以及当前活跃提供商tts.providers返回的 ElevenLabs 模型包括eleven_multilingual_v2、eleven_turbo_v2_5、eleven_monolingual_v1tts.providers。这些 RPC 与斜杠命令共享同一套 prefs 写入逻辑因此通过任一入口修改的偏好会保持一致。常见问题与建议没有 Key 时如何快速体验只需设置messages.tts.auto: always不配任何 Key即自动走 Edge TTS默认edge.enabled: true。Telegram 想要语音气泡确保使用 OpenAI 或 ElevenLabsOpus 格式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即时通讯后端本地部署语音【免费下载链接】openclaw-cn中文社区版OpenClaw同原版保持定期更新已内置钉钉、企业微信、飞书、QQ、微信以及国内网络环境优化。你的专属个人AI助手。支持所有操作系统和平台。项目地址https://gitcode.com/gh_mirrors/op/openclaw-cn点击查看免费下载相关推荐让my-translator开口说话Edge TTS、Google Chirp 3 HD、ElevenLabs与Piper本地朗读四大TTS方案完整指南让my translator开口说话Edge TTS、Google Chirp 3 HD、ElevenLabs与Piper本地朗读四大TTS方案完整指南 myWin11Debloat 完整指南三步清理 Windows 11 预装应用并关闭遥测Win11Debloat 完整指南三步清理 Windows 11 预装应用并关闭遥测 当你想在新装的 Windows 11 电脑上批量移除预装应用、关掉遥测与桌面应用CLI如何快速实现文本转语音Edge TTS零配置跨平台完整方案如何快速实现文本转语音Edge TTS零配置跨平台完整方案 Edge TTS是一款强大的Python模块让你无需安装Microsoft Edge浏览器、无需语音音频AI 应用上一篇MeshCentral终极指南10分钟搭建免费开源远程设备管理平台下一篇gsd-core 发布流程版本校验加固实战拒绝前导零与 npm 重复版本预检ADR-218 全解析创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考