codex - 💡(How to fix) Fix Codex Doctor Responses WebSocket timeout on macOS when DNS prefers IPv6; disabling IPv6 makes handshake succeed [1 comments, 2 participants]

What version of Codex CLI is running?

codex-cli 0.131.0

What subscription do you have?

ChatGPT account auth. Exact plan is not material to the network failure, but I can provide it privately if useful.

Which model were you using?

gpt-5.5

What platform is your computer?

Darwin 25.4.0 arm64 arm

Additional macOS version detail:

ProductName: macOS
ProductVersion: 26.4.1
BuildVersion: 25E253

What terminal emulator and version are you using (if applicable)?

Apple Terminal 470. No tmux/screen/zellij in the reported codex doctor run.

Codex doctor report

Current post-workaround codex doctor --json excerpt, redacted to remove local paths while preserving the network and WebSocket fields:

{
  "schemaVersion": 1,
  "overallStatus": "ok",
  "codexVersion": "0.131.0",
  "websocket": {
    "id": "network.websocket_reachability",
    "category": "websocket",
    "status": "ok",
    "summary": "Responses WebSocket handshake succeeded",
    "details": {
      "DNS": "2 IPv4, 0 IPv6, first IPv4",
      "auth mode": "chatgpt",
      "connect timeout": "15000 ms",
      "endpoint": "wss://chatgpt.com/backend-api/<redacted>",
      "handshake result": "HTTP 101 Switching Protocols",
      "model provider": "openai",
      "provider name": "OpenAI",
      "proxy env vars": "none",
      "supports websockets": "true",
      "wire API": "responses"
    }
  },
  "reachability": {
    "id": "network.provider_reachability",
    "category": "reachability",
    "status": "ok",
    "summary": "active provider endpoints are reachable over HTTP",
    "details": {
      "ChatGPT base URL": "https://chatgpt.com/backend-api/ reachable (HTTP 403)",
      "reachability mode": "ChatGPT auth"
    }
  },
  "network_env": {
    "id": "network.env",
    "category": "network",
    "status": "ok",
    "summary": "network-related environment looks readable",
    "details": {
      "proxy env vars": "none"
    }
  },
  "terminal": {
    "id": "terminal.env",
    "category": "terminal",
    "status": "ok",
    "details": {
      "TERM_PROGRAM": "Apple_Terminal",
      "terminal": "Apple Terminal",
      "terminal version": "470",
      "effective locale": "pt_BR.UTF-8"
    }
  },
  "config": {
    "status": "ok",
    "summary": "config loaded",
    "details": {
      "model": "gpt-5.5",
      "model_provider": "openai",
      "cwd": "<redacted>",
      "mcp_servers": "10"
    }
  }
}

The failing pre-workaround codex doctor --all output was captured before disabling IPv6:

Connectivity
  network      no proxy env vars
  websocket    Responses WebSocket timed out; HTTPS fallback may still work
      model provider           openai
      provider name            OpenAI
      wire API                 responses
      supports websockets      true
      proxy env vars           none
      connect timeout          15000 ms
      auth mode                chatgpt
      endpoint                 wss://chatgpt.com/backend-api/<redacted>
      DNS                      2 IPv4, 2 IPv6, first IPv6
    - handshake timed out
  reachability active provider endpoints are reachable over HTTP
      ChatGPT base URL         https://chatgpt.com/backend-api/ reachable

What issue are you seeing?

codex doctor --all reports the Responses WebSocket probe as degraded when the local network presents IPv6 first for chatgpt.com, even though HTTP reachability to the same ChatGPT backend is OK and the same probe succeeds immediately after disabling IPv6 on the Wi-Fi service.

This does not look like a generic outage, auth problem, proxy problem, or project-local issue. It looks like the Codex Responses WebSocket connect path can get stuck on an unreliable IPv6 route and does not fall back to IPv4 quickly enough for the chatgpt.com/backend-api WebSocket probe.

A longer connect timeout did not fix it. I tested a custom provider override equivalent to the ChatGPT backend with:

websocket_connect_timeout_ms = 60000

The WebSocket probe still timed out after 60s against wss://chatgpt.com/backend-api/<redacted> with DNS: 2 IPv4, 2 IPv6, first IPv6.

Network sanity checks:

networksetup -getproxyautodiscovery Wi-Fi
Auto Proxy Discovery: Off

scutil --proxy
HTTPEnable: 0
HTTPSEnable: 0
ProxyAutoDiscoveryEnable: 0

IPv4 connectivity to chatgpt.com was fast:

curl -4 https://chatgpt.com/backend-api/
remote=172.64.155.209
connect about 0.08s, appconnect about 0.16s, total about 0.25s

The IPv6 path was inconsistent. Direct socket tests showed the IPv4 addresses connecting quickly, while at least one returned IPv6 address timed out during TCP connect:

v6 2a06:98c1:3100::6812:202f ok about 0.07s
v6 2a06:98c1:310b::ac40:9bd1 timeout about 5s
v4 172.64.155.209 ok about 0.06s
v4 104.18.32.47 ok about 0.07s

As a control, a custom provider pointed at api.openai.com reached the WebSocket endpoint and failed with an expected auth/scope HTTP 401. That was not a workaround, but it suggests local WebSocket support itself was not globally blocked by the OS or network.

What steps can reproduce the bug?

On a macOS machine/network where chatgpt.com resolves to both A and AAAA records and Codex Doctor reports first IPv6:

1. Ensure Wi-Fi IPv6 is automatic/enabled.
2. Confirm no proxy env vars are set and no macOS HTTP/HTTPS proxy is active.
3. Run:

codex doctor --all

1. Observe the degraded WebSocket probe:

Responses WebSocket timed out
endpoint: wss://chatgpt.com/backend-api/<redacted>
DNS: 2 IPv4, 2 IPv6, first IPv6
handshake timed out

1. Disable IPv6 for the active Wi-Fi network and flush DNS:

networksetup -setv6off Wi-Fi
dscacheutil -flushcache
killall -HUP mDNSResponder

1. Run:

codex doctor --summary --no-color

1. Observe the WebSocket probe succeed:

websocket: connected (HTTP 101 Switching Protocols) - 15s timeout
DNS: 2 IPv4, 0 IPv6, first IPv4
13 ok, 1 idle, 1 notes, 0 warn, 0 fail

What is the expected behavior?

Codex should not require users to disable IPv6 at the OS/network-service level to make the default ChatGPT-auth Responses WebSocket path pass codex doctor.

Expected behavior would be one of:

• use Happy Eyeballs or equivalent IPv4 fallback for the Responses WebSocket connect path;
• retry the WebSocket probe against a working IPv4 address when the first IPv6 route stalls;
• expose a supported user-facing force IPv4, prefer HTTP, or disable Responses WebSocket option for environments with broken IPv6/WebSocket routing;
• make codex doctor distinguish "IPv6 route timed out before IPv4 fallback" from a generic WebSocket failure.

Additional information

With IPv6 enabled on this Wi-Fi network, the ChatGPT Responses WebSocket probe timed out and remained degraded even with a 60s WebSocket connect timeout.

With IPv6 disabled on the same Wi-Fi network, the same Codex install/auth/config immediately reports a successful WebSocket handshake with HTTP 101 Switching Protocols.

There are older issues around WebSocket fallback and IPv4 forcing, but this is a current 0.131.0 macOS reproduction using codex doctor, not an older Windows-only reconnect-loop report:

• #19525 reports IPv6 unavailable / relay / VPN cases on older Codex CLI versions.
• #16768 requests a force-IPv4 flag mainly for Windows.
• #19821 covers broader delayed HTTP fallback when Responses WebSocket connect fails.

I am intentionally not attaching full local logs because they contain unrelated local paths and private workspace context. The relevant codex doctor output above is redacted to the same level as --json redaction and should be sufficient to identify the network/probe behavior.