docs: clarify OpenAI WS mode router prerequisite

README.md

@@ -639,8 +639,20 @@ override this limit.
 The connection cap is coordinated through Redis using a 60-second lease that
 is refreshed every 20 seconds. A process that cannot confirm a lease for a
 full lease lifetime closes its local WebSocket rather than continuing outside
-the global cap. Use `http_bridge` for client-WebSocket/upstream-HTTP operation
-when rolling out or mitigating upstream WebSocket issues.
+the global cap.
+
+Enable the v2 mode router before selecting an account-level WS mode such as
+`http_bridge`:
+
+```yaml
+gateway:
+  openai_ws:
+    mode_router_v2_enabled: true
+```
+
+Or set `GATEWAY_OPENAI_WS_MODE_ROUTER_V2_ENABLED=true` in the environment.
+Use `http_bridge` for client-WebSocket/upstream-HTTP operation when rolling out
+or mitigating upstream WebSocket issues.
 
 #### ⚠️ Important: Creating the Admin Account
 

deploy/config.example.yaml

@@ -261,9 +261,10 @@ gateway:
   openai_compact_model: "gpt-5.4"
   # OpenAI Responses WebSocket 配置（默认开启，可按需回滚到 HTTP）
   openai_ws:
-    # 新版 WS mode 路由（默认关闭）。关闭时保持当前 legacy 实现行为。
+    # 新版 WS mode 路由（默认关闭）。关闭时忽略账号级 WS mode（包括 http_bridge），保持 legacy ctx_pool 行为。
+    # 环境变量：GATEWAY_OPENAI_WS_MODE_ROUTER_V2_ENABLED=true
     mode_router_v2_enabled: false
-    # ingress 默认模式：off|ctx_pool|passthrough|http_bridge（仅 mode_router_v2_enabled=true 生效）
+    # ingress 默认模式：off|ctx_pool|passthrough|http_bridge（仅 mode_router_v2_enabled=true 生效；关闭时账号级 WS mode 被忽略）
     # 兼容旧值：shared/dedicated 会按 ctx_pool 处理。
     ingress_mode_default: ctx_pool
     # 完整读取并解压首条客户端消息的总超时（秒）；大请求或慢链路可调高到 120-300。

frontend/src/i18n/__tests__/wsModeLocaleDesc.spec.ts

@@ -0,0 +1,13 @@
+import { describe, expect, it } from 'vitest'
+
+import en from '../locales/en/admin/accounts'
+import zh from '../locales/zh/admin/accounts'
+
+describe('OpenAI WS mode locale descriptions', () => {
+  it('documents the global v2 router requirement for account WS modes', () => {
+    expect(zh.accounts.openai.wsModeDesc).toContain('mode_router_v2_enabled')
+    expect(zh.accounts.openai.wsModeDesc).toContain('http_bridge')
+    expect(en.accounts.openai.wsModeDesc).toContain('mode_router_v2_enabled')
+    expect(en.accounts.openai.wsModeDesc).toContain('http_bridge')
+  })
+})

frontend/src/i18n/locales/en/admin/accounts.ts

@@ -439,7 +439,8 @@ export default {
         responsesWebsocketsV2Desc:
           'Disabled by default. Enable to allow responses_websockets_v2 capability (still gated by global and account-type switches).',
         wsMode: 'WS mode',
-        wsModeDesc: 'Only applies to the current OpenAI account type.',
+        wsModeDesc:
+          'Only applies to the current OpenAI account type; account WS modes, including http_bridge, take effect only when the global gateway.openai_ws.mode_router_v2_enabled=true.',
         wsModeOff: 'Off (off)',
         wsModeCtxPool: 'Context Pool (ctx_pool)',
         wsModePassthrough: 'Passthrough (passthrough)',

frontend/src/i18n/locales/zh/admin/accounts.ts

@@ -543,7 +543,8 @@ export default {
         responsesWebsocketsV2Desc:
           '默认关闭。开启后可启用 responses_websockets_v2 协议能力（受网关全局开关与账号类型开关约束）。',
         wsMode: 'WS mode',
-        wsModeDesc: '仅对当前 OpenAI 账号类型生效。',
+        wsModeDesc:
+          '仅对当前 OpenAI 账号类型生效；包括 http_bridge 在内的账号 WS mode 仅在全局 gateway.openai_ws.mode_router_v2_enabled=true 时生效。',
         wsModeOff: '关闭（off）',
         wsModeCtxPool: '上下文池（ctx_pool）',
         wsModePassthrough: '透传（passthrough）',