From 4f8acfaeffde7f18891e3ec362a365b2a8e1459a Mon Sep 17 00:00:00 2001
From: Danny Kopping <danny@coder.com>
Date: Mon, 22 Jun 2026 11:56:58 +0200
Subject: [PATCH] docs: add Codex WebSocket fallback troubleshooting (#26565)

## Summary

Adds a Troubleshooting section to the Codex CLI AI Gateway client docs
covering the WebSocket-to-HTTPS transport fallback.

Recent Codex CLI versions default to the WebSocket runtime for the
Responses API. AI Gateway does not support WebSocket transport, so each
request attempts a WebSocket connection, fails, and falls back to HTTPS,
surfacing:

```text
Falling back from WebSockets to HTTPS transport.
```

The doc explains the cause and the fix: set `supports_websockets =
false` in the `[model_providers.ai_gateway]` block in
`~/.codex/config.toml` to force HTTPS directly and remove the fallback
delay.

Closes
[AIGOV-453](https://linear.app/codercom/issue/AIGOV-453/document-codex-cli-websocket-fallback-workaround).

<details>
<summary>Note on the config value</summary>

The original request and the Linear issue referenced enabling websocket
support / `support_websockets = false`. The authoritative Codex CLI
[config reference](https://developers.openai.com/codex/config-reference)
confirms:

- The key is `supports_websockets` (trailing "s").
- It declares whether a provider supports the Responses API WebSocket
transport.
- Setting it to `false` is the documented workaround to force HTTPS and
stop the fallback attempts.

Since AI Gateway does not support WebSockets, `supports_websockets =
false` is the correct value. `= true` would assert support that does not
exist and keep the fallback happening.

</details>

---

This PR was generated by Coder Agents on behalf of @dannykopping.
---
 docs/ai-coder/ai-gateway/clients/codex.md | 33 ++++++++++++++++++++++-
 1 file changed, 32 insertions(+), 1 deletion(-)

diff --git a/docs/ai-coder/ai-gateway/clients/codex.md b/docs/ai-coder/ai-gateway/clients/codex.md
index 81a494ce06..c9e3b22788 100644
--- a/docs/ai-coder/ai-gateway/clients/codex.md
+++ b/docs/ai-coder/ai-gateway/clients/codex.md
@@ -141,4 +141,35 @@ Do not set `OPENAI_API_KEY` in the workspace when using the ChatGPT
 subscription flow, or Codex authenticates with the API key instead of
 the ChatGPT login.
 
-**References:** [Codex CLI Configuration](https://developers.openai.com/codex/config-advanced)
+## Troubleshooting
+
+### Codex falls back from WebSockets to HTTPS transport
+
+Recent Codex CLI versions default to the WebSocket runtime for the
+Responses API. AI Gateway does not support WebSocket transport, so each
+request attempts a WebSocket connection and retries up to 5 times before
+falling back to HTTPS. When this happens you will see:
+
+```text
+Falling back from WebSockets to HTTPS transport.
+```
+
+The requests still succeed over HTTPS, but every turn waits through the
+five failed WebSocket attempts first.
+
+To stop Codex from attempting WebSockets, set `supports_websockets = false`
+in your AI Gateway provider block in `~/.codex/config.toml`:
+
+```toml
+model_provider = "ai_gateway"
+
+[model_providers.ai_gateway]
+name = "AI Gateway"
+base_url = "<your-deployment-url>/api/v2/aibridge/openai/v1"
+wire_api = "responses"
+supports_websockets = false
+```
+
+This forces the HTTPS transport directly and removes the fallback delay.
+
+**References:** [Codex CLI Configuration](https://developers.openai.com/codex/config-reference)