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.

$ 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.