OpenAI 语音和语音

捆绑的 openai 插件为 tts 表面注册语音合成。

可用模型：gpt-4o-mini-tts、gpt-4o-mini-tts-2025-12-15、tts-1、 tts-1-hd。可用声音：alloy、ash、ballad、cedar、coral、 echo、fable、juniper、marin、onyx、nova、sage、shimmer、 verse。

extraBody 在 OpenClaw 生成的字段之后合并到 /audio/speech 请求 JSON 中，因此将其用于需要额外密钥（例如 lang）的 OpenAI- 兼容端点。原型键将被忽略。

{  tts: {    providers: {      openai: { model: "gpt-4o-mini-tts", speakerVoice: "coral" },    },  },}

捆绑的 openai 插件通过 OpenClaw 的媒体理解转录表面注册批量语音转文本。

当账户允许时，批量转录可以在标准转录端点上使用选定的 OpenAI API-key 或 ChatGPT OAuth 配置文件。配置的模型、提示和语言提示通过相同的请求路径工作。无需切换凭证类别即可报告访问和配额错误； OAuth 支持并不意味着包含或无限制转录。自定义端点和请求覆盖需要 API-key 配置文件。请参阅 音频和语音注释 以在需要时选择单独的音频 API- 密钥配置文件。

• 默认模型：gpt-4o-transcribe
• 端点：OpenAI REST /v1/audio/transcriptions
• 输入路径：multipart 音频文件上传
• 在入站音频转录读取 tools.media.audio 的地方使用，包括 Discord 语音通道段和通道音频附件

要强制入站音频转录使用 OpenAI：

{  tools: {    media: {      models: [        {          type: "provider",          provider: "openai",          model: "gpt-4o-transcribe",          capabilities: ["audio"],        },      ],      audio: {        enabled: true,      },    },  },}

当共享的音频媒体配置或单次转录请求提供语言和提示提示时，它们会被转发给 OpenAI。

捆绑的 openai 插件为 Voice Call 插件注册实时转录。

捆绑的 openai 插件为 Voice Call 插件注册实时语音。

gpt-realtime-2.1 可用的内置实时语音：alloy、ash、ballad、coral、echo、sage、shimmer、verse、 marin、cedar。 OpenAI 建议使用 marin 和 cedar 以获得最佳实时质量。这是与上面的文本转语音语音不同的一组； TTS-only 语音（例如 fable、nova 或 onyx）对于实时会话无效。当您更喜欢更小、成本更低的实时 2.1 变体时，请将模型明确设置为 gpt-realtime-2.1-mini。

自定义实时端点

将 talk.realtime.providers.openai.baseUrl 设置为 OpenAI 实时兼容服务器的完整 WebSocket 端点，然后选择 gateway-relay。保留 provider: "openai"：自定义 URL 不会注册新的提供商。

{  talk: {    realtime: {      provider: "openai",      transport: "gateway-relay",      model: "your-realtime-model",      providers: {        openai: {          apiKey: "${REALTIME_API_KEY}",          baseUrl: "wss://voice.example.com/custom/realtime?realtime=true",        },      },    },  },}

默认值为 wss://api.openai.com/v1/realtime。保留URL的路径和查询参数； OpenClaw 设置所选模型的 model 查询参数。适用标准 URL 解析；对签名端点使用正确的 URL-encoded 查询。包括完整的端点路径，而不仅仅是 API 根（例如 /v1）。 https: 和 http: URL 分别转换为 wss: 和 ws:。在受信任的本地网络之外首选 TLS。带有嵌入凭据或片段的 URL 将被拒绝。

相同的 baseUrl 选项可在 OpenAI 实时提供程序块中用于语音呼叫和其他网关端语音桥。它不会更改聊天、转录或 TTS 端点。当自定义端点没有显式模型时，GA Realtime 默认值仍然使用，而不是 GPT-Live。

这是服务器端实时 WebSocket 覆盖，而不是通用协议适配器：该服务必须支持 OpenClaw 的实时会话事件、音频格式、语音和工具。不暗示特定于提供商的兼容性，包括 DashScope。 API密钥保留在网关上并直接验证套接字；不需要浏览器客户端秘密端点。浏览器 WebRTC、GPT-Live 和 Azure endpoint/deployment 设置无法与此替代结合使用。这些组合会失败，而不是将凭证或音频发送到默认的 OpenAI 端点。

网关控制的实时呼叫清理

关闭网关控制的 GA 实时 WebRTC 会话会收回其网关权限，并在要求 OpenAI 挂断提供商呼叫之前关闭本地边带。这些是单独的事件；控制关闭不会建立提供者确认或召回已经排队的媒体。

如果挂断失败，显式取消或清除会报告失败。代理会在 1 秒后自动重试，然后在 5 秒后自动重试，每次尝试的现有超时时间为 30 秒。三次尝试均失败后，日志报告 cleanup INCOMPLETE。确切的清理义务及其容量仍然保留，包括跨插件替换：全局八个会话，每个网关客户端两个会话。恢复提供商连接；稍后的 OpenAI broker/plugin 运行时清理可以重试这些保留的调用。重复结束或 talk.client.close 不是重试边界，因为网关会话可能已经停用。

清理义务仅存在于内存中。网关退出、崩溃或重启都可能丢失它们；重新启动并不能证明提供者呼叫已结束。适配器的 30 分钟活动会话租用不是远程生命周期保证或挂断失败后的后备。

GA 实时浏览器身份验证

普通的 GA browser Talk 首先按以下顺序尝试平台身份验证：配置的实时密钥、openai API-key 配置文件，然后是 OPENAI_API_KEY。当平台凭证可用时，网关会创建一个临时客户端密钥，并且浏览器直接执行 SDP 交换。

当未配置平台凭证源时，普通 GA 浏览器 Talk 会回退到 OpenClaw ChatGPT OAuth 订阅配置文件。一次性网关报价经纪人将OAuth保留在服务器端，交换浏览器的SDP，并仅返回答案SDP。显式配置但不可用的平台凭据会失败，而不是回退到 OAuth。

网关控制的 GA 中继、iOS 客户端拥有的 WebRTC、GA 语音呼叫、直接后端套接字和 GA Discord 实时语音需要平台身份验证。

GPT-直播 API

未配置模型时，通话和网关中继会话选择 GPT-Live。 OpenAI 平台密钥、API-key 配置文件或 OPENAI_API_KEY 选择 gpt-live-1 和 marin； ChatGPT-only 账户选择 gpt-live-1-codex 和 cove。配置的平台凭据优先于 ChatGPT 登录，包括当该凭据需要修复时。

GPT-Live 仅支持音频，因此 Control UI 在此默认情况下不提供相机捕获功能。明确选择 gpt-realtime-2.1 来使用相机。 talk.catalog 描述已配置的 Talk 代理的默认发现表面；范围为另一个代理的会话在启动时解析该代理的帐户。

明确的模型选择和该模型支持的声音仍然有效；显式 GPT-Live 模型仅包含音频。当没有固定模型时，需要视频或强制代理咨询回复的请求会保留 gpt-realtime-2.1。直接工具桥、Discord 和语音呼叫，无需显式模型，并且 Azure 部署保留其现有默认值。 Discord 或语音呼叫中的显式 GPT-Live 模型使用共享网关中继桥和提供商拥有的委派。安装更新不会重写已保存的配置或切换活动会话。

对于公共 GPT-Live API，将 talk.realtime.model 显式设置为 gpt-live-1。 GPT-Live 处理语音对话，同时委派任务通过您配置的 OpenClaw 代理运行。它可以边听边说；打断讲话本身并不取消智能体的工作。

该模型需要具有模型访问权限的 OpenAI 平台 API 密钥（从配置的实时密钥、openai API-key 配置文件或 OPENAI_API_KEY 中选择）。 ChatGPT 订阅凭证不是 gpt-live-1 的后备。

{  talk: {    realtime: {      provider: "openai",      model: "gpt-live-1",      speakerVoice: "marin",      transport: "webrtc",    },  },}

Browser Talk 使用网关代理的 WebRTC；平台密钥保留在网关上。设置 transport: "gateway-relay" 为直接服务器 WebSocket 路径。 Discord 实时语音和使用 gpt-live-1 的语音呼叫使用相同的网关拥有的直接 WebSocket 桥接和本机代理委派。

iOS 使用相同的代理 WebRTC 路径并显示公共实时字幕。物理设备语音验证仍悬而未决。

默认语音为 marin。支持的内置语音有 alloy、ash、ballad、beacon、bossa、cedar、cinder、coral、delta、 echo、gleam、marin、meridian、quartz、ripple、sage、shimmer、stone、 tempo、verse、vesper 和 willow。不支持的配置语音回退到 marin。在开始会话之前选择声音。 cove 属于 gpt-live-1-codex；使用公共 gpt-live-1 模型选择它会回退到 marin。

公共API使用/v1/live/sessions来创建WebRTC和主WebSockets。直接插座以session.start开头；浏览器会话在 SDP 交换期间启动。网关边带处理委派的工作，而浏览器媒体保留在 WebRTC 上。公开直播指令将 session.thinking.append 描述为安静环境，将 session.commentary.append 描述为语音更新。定制指令应保留这种区别； Codex 路线使用其单独的 commentary/speakable 通道合约。

两条路由都指示语音模型等待委托结果，而不是重复相同的后端请求。仍然允许新用户跟进、更正和明确重试。这些指令指导模型的行为；他们不保证每个请求只执行一次。

公共记录事件是片段，而不是完整的回合。网关拥有有限接收文本快照的持久性；客户端显示字幕而不保存另一个副本。实时字幕和保存的快照都可以跨越同一演讲者的多次交流；它们不重建时间顺序或跨说话者计时。重叠的片段不能识别完整的话语。保存文本并不表明语音或播放已完成。有关公共会话和语音合约，请参阅 OpenAI 的 会话指南。

发布GPT-Live浏览器和网关中继认证

单独的Codex GPT-Live模型gpt-live-1-codex保留了其ChatGPT订阅路线。其浏览器和网关中继 WebRTC 首先尝试 OpenClaw ChatGPT OAuth 订阅配置文件。当 OAuth 不可用时，网关按以下顺序回退到平台身份验证：配置的实时密钥、openai API-key 配置文件，然后是 OPENAI_API_KEY。使用 openclaw models auth login --provider openai 创建 OAuth 配置文件。

当 channels.discord.voice.realtime.model 是 gpt-live-1-codex 时，Discord 使用相同的网关拥有的 WebRTC 桥。将 channels.discord.voice.realtime.speakerVoice 设置为 cove 作为 Codex 默认语音。其他支持的语音为 arbor、breeze、ember、juniper、maple、sol、spruce 和 vale。语音选择特定于其模型路由，无论客户端是 Talk、Discord 还是 Voice Call。

当 plugins.entries.voice-call.config.realtime.providers.openai.model 为 gpt-live-1-codex 时，语音呼叫使用相同的 OAuth- 桥接器；在该提供程序块中设置 voice: "cove"。其音频适配器可将 8 kHz 的载波 G.711 mu-law 与模型的 24 kHz PCM 流进行转换，以用于 WebRTC 和直接 WebSocket 路由。初始问候语和 voicecall.speak 请求使用本机会话上下文。

两条 GPT-Live 路由都会产生连续的音频和自己的中断。网关 WebSocket 和 WebRTC 使用相同的采样时钟以记录的速率发送麦克风输入，并在捕获之间提供静音。 Discord 不添加扬声器启动取消或等待响应完成事件来播放简短回复。显式 Discord requireWakeName: true 或 consultPolicy: "always" 被拒绝，因为 GPT-Live 无法强制执行这些主机策略；它的默认值使用自动提供者委派。每个演讲者的委派工作保留其 Discord 身份和权限。共享的 OpenClaw 座席对话提供房间上下文，而每个发言者的语音模型连接都有单独的声学对话历史记录。请参阅 Discord](/channels/discord/voice-channels#gpt-live-in-discord) 中的 [GPT-Live。

语音通话还会在实时播放期间使麦克风输入保持打开状态，并且不会添加主持人语音开始取消功能。本机委托使用现有的呼叫拥有的​​代理咨询，包括其工具策略和取消生命周期。对于 GPT-Live，显式 realtime.consultPolicy: "always" 被拒绝。 openclaw_end_call 和自定义 realtime.tools 需要本机功能工具支持，并且在 GPT-Live 上仍然不可用；代表团不会揭露他们。请参阅语音 Call](/plugins/voice-call/realtime-and-streaming#gpt-live) 中的 [GPT-Live。

两种凭证类型都保留在网关中。一次性报价经纪人交换浏览器的 SDP 并仅返回答案 SDP；它不会向浏览器发送 OAuth 令牌、平台密钥或临时客户端密钥。

网关中继 WebRTC 根据连续采样时钟调整麦克风音频的速度，因此在较长的通话过程中计时器延迟不会累积。调度程序暂停后，排队的音频会以正常速度恢复，而时间戳会说明经过的间隙。呼叫隐藏格式错误的传入音频数据包并继续播放稍后的音频。一个被拒绝的音频数据包发送不会结束其他连接的呼叫。不可用的编解码器状态、意外的流更改和终端连接状态仍然会结束呼叫。丢包诊断忽略原始错误详细信息。

启用的 OpenAI 插件会自动启动代理，包括在网关启动后登录时。仅当您启动语音会话时，代理才会打开提供商会话；登录不打开麦克风或加入Discord语音。登录后返回浏览器会刷新聊天麦克风的就绪状态。

未列出的私有实时传输路径

未列出或私人浏览器 Talk 使用具有网关拥有控制权的平台密钥客户端 WebRTC。网关中继和其他直接后端消费者使用平台密钥双向传输。凭证和提供商控制保留在网关上。

使用账户发布的实时模型值。未列出的模型值被接受为自由格式的 Talk 配置，但不会通过目录或诊断发布。使用 talk.realtime.model 明确选择加入；发布的模型仍然是默认的。

当前平台密钥会话接受 marin 和 cedar。 OpenClaw 默认为 marin 并将不支持的配置语音映射回它。

未列出或私有浏览器 WebRTC 先决条件，依次为：

1. A 通过 talk.realtime.providers.openai.apiKey、openai API-key 配置文件或 OPENAI_API_KEY 配置的平台 API 密钥。
2. talk.realtime.model 设置为帐户发行的值 - 通过 Control UI 中的 Settings → Talk 或下面的配置。
3. 捆绑的openai插件以完整模式注册。限制性 plugins.allow 列表失败，并显示“OpenAI 实时浏览器会话代理不可用”。

{  talk: {    realtime: {      provider: "openai",      model: "<account-issued-realtime-model>",      transport: "webrtc",    },  },}

网关中继使用直接双向传输：

{  talk: {    realtime: {      provider: "openai",      model: "<account-issued-realtime-model>",      transport: "gateway-relay",    },  },}

浏览器 Talk 使用 transport: "webrtc"。

这些行描述了已实现的传输，而不是帐户权利或完整的模型功能奇偶校验。在为这些消费者选择未列出或私有路由之前，请参阅 Discord 语音策略限制 和 语音呼叫工具限制。

403 Voice session access denied 响应已过载，并且其本身并不能证明帐户权限问题：无效的语音会产生相同的响应。首先根据上面接受的列表验证模型和语音，然后根据同一项目验证平台密钥和配置的模型。

Codex GPT-Live 网关拥有的 WebRTC 路由首先使用 OAuth 和平台回退，通过配置的 OpenClaw 代理路由边带委派，并使凭据远离中继客户端。未列出或私有浏览器 WebRTC 和直接后端套接字仍然仅适用于平台。直接插座可实现Discord语音和语音Call/telephony； OpenClaw 将 G.711 u-law 电话音频与提供商的 24 kHz PCM 流进行转换。 Android 的客户端门保持关闭状态，直到网关中继路径收到来自 Android 设备的实时证明。

WebRTC 路径创建提供商呼叫并加入其边带。直接 unlisted/private 后端路径打开一个双向会话，发送无帧 session.update，然后通过该套接字传送 PCM 音频、转录、委托和委托结果。

维护人员可以通过选择加入实时测试来使用平台直接路径和单独的 GA 浏览器 OAuth 路径。从talk.realtime.model中读取账户发行的实时模型；缺少凭据或模型配置会产生经过净化的跳过，并且测试永远不会打印任一值：

OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_GPT_LIVE=1 node --import tsx scripts/test-live.mts -- extensions/openai/realtime-quicksilver.live.test.tsOPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_GPT_LIVE=1 node --import tsx scripts/test-live.mts -- extensions/openai/realtime-quicksilver-gateway-bridge.live.test.ts