Codex Reconnect Repair

If this Skill saves you from the five-reconnect wait, please ⭐ star the repository. It helps more Codex users find it.

A diagnosis-first Codex Skill for the repeated:

Reconnecting... 1/5
...
Reconnecting... 5/5

It identifies whether the affected Codex process has a WebSocket-only failure, a mismatched client environment, or a broader HTTP/auth/DNS/TLS problem. It changes configuration only when the evidence proves a bounded repair is appropriate.

中文说明

Why this exists

Current Codex releases can retry a failed Responses WebSocket stream five times before falling back to HTTPS/SSE. Many public workarounds disable WebSockets immediately, even when the real issue is a different desktop/IDE environment, proxy authentication, certificate trust, or broken HTTP connectivity.

This project takes a narrower approach:

  • read-only, redacted diagnostics by default;
  • exact affected-binary selection for CLI, desktop, IDE, remote, and container contexts;
  • native macOS system-proxy support when Codex itself recommends it;
  • HTTPS/SSE fallback only when HTTP works and WebSocket fails;
  • no hard-coded ChatGPT backend URL;
  • atomic writes, timestamped backups, strict validation, and hash-guarded rollback;
  • no global proxy, DNS, firewall, registry, launchctl, or shell-profile edits.

Requirements

  • Python 3.9 or newer
  • A Codex release with codex doctor --json for automatic classification
  • macOS, Linux, or Windows

Older Codex versions are diagnosed as an update/select-the-correct-binary prerequisite instead of being modified blindly.

Install as a Skill

macOS or Linux:

mkdir -p ~/.agents/skills
git clone https://github.com/9398-haha/codex-reconnect-repair.git \
  ~/.agents/skills/codex-reconnect-repair

PowerShell:

New-Item -ItemType Directory -Force "$HOME\.agents\skills" | Out-Null
git clone https://github.com/9398-haha/codex-reconnect-repair.git `
  "$HOME\.agents\skills\codex-reconnect-repair"

Restart Codex if the skill does not appear, then invoke:

Use $codex-reconnect-repair to diagnose and fix my Reconnecting 1/5 through 5/5 loop.

Use the diagnostic directly

Read-only diagnosis:

python3 scripts/codex_reconnect_repair.py diagnose --json

Preview the evidence-selected repair:

python3 scripts/codex_reconnect_repair.py repair --strategy auto

Apply it:

python3 scripts/codex_reconnect_repair.py repair --strategy auto --apply

Validate without a model request:

python3 scripts/codex_reconnect_repair.py verify --json

With explicit permission to consume one minimal account request:

python3 scripts/codex_reconnect_repair.py verify --live --json

Guarded rollback:

python3 scripts/codex_reconnect_repair.py rollback
python3 scripts/codex_reconnect_repair.py rollback --apply

On Windows, replace python3 with py -3 if needed.

What gets changed

The system-proxy strategy uses Codex's native features enable respect_system_proxy command on macOS, then verifies a new Doctor WebSocket check.

The http-fallback strategy activates this managed provider only for the built-in OpenAI provider:

model_provider = "codex-reconnect-http"

[model_providers."codex-reconnect-http"]
name = "OpenAI"
wire_api = "responses"
requires_openai_auth = true
supports_websockets = false
supports_standalone_web_search = true

The missing base_url is intentional: Codex derives the official endpoint from ChatGPT or API-key authentication. Every applied change creates a private backup under the effective CODEX_HOME/reconnect-repair/ directory.

Privacy and support

The helper reports environment variable names, never values. It does not read prompt/session files or print raw logs. Raw codex doctor --json can still contain local paths; do not paste it into a public issue. Use this helper's sanitized diagnose --json output and review it before posting.

See SECURITY.md before filing a security-sensitive report.

Upstream status

The underlying delayed fallback behavior is tracked in openai/codex#19821. This Skill should become more conservative as upstream Codex improves; it should not preserve obsolete workarounds indefinitely.

Development

python3 -m unittest discover -s tests -v
python3 -m py_compile scripts/codex_reconnect_repair.py

Licensed under the MIT License.