Document the WebSocket responses opt-out

[1fanwang]

Why

Models that advertise a WebSocket responses endpoint use it by default. When that transport is unusable, either because the network blocks WebSocket connections or because a session starts failing with 400 input item ID does not belong to this connection, there is a working escape hatch, but nothing user-facing points to it.

COPILOT_CLI_DISABLE_WEBSOCKET_RESPONSES is not listed in copilot help environment and is not in the README. The only public description lives in an SDK type comment, which CLI users do not read. People hitting this are left changing models by trial and error, and switching between two models that both use the transport appears to do nothing.

Related: #4505

What changed

A short subsection under Using the CLI naming the variable, the two situations it addresses, and its relationship to the SDK session option.

Testing

Ran the same prompt with and without the variable under --log-level debug, in an isolated home directory, and counted use of the WebSocket responses network module.

Raw logs

$ export COPILOT_HOME=$(mktemp -d)
$ L=$(mktemp -d); L2=$(mktemp -d)

$ copilot --log-level debug --log-dir "$L" --model gpt-5.6-sol -p 'say OK'
$ grep -c 'Opening WebSocket responses connection' "$L"/*.log
1
$ grep -oE 'network::[a-z_]+' "$L"/*.log | sort | uniq -c
   3 network::websocket_responses

$ COPILOT_CLI_DISABLE_WEBSOCKET_RESPONSES=true \
    copilot --log-level debug --log-dir "$L2" --model gpt-5.6-sol -p 'say OK'
$ grep -c 'Opening WebSocket responses connection' "$L2"/*.log
0
$ grep -oE 'network::[a-z_]+' "$L2"/*.log | sort | uniq -c
(no matches)

$ copilot help environment | grep -c COPILOT_CLI_DISABLE_WEBSOCKET_RESPONSES
0

Repeating the second run with --model gpt-5.6-terra also reported zero
WebSocket responses connections.

[Copilot]

🟡 Changes recommended

Clarify the inverse SDK option and add PowerShell instructions.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Documents disabling WebSocket responses to fall back to HTTP.

Changes:

• Adds the opt-out environment variable.
• Explains relevant failure scenarios and SDK configuration.

File summaries

File	Description
README.md	Documents HTTP fallback configuration for WebSocket response failures.

Review details

• Files reviewed: 1/1 changed files
• Comments generated: 2
• Review effort level: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.