> ## Content Index
> Fetch the complete content index at: https://tbbbk.com/llms.txt
> Use this file to discover other available public pages before exploring further.

# Codex 连不上网怎么排查：codex doctor --network-only 实测（2026）
- URL: https://tbbbk.com/codex-doctor-network-troubleshooting/
- Published: 2026-11-15T12:17:03.000Z
- Updated: 2026-11-15T12:17:03.000Z
- Description: Codex CLI 连不上？用 codex doctor --network-only 几秒钟定位是代理、证书还是接口地址的问题。Windows 上 0.169 实测，附真实输出和改法。
- Author: TuBaiBai
- Tags: AI 编程工具, Codex

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 安装教程](https://tbbbk.com/openai-codex-cli-install-subscription-usage-china-guide-2026/)。Windows 上 Codex 打不开、daemon 起不来是另一回事，见 [Codex CLI Windows daemon 修法](https://tbbbk.com/codex-windows-daemon-fix/)。

## 第二步：跑一次诊断

```
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](https://tbbbk.com/claude-code-codex-deepseek-flash-setup/)）。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](https://github.com/openai/codex/releases/tag/rust-v0.166.0)
- Codex 0.167.0 发布说明（系统代理实验开关）：[GitHub](https://github.com/openai/codex/releases/tag/rust-v0.167.0)，实现见 [PR #58157](https://github.com/openai/codex/pull/58157)
- WebSocket 退回 HTTP 的行为：[PR #58989](https://github.com/openai/codex/pull/58989)
- 环境变量（`CODEX_CA_CERTIFICATE` / `SSL_CERT_FILE`）：[官方文档](https://learn.chatgpt.com/docs/config-file/environment-variables)
- CLI 命令（`codex doctor`、`codex features`）：[官方文档](https://learn.chatgpt.com/docs/developer-commands?surface=cli)