fixing-codex-websocket-reconnect

name	fixing-codex-websocket-reconnect
description	Use when Codex repeatedly shows "Reconnecting... 2/5" through "5/5", WebSocket connection attempts fail before HTTP fallback, or the user wants to force the Responses API to use HTTP only.

Fixing Codex WebSocket Reconnect

Goal

Diagnose repeated startup reconnects and, when WebSocket transport is the cause, configure a dedicated HTTP-only OpenAI provider without disturbing unrelated Codex settings.

Workflow

1. Locate the active global config, normally ~/.codex/config.toml. Respect CODEX_HOME when set.
2. Read the complete config before editing. Check for existing model_provider and [model_providers.*] entries.
3. Record the installed version with codex --version. Prefer current official Codex configuration documentation for field semantics when available.
4. Run TERM=xterm-256color codex doctor --summary --ascii before editing when practical. Do not assume every reconnect is a WebSocket problem.
5. If Doctor or logs indicate Responses WebSocket failures followed by HTTP fallback, add an HTTP-only provider.

Keep root-level keys before the first table header:

model_provider = "openai_http"

[model_providers.openai_http]
name = "OpenAI HTTP only"
wire_api = "responses"
requires_openai_auth = true
supports_websockets = false

If openai_http already exists, update it instead of duplicating the table. If that name belongs to a different provider, choose a unique name and make model_provider match it.

6. Preserve the user's model, reasoning effort, notification command, projects, plugins, MCP servers, feature flags, and other unrelated settings.
7. Run TERM=xterm-256color codex doctor --summary --ascii after editing.

Success Criteria

Require all of the following:

• Configuration: config loaded
• Connectivity: Responses WebSocket is not enabled for the active provider
• Connectivity: active provider endpoints are reachable over HTTP
• Doctor reports no configuration or connectivity failure

Tell the user to restart Codex or start a new session so the provider change takes effect.

Guardrails

• Do not disable WebSockets before confirming the symptom or explicit user preference.
• Do not overwrite the whole config to add five lines.
• TOML table scope continues until another table header. A root key placed after [model_providers.openai_http] becomes part of that provider table. Keep keys such as notify above the provider table.
• A TERM=dumb Doctor failure concerns terminal capabilities, not provider connectivity. Re-run with TERM=xterm-256color.
• If HTTP reachability also fails, investigate proxy, DNS, TLS, authentication, firewall, or endpoint configuration instead of claiming this change fixed the issue.