OpenClaw Microsoft 语音合成 Provider 深度指南免密钥接入 Edge 神经网络 TTS【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw本文围绕 OpenClaw 内置的 Microsoft 语音插件官方参考文档见 docs/plugins/reference/microsoft.md展开系统讲解它如何以零 API Key方式接入微软 Edge 在线神经网络语音服务覆盖安装分发、工作原理、完整配置字段、中文自动切换、输出格式降级、音色发现以及与语音通话Voice Call的边界。读完本文你将能独立完成 Microsoft TTS 的配置、调优与故障排查并理解其底层实现机制。插件定位与分发根据 docs/plugins/reference/microsoft.md该插件在 OpenClaw 中的定位非常明确能力摘要Adds text-to-speech provider support为 OpenClaw 增加文本转语音 Provider 支持分发包openclaw/microsoft-speech安装方式随 OpenClaw 一并内置Install route: included in OpenClaw无需单独安装对外契约SurfacespeechProviders——即注册一个符合 OpenClaw 语音 Provider 契约的实现供 TTS 工具、自动 TTS 与 Talk 等场景调用。在仓库中插件源码位于 extensions/microsoft核心文件包括文件职责index.ts插件入口通过definePluginEntry注册microsoftProviderspeech-provider.tsProvider 实现配置解析、音色列表、合成调度tts.ts底层 Edge TTS 封装与输出文件扩展名推断capability-catalog.ts能力目录声明speechProvidersopenclaw.plugin.json插件元数据契约、激活策略、默认启用speech-provider.test.tsProvider 行为测试入口注册逻辑index.ts通过插件 SDK 的registerSpeechProvider将buildMicrosoftSpeechProvider()挂载到运行时插件元数据openclaw.plugin.json声明契约speechProviders同时包含两个 idmicrosoft与edgeedge是历史别名enabledByDefault: true默认随 OpenClaw 启用activation.onStartup: false不要求在启动时强制激活按需加载。免密钥接入它是如何工作的与其他需要 API Key 的 TTS Provider 不同Microsoft Provider 在 docs/tools/tts.md 的 Provider 总表中被明确标注为Auth: none无需鉴权其原理是通过node-edge-tts调用微软 Edge 浏览器的在线神经网络 TTS 公共 Web 服务speech.platform.bing.com。该服务是公开 Web 服务没有已发布的 SLA 或配额应当按best-effort尽力而为对待。这一点在源码中得到印证package.json 声明依赖node-edge-tts: 1.2.10speech-provider.ts 构造请求头时会携带Authority: speech.platform.bing.com与 Edge 扩展来源Origin模拟 Chrome/Edge 的User-Agent版本取自CHROMIUM_FULL_VERSIONSec-MS-GEC动态令牌与Sec-MS-GEC-Version来自node-edge-tts/dist/drm.js的generateSecMsGecToken。也就是说该 Provider 复用了 Edge 浏览器朗读服务的公开接口因此不要求你拥有 Azure 订阅或任何密钥代价是没有 SLA 保证、无法承诺可用性。安全上所有对外请求都经由fetchWithSsrFGuard发出并以ssrfPolicyFromHttpBaseUrlAllowedHostname(https://speech.platform.bing.com)限定允许访问的主机名speech-provider.ts从插件 SDK 层面对请求目标做了 SSRF 防护同时通过captureHttpExchange在调试代理模式下记录 HTTP 交换便于排查问题。快速开始最小可运行配置OpenClaw 的 TTS 配置集中在~/.openclaw/openclaw.json的tts节点下详见 docs/tools/tts.md。选择 Microsoft 作为 Provider 的最小配置如下{ tts: { auto: always, // 自动 TTS 模式always / off / inbound / tagged provider: microsoft, // 语音 Provider idedge 会被归一化到 microsoft providers: { microsoft: { // 不填 apiKey —— Microsoft 无需鉴权 speakerVoice: en-US-MichelleNeural, // 规范字段历史别名 voice lang: en-US, outputFormat: audio-24khz-48kbitrate-mono-mp3, saveSubtitles: false, }, }, }, }要点tts.auto控制自动 TTSalways始终朗读、off关闭、inbound仅在收到入站语音后回复、tagged仅在回复包含[[tts:...]]指令时朗读tts.provider不设置时OpenClaw 会按注册表的自动选择顺序auto-select order取第一个已配置 Provider——Microsoft 的autoSelectOrder为30speech-provider.ts也可以使用/tts audio、/tts latest等显式指令或 Agent 的tts工具按需合成。完整配置字段参考结合 docs/tools/tts.md 的 Microsoft (no API key) 字段参考与 speech-provider.ts 的解析实现Microsoft Provider 支持以下配置项字段类型/取值默认值说明enabledbooleantrue是否允许使用 Microsoft 语音speakerVoice别名voicestringen-US-MichelleNeural微软神经网络音色名当默认英语音色生效且文本以 CJK 为主时自动切换为zh-CN-XiaoxiaoNeurallangstringen-US语言代码outputFormatstringaudio-24khz-48kbitrate-mono-mp3微软 Speech 输出格式注意内置的 Edge 传输层并不支持所有格式ratestring未设置语速百分比字符串如10%、-5%pitchstring未设置音调百分比字符串如10%、-5%volumestring未设置音量百分比字符串saveSubtitlesbooleanfalse是否在音频旁同时写入 JSON 字幕proxystring未设置语音请求使用的代理 URLtimeoutMsnumber未设置跟随请求级超时请求超时覆盖值毫秒从源码角度看配置解析speech-provider.ts会合并三个来源并以后者优先raw { ...rawConfig.edge, ...rawConfig.microsoft, ...rawConfig.providers.microsoft }这意味着历史遗留的顶层tts.edge.*、tts.microsoft.*块仍然会被读取但 docs/tools/tts.md 明确要求新配置一律写入tts.providers.microsoft遗留块由openclaw doctor --fix自动重写迁移。另外rate/pitch/volume/proxy/saveSubtitles会被原样传入node-edge-tts的EdgeTTS构造器tts.ts因此它们的行为与上游库保持一致。中文文本自动切换开箱即用的 CJK 优化一个值得关注的设计是中文自动切换speech-provider.ts当没有显式覆盖音色、且当前使用的是默认英语音色en-US-MichelleNeural时若待合成文本被判定为 CJK 主导去除空白后中日韩字符占比超过30%Provider 会自动改用zh-CN-XiaoxiaoNeural语言zh-CN反之只要你在配置或请求中显式指定了音色哪怕也是英语音色该自动切换便不再生效。这一行为在 speech-provider.test.ts 中有两组对照测试验证一组用默认英语音色合成中英混合文本你好这是一个测试 hello断言最终以zh-CN-XiaoxiaoNeural/zh-CN调用 Edge TTS另一组显式配置en-US-AvaNeural断言保持英语音色不变。对于面向中文用户的场景这一机制能避免英文语音读中文的违和体验且无需任何额外配置。输出格式、文件扩展名与降级重试Microsoft Provider 使用microsoft.outputFormat默认audio-24khz-48kbitrate-mono-mp3docs/tools/tts.md 给出了三条关键注意事项内置的 Edge 传输层接受outputFormat参数但并非所有微软官方格式都可用格式取值遵循微软 Speech 输出格式规范含 Ogg/WebM Opus 等若配置的输出格式合成失败OpenClaw 会自动改用 MP3 重试——源码中的实现是当outputFormat不等于默认 MP3 时记录一个 fallback首次失败且 fallback 与当前格式不同则切换后重试speech-provider.tsTelegram 的sendVoice只接受 OGG/MP3/M4A如果需要保证 Opus 语音消息应改用 OpenAI / ElevenLabs 等原生支持 Opus 的 Provider。生成文件的扩展名由 tts.ts 的inferEdgeExtension根据格式字符串推断包含webm→.webm、ogg→.ogg、opus→.opus、wav/riff/pcm→.wav其余默认.mp3。合成流程还有几处健壮性处理空文本直接报错Microsoft TTS text cannot be emptytts.ts空音频自动重试一次若输出文件大小为 0最多重试两轮仍为空则抛出 Edge TTS produced empty audio file after retrytts.ts输出写入临时工作目录前缀tts-microsoft-完成后在finally中清理speech-provider.ts避免残留临时文件。音色发现动态拉取微软音色目录Provider 实现了listVoices能力speech-provider.ts会实时请求https://speech.platform.bing.com/consumer/speech/synthesize/readaloud/voices/list?trustedclienttoken...并携带前述 Edge 模拟请求头。响应中的每条音色记录会被映射为 OpenClaw 的SpeechVoiceOption微软字段映射结果ShortNameid如en-US-AvaNeuralFriendlyNamename缺失时回退到 idVoiceTag.ContentCategoriescategory取第一项如GeneralVoiceTag.VoicePersonalitiespersonalities数组同时拼接为descriptionLocale/Genderlocale/gender映射过程对畸形数据非常宽容顶层不是数组时返回空目录数组中混入null、字符串、空数组或ShortName非字符串的行会被静默跳过不影响其余有效音色speech-provider.test.ts 有专门用例。若服务端返回非 2xx则抛出形如Microsoft voices API error (503)的 Provider 错误。列表请求的默认超时为30 秒且优先采用 Provider 配置中的timeoutMs其次才回退到请求级超时——测试用例prefers the configured provider request timeout验证了当配置为2345ms、请求级为1234ms时最终采用2345msspeech-provider.test.ts。调试时开启OPENCLAW_DEBUG_PROXY_ENABLED环境变量即可在调试代理会话中捕获该请求的 request/response 记录测试覆盖了重复捕获去重逻辑。与 Talk / Voice Call 的边界需要特别说明的是docs/plugins/voice-call.md 明确指出 Microsoft 语音会被语音通话忽略——电话语音合成要求 Provider 实现 telephony-target 输出而 Edge 公共服务不具备该能力。因此在 Talk / 电话场景中应选用 Azure Speech、Inworld、Gradium 等原生支持 PCM/telephony 输出的 Provider。不过在 Talk 的配置侧Microsoft Provider 依然实现了resolveTalkConfig与resolveTalkOverridesspeech-provider.ts允许 Talk 块对基础 TTS 配置做深合并覆盖resolveTalkConfig以基础tts配置为基底合并 Talk Provider 块中的voiceId → voice、languageCode → lang、outputFormat、pitch、rate、volume、proxy、timeoutMs并强制enabled: trueresolveTalkOverrides支持按请求参数覆盖voiceId与outputFormat。这些扩展点保证了 Microsoft 作为通用语音 Provider 在 OpenClaw 各语音入口中的行为一致性即便电话场景不可用也会在文档与诊断中被明确提示。兼容性与迁移edge→microsoft由于微软 Edge 历史原因旧配置中普遍使用edge作为 Provider id。OpenClaw 的兼容策略见 docs/tools/tts.mdtts.provider: edge会被归一化为microsoft遗留的tts.edge.*/tts.microsoft.*/tts.openai/tts.elevenlabs等顶层直写块由openclaw doctor --fix一键重写为tts.providers.id结构插件契约speechProviders: [microsoft, edge]同时接受两个 idopenclaw.plugin.json保证历史引用不中断。迁移后如需检查配置状态可使用openclaw doctor、tts.status、tts.providers列出已配置 Provider 及状态等命令或 Gateway RPC方法清单见 docs/tools/tts.md 的 Gateway RPC 小节。验证与测试仓库为该插件提供了完善的测试覆盖speech-provider.test.ts音色元数据映射、畸形载荷容错、503 错误抛出、超时优先级、调试代理捕获去重、CJK 自动切换与显式音色保持等extensions/microsoft/tts.test.ts 对应目录下的 TTS 行为测试extensions/microsoft/microsoft.live.test.ts面向真实服务的 live 测试需网络可达speech.platform.bing.com。限制与注意事项汇总最后把使用 Microsoft Provider 前需要明确的边界条件集中列出无 SLA、无配额保证底层是 Edge 公共朗读服务属 best-effort正式/生产场景请评估可用性风险并非所有输出格式都可用配置非默认格式前先在服务端验证失败时会自动降级为 MP3电话/Talk 场景不可用telephony 目标需要专用 Provider如 Azure Speech、Inworld中文自动切换有前提仅在未显式覆盖音色 默认英语音色 文本 CJK 占比 30%时触发请求目标被 SSRF 策略锁定只能访问speech.platform.bing.com无法通过改 baseUrl 指向其他服务。总体而言Microsoft Provider 是 OpenClaw 中唯一零配置、零密钥的语音合成方案开箱即用、支持数百种神经网络音色与动态音色发现配合中文自动切换与输出格式降级是体验 OpenClaw TTS 能力成本最低的入口。深入源码可继续阅读 speech-provider.ts 与 docs/tools/tts.md 的完整字段参考。【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
