故障排除
OpenAI Agents SDK 支持以下服务器环境:
- Node.js 22+
- Deno 2.35+
- Bun 1.2.5+
- Cloudflare Workers:Agents SDK 可在 Cloudflare Workers 中使用,但目前存在一些限制:
- SDK 目前要求启用
nodejs_compat - 需要在请求结束时手动刷新追踪数据。更多详情请参阅追踪。
- 由于 Cloudflare Workers 对
AsyncLocalStorage的支持有限,某些追踪可能不准确 - 出站 WebSocket 连接必须使用基于 fetch 的协议升级方式(而非全局
WebSocket构造函数)。对于 Realtime,请使用@openai/agents-extensions中的 Cloudflare 传输层(CloudflareRealtimeTransportLayer)。
- SDK 目前要求启用
- Responses API WebSocket 传输:
- 需要全局
WebSocket实现。 WebSocket实现必须支持在握手时使用自定义请求头。- 许多浏览器风格的 WebSocket API(以及某些边缘运行时)不支持自定义出站请求头。在这些环境中,请改用默认的 HTTP Responses 传输。
- 如果错误提示缺少全局
WebSocket实现或不支持自定义请求头,则表明该运行时的 WebSocket 实现与 Responses WebSocket 传输不兼容。
- 需要全局
- 浏览器:
- 核心 SDK 可以打包供浏览器使用,但在浏览器中默认禁用追踪。
- React Native:
@openai/agents-core和@openai/agents-realtime提供了 React Native 包条件,用于加载可移植的兼容层,但内置的OpenAIRealtimeWebRTC仍仅限浏览器使用。- Realtime 应用必须自行提供基于原生 WebRTC 实现(如
react-native-webrtc)的传输层,且仍需自行负责权限、音频路由和传输生命周期的管理。 - Expo Go 无法加载原生 WebRTC 模块。请使用 Expo 开发构建或原生 React Native 项目。请参阅
examples/realtime-react-native代码示例。
- v8 隔离实例:
- 使用带有适当浏览器 polyfill 的打包工具时,应该可以为 v8 隔离实例打包 SDK,但追踪功能将无法使用
- v8 隔离实例尚未经过广泛测试
如果您在使用 SDK 时遇到问题,可以启用调试日志,获取有关运行情况的更多信息。
将 DEBUG 环境变量设为 openai-agents:* 即可启用调试日志。
DEBUG=openai-agents:*默认情况下,模型和工具数据仍会被隐藏。如果需要这些详细信息,请参阅日志中的敏感数据,并仅在日志得到安全处理的环境中选择启用。
您也可以将调试范围限定为 SDK 的特定部分:
openai-agents:core— SDK 的主要执行逻辑openai-agents:openai— OpenAI API 调用openai-agents:realtime— 语音智能体组件