Codex 连不上网怎么排查:codex doctor --network-only 实测(2026)
Codex CLI 一直转圈、报连接错误,或者浏览器能打开网页它却连不上——以前只能靠猜。0.166 版(2026-10-29)起 Codex 自带了一个网络诊断命令 codex doctor --network-only,几秒钟就能告诉你是代理、证书还是接口地址的问题。
这篇是我在 Windows 11 上用 Codex 0.169.0 实测的:故意把代理、证书、接口地址弄错,看它分别怎么报,以及每种报错该怎么改。测试时没有登录账号,下面的输出都是真实输出,只把本机路径换成了 <你的用户名>。
先说结论
| doctor 里看到的 | 多半是 | 怎么办 |
|---|---|---|
[XX] reachability + connect failed | 代理环境变量指向了一个不存在的代理 | 改对或删掉 HTTPS_PROXY,或者用 NO_PROXY 排除 |
[XX] reachability + request timed out | 接口地址写错 / 被防火墙拦 | 检查 config.toml 里的 base_url |
[!!] network custom CA env var points at an unreadable path | 证书变量指向的文件不存在 | 改对 CODEX_CA_CERTIFICATE 的路径 |
[!!] websocket + http 401 | 还没登录,不是网络问题 | 先 codex login |
浏览器能上、Codex 不行,respect system proxy disabled | 你的代理是 Windows 系统代理,Codex 默认不读 | 打开实验功能 respect_system_proxy |
第一步:升级到 0.166 以上
--network-only 是 0.166.0 加的,旧版本没有。先看版本:
codex --version低于 0.166 就升级(npm 装的用 npm,或者直接 codex update):
npm install -g @openai/codex@latest还没装的可以先看 Codex CLI 安装教程。Windows 上 Codex 打不开、daemon 起不来是另一回事,见 Codex CLI Windows daemon 修法。
第二步:跑一次诊断
codex doctor --network-only它只查四样东西:配置能不能加载、网络环境(代理和证书变量)、模型接口的 HTTP 能不能通、Responses WebSocket 能不能通。数据库、MCP 这些不相关的检查会跳过,所以很快。
我这台机器(没登录)的正常输出是这样的:
Codex Doctor v0.169.0
Configuration
[ok] config loaded
Connectivity
[ok] network no proxy env vars
proxy env vars none
respect system proxy disabled
managed proxy not configured
[!!] websocket Responses WebSocket failed; HTTPS fallback may still work - Check proxy, VPN, firewall, DNS, custom CA, and WebSocket policy support.
……
handshake transport error http 401 Unauthorized: [redacted]
[ok] reachability active provider endpoints are reachable over HTTP
reachability mode ChatGPT auth
ChatGPT inference URL https://chatgpt.com/backend-api/<redacted> reachable (HTTP 405)
-------------------------------------------------------------
3 ok | 1 notes | 1 warn | 0 fail degraded怎么看:
[ok]正常,[!!]警告,[XX]失败。最后一行是汇总,failed才是真连不上- 上面的输出加了
--ascii --no-color,状态标签是纯文字,方便复制;默认输出带颜色 reachable (HTTP 405)/(HTTP 401)这类返回码说明网络是通的,服务器回了话,只是没带凭据,正常
WebSocket 报 401 不用慌
上面那条 [!!] websocket 是因为我没登录,握手时服务器回了 401。它不是网络问题,登录后再跑就行。
就算真的是网络挡了 WebSocket,Codex 也会退回普通 HTTPS:官方 0.168 的更新说明写的是,WebSocket 重试用完或收到 HTTP 426 后,本次会话剩下的请求都改走 HTTP。所以只要 reachability 是 ok,一般就能用,只是可能慢一点。
场景一:代理变量指向了不存在的代理
最常见的情况:以前设过 HTTPS_PROXY,后来代理软件关了或端口变了,变量还留着。我故意把代理指到一个没人监听的端口:
# PowerShell
$env:HTTPS_PROXY = "http://127.0.0.1:9"
$env:HTTP_PROXY = "http://127.0.0.1:9"
codex doctor --network-onlyConnectivity
[ok] network network-related environment looks readable
proxy env vars present HTTP_PROXY, HTTPS_PROXY, http_proxy, https_proxy
……
[!!] websocket Responses WebSocket failed; HTTPS fallback may still work - ……
handshake transport error network error: [redacted]
[XX] reachability one or more required provider endpoints are unreachable over HTTP - Check proxy, VPN, firewall, DNS, and custom CA configuration.
ChatGPT inference URL https://chatgpt.com/backend-api/<redacted> connect failed (required)
2 ok | 2 notes | 1 warn | 1 fail failed注意两点:
network那行还是[ok],它只是说"读到了代理变量",不管代理能不能用。真正的报错在下面的reachabilityproxy env vars present会把读到的变量名都列出来,大小写两种写法都算。看到你没印象设过的变量,就是它在捣乱
改法:把变量改对,或者删掉。PowerShell 里只删当前窗口:
Remove-Item Env:HTTPS_PROXY, Env:HTTP_PROXY如果是在"系统属性 → 环境变量"里设的,要去那里删,然后重开终端。
有些地址不该走代理(比如公司内网的模型网关),可以用 NO_PROXY 排除。我在代理坏掉的情况下加了这一句,reachability 就恢复成 ok 了:
$env:NO_PROXY = "chatgpt.com,api.openai.com" [ok] reachability active provider endpoints are reachable over HTTP
3 ok | 1 notes | 1 warn | 0 fail degraded场景二:浏览器能上,Codex 连不上(系统代理)
公司电脑经常是在 Windows "设置 → 网络 → 代理"里配的代理(或 PAC 脚本),浏览器自动用,Codex 默认不用。doctor 里那行 respect system proxy disabled 说的就是这个。
0.167 起可以让 Codex 读系统代理(实验功能,只支持 Windows 和 macOS)。两种开法:
- 在 Codex 里输入
/experimental,打开 "System proxy",然后重启 Codex - 命令行:
codex features enable respect_system_proxyEnabled feature `respect_system_proxy` in config.toml.它会在 ~/.codex/config.toml 里写上:
[features]
respect_system_proxy = true再跑 doctor,那一行会变成 respect system proxy enabled。关掉用 codex features disable respect_system_proxy。
我这台机器没配系统代理,所以只验证了开关本身生效,没实测它在真实公司代理下的效果。另外 0.164 起,Windows 上遇到需要 NTLM / Negotiate 认证的公司代理,Codex 会用当前登录的 Windows 账户自动认证(据官方更新说明,同样没实测)。
场景三:公司网络换了证书(TLS 拦截)
有些公司的安全网关会解密 HTTPS,再用公司自己的根证书重新签名。浏览器信任这个证书,Codex 不认识,就会连不上。
官方给的办法是用 CODEX_CA_CERTIFICATE 指向一个 PEM 格式的证书包(找 IT 要公司根证书)。它对 HTTPS、登录和 WebSocket 都生效,优先级高于 SSL_CERT_FILE:
$env:CODEX_CA_CERTIFICATE = "C:\certs\company-root.pem"路径写错时 doctor 会直接指出来。我故意指向一个不存在的文件:
[!!] network custom CA env var points at an unreadable path
CODEX_CA_CERTIFICATE C:/Users/<你的用户名>/……/nope.pem (The system cannot find the file specified. (os error 2))看到这行就检查文件路径和权限。另外 SSL_CERT_FILE 是很多程序共用的变量,如果它指向一个旧文件,也会影响 Codex(CODEX_CA_CERTIFICATE 没设的时候会用它)。
我没有公司 TLS 拦截的环境,证书内容不对时会报什么没实测。
场景四:用第三方接口时地址写错
接 DeepSeek 之类第三方模型时,接口地址写在 config.toml 的 model_providers 里(接法见 Claude Code / Codex 接入 DeepSeek)。doctor 会直接请求你配的地址,平时直接跑 codex doctor --network-only 就行。我为了测试,临时用 -c 配了一个 provider(在 Git Bash 里跑的;PowerShell 5 传带双引号的参数会出问题,建议直接写进 config.toml):
codex doctor --network-only -c model_provider=test -c 'model_providers.test={name="test",base_url="https://api.deepseek.com",wire_api="responses",env_key="TEST_KEY"}'地址正确时:
[ok] websocket Responses WebSocket is not enabled for the active provider
[ok] reachability active provider endpoints are reachable over HTTP
reachability mode provider auth
test API inference URL https://api.deepseek.com/responses reachable (HTTP 401)
test API route probe https://api.deepseek.com/models route exists (HTTP 401)
4 ok | 0 warn | 0 fail ok把域名故意打错成 api.deepseek.cmo:
[XX] reachability one or more required provider endpoints are unreachable over HTTP - ……
test API inference URL https://api.deepseek.cmo/responses request timed out (required)
3 ok | 1 notes | 0 warn | 1 fail failed几个细节:
- 域名打错报的是
request timed out,不是"域名解析失败",别被误导去查网速,先核对地址拼写 - 它会把实际请求的完整 URL 打出来(
…/responses),拿这个对照服务商文档,能看出base_url是不是少了或多了/v1 - 第三方接口一般不支持 Responses WebSocket,显示
not enabled for the active provider是正常的 - 401 只说明连得上;Key 对不对,doctor 这一步不管
要发给别人帮忙看:--summary 和 --json
只看每项结果、不要细节:
codex doctor --network-only --summary要贴到 GitHub issue 或发给 IT,用 JSON:
codex doctor --network-only --json > doctor.jsonJSON 里 overallStatus 是总结果,checks 下面是每一项。Token、请求头这些敏感值会被替换成 [redacted],但本机路径和用户名不会,发出去前自己看一眼。
不加 --network-only 的 codex doctor 会做完整检查(安装、登录、存储、MCP 等),排查网络以外的问题时用。
常见问题
提示没有 --network-only 这个参数
版本低于 0.166,先升级(旧版本的具体报错我没测)。
doctor 全是 ok,但 Codex 还是连不上
doctor 是在你当前的终端里跑的,读的是这个终端的环境变量。如果 Codex 是从 VS Code 扩展或桌面 App 启动的,它们的环境变量可能不一样。在同一个地方启动再试,或者把变量设到系统环境变量里再重启那个程序。
改了环境变量没生效
在系统设置里改的环境变量,已经开着的终端读不到,要关掉重开。