𝐗𝐀𝐈

XAI Router 已支持 OpenAI WebSocket Mode：与官方语义对齐说明

Posted February 24, 2026 by XAI 技术团队 ‐ 6 min read

本文是 XAI Router WebSocket 能力的工程说明。 截至 2026-02-24，XAI Router 已完成对 OpenAI WebSocket 相关能力的统一支持，重点覆盖：

  1. POST /v1/responses 对应的 WebSocket mode（wss://.../v1/responses）
  2. wss://.../v1/realtime 实时会话
  3. 与现有 HTTP 转发体系共存，不改变原有 HTTP API 行为

先看 OpenAI 官方语义（WebSocket Mode）

根据 OpenAI 官方文档，Responses 的 WebSocket mode 关键点是：

  1. 保持持久连接到 /v1/responses
  2. 每一轮通过 response.create 发起
  3. 使用 previous_response_id + 增量 input 持续对话
  4. 单连接为顺序执行：一次仅允许一个 in-flight response（不支持 multiplexing）
  5. 连接时长上限 60 分钟，超时后需要重连

XAI Router 对齐策略

1) 路径兼容

XAI Router 同时支持这两组路径，便于不同客户端接入：

  • /v1/responses 与 /responses
  • /v1/realtime 与 /realtime

2) 官方语义对齐

在 /v1/responses WebSocket 模式下，XAI Router 采用与官方一致的顺序语义：

  • 连接内允许多次 response.create
  • 但严格“一个在途请求完成后再发下一个”
  • 并发发送多个 response.create 会被拒绝

这与 OpenAI 官方文档中“单连接顺序执行、无 multiplexing”保持一致。

3) 状态与续接

previous_response_id、增量 input、store=false 等字段均按事件透传路径处理； XAI Router 不改写这类会话语义字段，只在必要位置做模型映射、鉴权、限流与计费。

架构实现（统一框架）

本次实现不是单点补丁，而是将 WebSocket 统一到同一框架：

  1. ws_framework：统一会话、转发、超时、错误处理、连接收敛
  2. openai-responses-ws 适配器：处理 response.create 生命周期、turn 绑定、usage 采集
  3. openai-realtime-ws 适配器：处理 realtime 事件流与会话计费

同时将原有 /v1/realtime 迁移到同一框架内，减少分叉逻辑，降低后续维护复杂度。

XAI Router OpenAI WebSocket 对齐架构图

上图对应统一 WebSocket 框架的核心思路：在保持 OpenAI 官方语义的前提下，把 Responses 与 Realtime 都收敛到同一会话与转发模型。

最小调用示例（Responses WebSocket）

下面示例通过 XAI Router 使用 gpt-5.4 发起一轮 response.create：

from websocket import create_connection
import json
import os

ws = create_connection(
    "wss://api.xairouter.com/v1/responses",
    header=[
        f"Authorization: Bearer {os.environ['XAI_API_KEY']}",
    ],
)

ws.send(json.dumps({
    "type": "response.create",
    "model": "gpt-5.4",
    "store": False,
    "input": [
        {
            "type": "message",
            "role": "user",
            "content": [{"type": "input_text", "text": "请用一句话总结 websocket mode。"}]
        }
    ],
    "tools": []
}))

while True:
    event = json.loads(ws.recv())
    print(event.get("type"))
    if event.get("type") in ("response.completed", "response.failed", "response.incomplete"):
        break

ws.close()

Codex CLI 配置（参考基线）

如果你用 Codex CLI 走 XAI Router，下面这份是一份可直接工作的参考基线配置：

model_provider = "xai"
model = "gpt-5.4"
model_reasoning_effort = "xhigh"
plan_mode_reasoning_effort = "xhigh"
model_reasoning_summary = "none"
model_verbosity = "medium"
approval_policy = "never"
sandbox_mode = "danger-full-access"

[model_providers.xai]
name = "OpenAI"
base_url = "https://api.xairouter.com"
wire_api = "responses"
requires_openai_auth = false
env_key = "XAI_API_KEY"

说明：

  1. 这份配置可作为 ~/.codex/config.toml 的参考基线。
  2. 旧版本示例里出现过 supports_websockets 与 responses_websockets_v2 开关；如果你的 Codex 版本仍显式暴露这些选项，再按对应版本文档追加即可。
  3. env_key = "XAI_API_KEY" 只告诉 Codex 去读取哪个环境变量；建议 Linux 写入 ~/.bashrc、macOS 优先写入 ~/.zshrc、Windows 写入用户环境变量后再重开终端。部分较老的 macOS、旧终端或某些 IDE 会话如果仍走 bash 登录环境，除了 ~/.zshrc 外，最好再同步写入 ~/.bash_profile，必要时也补到 ~/.bashrc。
  4. 修改后请重启 Codex 会话，使新配置完整生效。

性能与稳定性说明

在保持功能不变前提下，XAI Router 对 WS 路径做了几项工程化优化：

  1. 高频事件先做轻量字段预判，再进入完整 JSON 解析
  2. 复用统一转发框架，减少重复逻辑与状态分叉
  3. 连接异常日志做降噪，保留握手阶段关键错误，减少无意义噪音

实际效果是：在不影响原 HTTP 主流程的前提下，WS 路径更可维护、行为更稳定。

结语

如果你正在做多轮工具调用、Agent 编排或低延迟长链路任务， /v1/responses 的 WebSocket mode 会比“每轮 HTTP 重建上下文”更合适。

XAI Router 的目标不是“再包一层”，而是： 在保持 OpenAI 官方语义的同时，把多 key、鉴权、限流、计费、路由和稳定性做到工程可用。

参考来源