OpenClaw 接入 Inworld 流式语音合成安装、配置与 MP3/OGG_OPUS/PCM 输出实战【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclawInworld 是一家提供流式文本转语音TTS能力的服务商在 OpenClaw 中作为speechProviders契约下的官方语音合成插件openclaw/inworld-speech使用它为 Agent 的外呼回复合成音频默认输出 MP3面向语音消息voice note场景输出 OGG_OPUS面向 Voice Call 等电话通道则输出 22050 Hz 的原始 PCM 音频。阅读本文后你将掌握从安装插件、配置密钥与音色到理解其流式音频拼接、鉴权方式与故障排查的完整链路。Inworld 在 OpenClaw 中的定位在 OpenClaw 的插件体系中Inworld 以官方外部包official external package形式存在核心信息如下属性值Provider idinworld插件包官方外部包openclaw/inworld-speech契约ContractspeechProviders仅 TTS鉴权环境变量INWORLD_API_KEYHTTP Basic使用控制台 Base64 凭据Base URLhttps://api.inworld.ai默认音色voiceSarah默认模型inworld-tts-1.5-max输出格式MP3默认、OGG_OPUS语音消息、PCM 22050 Hz电话通道从插件清单 extensions/inworld/openclaw.plugin.json 可以看到该插件通过speechProviders: [inworld]声明契约onStartup: false、enabledByDefault: true并声明了INWORLD_API_KEY这一环境变量其配置模式apiKey/baseUrl/voiceId/modelId/temperature也在同一文件的configSchema中做了约束。插件入口 extensions/inworld/index.ts 调用api.registerSpeechProvider(buildInworldSpeechProvider())完成注册能力目录 extensions/inworld/capability-catalog.ts 同样导出speechProviders。安装插件在 OpenClaw 中安装 Inworld 语音插件只需两步openclaw plugins install openclaw/inworld-speech openclaw gateway restartopenclaw gateway restart用于让网关重新加载插件注册表。安装来源支持 ClawHub 与 npm 两条通道clawhub:openclaw/inworld-speech/openclaw/inworld-speech插件元数据 extensions/inworld/package.json 中还声明了最低宿主版本2026.6.8与插件 API 兼容版本2026.9.3升级 OpenClaw 时需留意这些约束。快速上手第一步设置 API Key进入 Inworld 控制台Workspace API Keys复制凭据字符串然后设置为环境变量INWORLD_API_KEYbase64-credential-from-dashboard关键提醒该值是控制台给出的 Base64 编码凭据字符串OpenClaw 会将它原样作为 HTTP Basic 凭据发送Authorization: Basic apiKey因此不要再对它做一次 Base64 编码不要把它改写成 bearer token 形式。这一点在源码中也有明确注释请求头直接拼接Basic ${params.apiKey}见 extensions/inworld/tts.ts任何二次编码都会导致鉴权失败。isConfigured判定与所有请求入口synthesize / synthesizeTelephony / listVoices都依赖该密钥空白字符串会被视为未配置见 extensions/inworld/speech-provider.test.ts 中针对空白 key 的用例。第二步在 tts 配置中选用 Inworld在 OpenClaw 的tts配置块中指定 provider 与参数{ tts: { auto: always, provider: inworld, providers: { inworld: { voiceId: Sarah, modelId: inworld-tts-1.5-max, }, }, }, }完整配置说明参见 docs/gateway/configuration.mdTTS 整体能力与 provider 概览参见 docs/tools/tts.md。第三步发送消息触发合成通过任意已连接通道发送回复OpenClaw 即会调用 Inworld 流式 TTS 端点合成音频并按通道类型交付默认 MP3当通道期望 voice note 时自动请求 OGG_OPUS音频以原生语音气泡播放。配置项详解配置项配置路径说明apiKeytts.providers.inworld.apiKeyBase64 控制台凭据缺省时回退到环境变量INWORLD_API_KEYbaseUrltts.providers.inworld.baseUrl覆盖 Inworld API 基础地址默认https://api.inworld.aivoiceIdtts.providers.inworld.voiceId音色标识默认Sarah旧别名speakerVoiceIdmodelIdtts.providers.inworld.modelIdTTS 模型 id默认inworld-tts-1.5-maxtemperaturetts.providers.inworld.temperature采样温度取值范围(0, 2]0 不包含源码 extensions/inworld/speech-provider.ts 中的normalizeInworldProviderConfig展示了这些配置的实际解析逻辑apiKey走密钥规范化管线normalizeResolvedSecretInputStringbaseUrl经过normalizeInworldBaseUrl归一化尾部斜杠会被剥除见 extensions/inworld/tts.tstemperature通过asFiniteNumberInRange强制限定在(0, 2]区间越界或非法值如3、0x1会被丢弃或产生告警——这一点有测试用例佐证warns on invalid directive temperature。运行时覆盖Directive / 覆盖参数除了配置文件Inworld 还支持在运行时通过指令令牌覆盖合成参数parseDirectiveToken支持以下 keyextensions/inworld/speech-provider.tsvoice/voiceid/voice_id/inworld_voice/inworldvoice→ 覆盖voiceIdmodel/modelid/model_id/inworld_model/inworldmodel→ 覆盖modelIdtemperature→ 覆盖采样温度同样限定(0, 2]非法值输出告警invalid Inworld temperature ...覆盖优先级为运行时覆盖overrides provider 配置 默认值且talk场景resolveTalkConfig支持在talk.providers.inworld.*下独立配置 API Key 与参数。支持的模型与音色支持的模型 id 共 4 个定义于 extensions/inworld/tts.ts与测试断言一致inworld-tts-1.5-max默认inworld-tts-1.5-miniinworld-tts-1-maxinworld-tts-1音色列表可通过插件的listVoices能力从GET {baseUrl}/voices/v1/voices拉取支持?languages语言过滤参数。返回的语音元数据会映射为id/name/description/locale/gender结构其中性别取自tags中的male/female标记空voiceId条目会被过滤见 extensions/inworld/tts.test.ts 中的映射与过滤用例。音频输出格式与流式拼接原理Inworld 插件在合成时会根据目标通道选择编码常规回复默认请求MP3交付.mp3文件语音消息voice-note目标为voice-note时请求OGG_OPUS交付.ogg可在聊天通道中原生播放见synthesize实现extensions/inworld/speech-provider.ts电话通道telephonysynthesizeTelephony以PCM编码、22050 Hz采样率合成输出pcm格式并返回sampleRate: 22050直接馈入电话桥接extensions/inworld/speech-provider.ts。底层调用链extensions/inworld/tts.ts值得展开请求端点POST {baseUrl}/tts/v1/voice:stream请求体为 JSON包含text、voiceId、modelId、audioConfig.audioEncoding可选sampleRateHertz与可选的temperature流式响应端点返回换行分隔的 JSONNDJSON每行包含result.audioContentBase64 音频块或error逐行解析与拼接对每一行做 JSON 解析将合法audioContent先规范化 Base64 再解码为 Buffer累计解码字节数并最终Buffer.concat为单一音频缓冲交给 OpenClaw 标准的回复音频管线错误处理遇到error字段直接抛错Inworld TTS stream error (code): message非 JSON 行会以 UTF-16 安全截断的方式给出解析错误无任何音频数据时抛Inworld TTS returned no audio data。稳健性设计fail-closed从 extensions/inworld/tts.test.ts 的Inworld response read bounding用例组可以确认以下防护行为流式响应体读取设有上限TTS 流为共享 16 MiB 音频上限的 2 倍即 32 MiBvoices 列表为 16 MiB超限立即报错并取消底层流避免被无限流撑爆内存解码后的音频总量同样受 16 MiB 上限约束上游 30 秒无数据会触发空闲超时INWORLD_UPSTREAM_IDLE_TIMEOUT_MS非 2xx 响应的错误体只读取最多 8 KiB / 400 字符的诊断片段超限以固定标记(error body exceeded diagnostic limit; truncated)代替防止恶意端点向错误信息注入任意字节所有请求均通过fetchWithSsrFGuard发出并依据baseUrl生成主机名白名单策略hostnameAllowlist做 SSRF 防护审计上下文为inworld-tts/inworld-voices见 extensions/inworld/tts.ts。常见问题与排查建议鉴权失败 / 401确认INWORLD_API_KEY是控制台复制的 Base64 凭据原文且未被二次编码或改写为 bearer 形式错误信息形如Inworld TTS API error (401): invalid api key。Inworld API key missing环境变量未设置、或配置中的apiKey为空白字符串isConfigured会判定为未配置synthesize / synthesizeTelephony / listVoices 三个入口都会拒绝请求有专门测试覆盖见 extensions/inworld/speech-provider.test.ts。流式解析报错Inworld TTS stream parse error通常意味着端点返回了非 NDJSON 内容如网关错误页可结合baseUrl是否被自定义代理地址覆盖来排查。超时/挂起请求设置了显式超时voice 列表默认 30 秒挂在代理后面时优先检查网络可达性与baseUrl是否正确。需要自定义端点通过tts.providers.inworld.baseUrl覆盖 API 主机插件会自动剥除尾部斜杠后再拼接路径。更多排查手段参见 docs/help/troubleshooting.md全部 provider 列表参见 docs/providers/index.md。【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考