阅读时间 8 分钟

Codex 连不上网怎么排查:codex doctor --network-only 实测(2026)

Codex CLI 连不上?用 codex doctor --network-only 几秒钟定位是代理、证书还是接口地址的问题。Windows 上 0.169 实测,附真实输出和改法。

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-only
Connectivity
  [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],它只是说"读到了代理变量",不管代理能不能用。真正的报错在下面的 reachability
  • proxy 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_proxy
Enabled 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.json

JSON 里 overallStatus 是总结果,checks 下面是每一项。Token、请求头这些敏感值会被替换成 [redacted],但本机路径和用户名不会,发出去前自己看一眼。

不加 --network-only 的 codex doctor 会做完整检查(安装、登录、存储、MCP 等),排查网络以外的问题时用。

常见问题

提示没有 --network-only 这个参数

版本低于 0.166,先升级(旧版本的具体报错我没测)。

doctor 全是 ok,但 Codex 还是连不上

doctor 是在你当前的终端里跑的,读的是这个终端的环境变量。如果 Codex 是从 VS Code 扩展或桌面 App 启动的,它们的环境变量可能不一样。在同一个地方启动再试,或者把变量设到系统环境变量里再重启那个程序。

改了环境变量没生效

在系统设置里改的环境变量,已经开着的终端读不到,要关掉重开。

参考来源

  • Codex 0.166.0 发布说明(加入 --network-only):GitHub
  • Codex 0.167.0 发布说明(系统代理实验开关):GitHub,实现见 PR #58157
  • WebSocket 退回 HTTP 的行为:PR #58989
  • 环境变量(CODEX_CA_CERTIFICATE / SSL_CERT_FILE):官方文档
  • CLI 命令(codex doctor、codex features):官方文档