Codex keeps reconnecting 5/5: HTTP / Responses troubleshooting

Bottom line first

When Codex is stuck reconnecting, use this order: stop the old session → back up the user-level config.toml → use an HTTP / Responses provider → fully restart Codex → verify normal text first, then a minimal read-only tool call → resume the original task last.

The purpose is to separate model behavior from transport behavior. If a minimal HTTP request is not stable, do not start by changing prompts, choosing a more complex model, or replaying a long task.

What the symptom means

Reconnecting... 1/5
Reconnecting... 2/5
Reconnecting... 3/5
Reconnecting... 4/5
Reconnecting... 5/5
Thinking...

WebSocket is useful for real-time, long-lived interactions and tool calls, but it is more sensitive to proxies, network nodes, corporate firewalls, and intermediary gateways. When connection setup fails, the client may go through a retry and fallback sequence. Five reconnect attempts do not necessarily mean five rounds of deep model reasoning.

This is a troubleshooting hypothesis, not a confirmed root cause from terminal text alone. Confidence increases only when a provider or network change produces a clear before-and-after result for both normal and tool requests.

Fastest recovery path

1. Stop the Codex process stuck in reconnecting. Preserve the workspace; do not delete the project.
2. Find the user-level config.toml and check whether CODEX_HOME is set.
3. Back up the file and add a provider; do not delete the original configuration first.
4. Set the provider protocol to responses; use supports_websockets = false only if the installed version supports it.
5. Close the old Codex session and terminal completely.
6. Run one sentence test, then a read-only tool test.
7. Resume the original task only after both minimal tests pass.

Step 1: Find the user-level config.toml

Codex normally stores user configuration at ~/.codex/config.toml. If CODEX_HOME is set, use that directory instead. On Windows, the usual location is %USERPROFILE%\.codex\config.toml.

# macOS / Linux
printf '%s\n' "${CODEX_HOME:-$HOME/.codex}/config.toml"

# Windows PowerShell
if ($env:CODEX_HOME) {
  Join-Path $env:CODEX_HOME "config.toml"
} else {
  Join-Path $HOME ".codex/config.toml"
}

# You can also ask Codex to locate it without editing:
Locate the current Codex config.toml path and tell me only the path. Do not modify the file.

Step 2: Back up the configuration

Back up before editing. Also record the Codex version, selected profile, model, and network environment so a rollback has a clear before-and-after comparison.

# macOS / Linux
cp ~/.codex/config.toml ~/.codex/config.toml.bak

# Windows PowerShell
Copy-Item "$HOME\.codex\config.toml" "$HOME\.codex\config.toml.bak"

Step 3: Configure an HTTP / Responses provider

The source post gives an OpenAI / ChatGPT authentication provider example. Its main idea is to use the Responses protocol and avoid preferring the WebSocket path.

# OpenAI / ChatGPT authentication example from the source post
model_provider = "openai_http"

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

If you use Codex through a gpt88.cc API key, do not copy requires_openai_auth = true from the source post. Use env_key and the gpt88.cc compatible endpoint instead:

# gpt88.cc API key example
model = "YOUR_MODEL_ID"
model_provider = "gpt88_http"

[model_providers.gpt88_http]
name = "gpt88 HTTP / Responses"
base_url = "https://api.gpt88.cc"
env_key = "OPENAI_API_KEY"
wire_api = "responses"

# Add this only if your Codex version recognizes it:
# supports_websockets = false

# Set an API key for the current shell
export OPENAI_API_KEY="sk-your-gpt88-api-key"

# Windows PowerShell
$env:OPENAI_API_KEY = "sk-your-gpt88-api-key"

The value of model_provider must exactly match the provider id in [model_providers.<id>]. If the id is gpt88_http, do not write openai_http or chatgpt_http at the top.

Step 4: Restart and verify

Save the file, quit Codex and the terminal, open a new terminal, and start a fresh session. Do not continue only inside the old session; it may retain stale provider, connection, or failure context.

# Verify the Codex version after reopening the terminal
codex --version

# Start a fresh session
codex

# Start with a minimal test:
Reply with one sentence: Codex connection test passed.

# Then verify a read-only tool task:
List the files in the current directory. Only return file names; do not modify anything.

1. Normal text succeeds: authentication, model, and basic HTTP path are at least working.
2. Read-only tool succeeds: the Agent can receive a tool result without failing at the first tool turn.
3. The original task succeeds: the configuration is useful for your real workflow, not just a short smoke test.

API key, OAuth, and field choices

For the complete gpt88.cc Codex CLI setup, continue to Codex CLI with gpt88.cc. For ChatGPT plugins or OAuth, read Codex OAuth and plugin login.

Troubleshooting order

1. Check the version. Run codex --version. If it is old, upgrade using your current installation method; npm installations can use npm install -g @openai/codex@latest.
2. Confirm provider activation. Check that model_provider and the provider id match exactly, and that Codex is reading the intended CODEX_HOME.
3. Compare networks. Test another network, proxy node, or route. If failure is isolated to a corporate network, firewall, or specific node, focus on WebSocket and long-lived connection support.
4. Start a fresh session. Reopen the project and launch Codex again. A failed old session is not a valid test of the new provider.
5. Classify the error. 401 / 403 usually points to authentication or permission, 404 to Base URL or model, and 524 to a gateway that did not receive a usable upstream response in time. Use the complete error, timestamp, and request id for confirmation.
6. Check tools separately. If normal text works but tools fail, inspect shell, hooks, MCP, subprocesses, and tool recovery instead of attributing everything to WebSocket.

# 1. Confirm that the provider id matches exactly
model_provider = "gpt88_http"
[model_providers.gpt88_http]

# 2. Confirm which config directory is active
printf '%s\n' "${CODEX_HOME:-$HOME/.codex}/config.toml"

# 3. Check for stale overrides
env | grep -E '^(OPENAI_API_KEY|OPENAI_BASE_URL|CODEX_HOME)='

# 4. Upgrade Codex if npm is your installation method
npm install -g @openai/codex@latest

Rollback

If Codex reports a configuration parse error, model list issue, or worse connection behavior, restore the backup and restart. Rolling back the configuration does not undo files already written to the project; inspect those changes separately.

# macOS / Linux
cp ~/.codex/config.toml.bak ~/.codex/config.toml

# Windows PowerShell
Copy-Item "$HOME\.codex\config.toml.bak" "$HOME\.codex\config.toml"

After configuration recovery, run the minimal text test again. If text works but tools still fail, continue with Codex tool recovery and Windows Codex 524 and PowerShell 7.

Acceptance checklist

□ Record the original error, time, model, and network
□ Locate the user-level config.toml and check CODEX_HOME
□ Back up the original configuration
□ Make model_provider and the provider id match exactly
□ Set wire_api = "responses"
□ Use env_key for the gpt88 API key path; do not mix it with requires_openai_auth
□ Verify supports_websockets against the installed Codex version
□ Fully close the old session and restart Codex
□ Confirm a normal text request
□ Confirm a minimal read-only tool request
□ Check workspace changes before resuming the original task

Sources and references

• Source X article: Codex keeps reconnecting 5/5 — summarized here with the gpt88 API key boundary added.
• Codex Config basics — official configuration layers and provider overview.
• Codex Advanced Config — custom providers, Base URL, authentication, and Responses examples.
• Codex Configuration Reference — current config.toml fields and version-sensitive checks.

Next steps

• Codex CLI with gpt88.cc: complete API key, model, and file-tool setup.
• Codex tool recovery: confirm tool state and restart implementation from step one.
• Windows Codex 524 and PowerShell 7: continue shell, encoding, and stream troubleshooting.