opensource/coder
3
0
Fork 0
mirror of https://github.com/coder/coder.git synced 2026-09-24 15:04:27 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: add Codex WebSocket fallback troubleshooting (#26565)

Browse Source 
## 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.
This commit is contained in:
Danny Kopping
2026-06-22 11:56:58 +02:00
committed by GitHub
parent 8b970e7ff3
commit 4f8acfaeff
1 changed files with 32 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/ai-coder/ai-gateway/clients/codex.md
+32 -1
View File
@@ -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)