在构建基于 OpenAI Realtime API 的语音对话应用时，WebRTC 连接失败是最令开发者头疼的问题之一。与普通的网络超时不同，ICE（Interactive Connectivity Establishment）超时往往表现为连接状态长时间停留在「checking」阶段，最终以失败告终。更棘手的是，这类故障往往没有明确的错误信息，开发者只能看到 ICE 候选交换受阻，却难以定位根因。本文将以 2025 年 3 月 OpenAI 引入的一次隐性破坏性变更为例，分析 ICE 超时的典型故障模式，并给出可落地的参数配置与监控方案。
ICE 超时的典型表现与诊断要点
当 WebRTC 连接建立过程中出现问题时，首先需要理解 ICE 协商的核心流程。ICE 协议的核心任务是为主动端和被动端分别收集候选地址（candidate），并通过信令通道交换这些地址，最终尝试建立一条可用的传输路径。这个过程涉及三个关键阶段：候选收集（gathering）、候选交换（exchanging）和连通性检查（checking）。
在实际生产环境中，ICE 超时通常表现为以下几种状态序列：连接状态从「new」转为「checking」后，长时间停留在 checking 状态，最终转为「failed」；或者 ICE 候选收集完成后，候选列表为空或仅有主机候选（host candidate），无法形成有效的传输路径。这种情况的根因往往不在客户端代码本身，而在于网络环境配置或会话创建参数存在缺陷。
诊断时应当重点关注以下几个技术指标：ICE 连接状态机当前所处阶段、已收集的候选类型与数量、ICE 服务器配置是否正确生效、以及信令通道是否完整传输了 SDP（Session Description Protocol）offer/answer。当连接状态在 checking 阶段停留超过 15 秒仍未过渡到 connected 时，即可判定为 ICE 超时。
根因剖析：turn_detection 参数的空值陷阱
2025 年 3 月中旬，大量开发者在社区反馈其 OpenAI Realtime API WebRTC 连接突然失效。问题的典型表现是：客户端代码未做任何修改，前一天还能正常工作的语音对话功能，第二天开始连接始终停留在 checking 阶段并最终失败。经过社区的深入排查，最终定位的根因令人意外：问题并非来自网络或服务端变更，而是源自一次 silent breaking change——OpenAI 修改了会话创建 API 对 turn_detection 参数的校验逻辑。
在 OpenAI Realtime API 中，turn_detection 参数用于控制语音激活检测（VAD）的行为。当开发者需要手动控制音频输入时，通常会将其设置为 null 或某个配置对象。许多开发者按照 JavaScript 的惯例，认为 null 表示「不设置该项」，因此在代码中显式传入 turn_detection: null。然而，OpenAI 在此次更新后，对 null 和 undefined 作出了区分处理：传入 undefined 时，API 会采用默认的服务器端 VAD 配置；传入 null 时，API 虽然仍能成功创建会话，但该会话的内部配置存在缺陷，导致后续 WebRTC 连接阶段的 ICE 协商无法完成。
这个问题的隐蔽性在于：会话创建 API 调用本身会返回成功的响应，开发者无法从会话创建的返回值中察觉任何异常。问题只有在实际建立 WebRTC 连接时才会暴露，表现为 ICE 状态长时间停留在 checking 阶段。这是因为服务端为 null 配置生成的会话元数据缺少了必要的 TURN 服务器信息或候选复用策略，导致客户端无法完成候选交换和连通性检查。
修复方案与配置参数清单
解决这一问题的直接方法是改用 undefined 而非 null。在 JavaScript 中，这两个空值类型在 API 交互中具有不同的语义：显式传入 undefined 表示「使用默认值」，而 null 则表示「显式设置为空」。这一细微差别在许多 Web API 中存在，但在 OpenAI Realtime API 中产生了实际的连接故障。
推荐的生产级配置模式如下：首先，对于需要服务器端 VAD 的场景，直接省略 turn_detection 字段或显式传入 undefined；其次，对于需要手动控制音频的场景，传入完整的配置对象，例如 turn_detection: { mode: 'server_vad', threshold: 0.5, prefix_padding_ms: 500, silence_duration_ms: 200 }。避免使用 null 作为占位符。
除了修复 turn_detection 参数问题外，生产环境中的 WebRTC 连接稳定性还依赖于以下配置参数：合理的 ICE 服务器配置、连接超时阈值设置、以及完善的状态监控机制。
生产环境的监控与回滚策略
在生产环境中，建议实现多层次的 ICE 连接状态监控，以便在故障早期发出告警。核心监控指标包括：ICE 连接状态机转换日志（重点关注 failed 和 disconnected 状态）、ICE 候选收集完成时间（正常应在 3 秒内完成）、从会话创建到 WebRTC 连接成功的时间差（通常不应超过 10 秒）、以及单位时间内的连接失败率。
对于已上线的应用，建议在客户端代码中加入参数兼容逻辑：当检测到 turn_detection 值为 null 时，自动将其转换为 undefined，并记录一次警告日志。这种防御性编程可以在服务端配置发生变更时提供向后兼容性，避免因细微的参数差异导致服务中断。
综上所述，OpenAI Realtime API 的 ICE 超时问题提醒我们：在使用云服务的实时通信功能时，不仅要关注网络层面的连通性，还要留意 API 参数的语义细节。空值类型的差异、配置对象的完整性、以及服务端协议的隐性变更，都可能成为影响服务可用性的关键因素。
资料来源：OpenAI Developer Community 论坛中关于 Realtime API WebRTC 连接失败的技术讨论。
内容声明：本文无广告投放、无付费植入。
如有事实性问题，欢迎发送勘误至 i@hotdrydog.com。