Codex CLI 走公司代理：PAC/WPAD、CA 证书与 HTTPS_PROXY（2026）

如果你的笔记本能在浏览器里打开 ChatGPT，但 codex 在第一个请求上干坐着什么都不干，那网络没坏，Codex 也没坏。 Codex CLI 不会像浏览器那样读你的 PAC 文件、也不会发现 WPAD，所以一台上网正常的机器照样能让 codex 卡在第一个请求上。这篇指南带你从那个死掉的终端走到一个能干活的 agent，并解释为什么到了 2026 年这个修法仍然是手动设 HTTPS_PROXY。

30 秒速答

整件事就是四步：找出 PAC 指向的真实代理、导出 HTTPS_PROXY/HTTP_PROXY/NO_PROXY、用 CODEX_CA_CERTIFICATE 把公司 CA 交给 Codex、再用 RUST_LOG=debug 验证。这页剩下的内容就是每一步背后的细节，以及你一路上会撞见的报错。

配置完能做什么（做不到什么）

配好之后，Codex 会通过你浏览器用的同一个代理发出它的 API 调用、扛得住一个做 TLS 检查的中间盒子、并且对内部 Git 服务器和包仓库跳过代理。这覆盖了绝大多数被锁死的企业网络。

它不会把 Codex 变成浏览器。Codex 依然不会解析 PAC 脚本、依然不会应答 WPAD 广播、依然不能可靠地走 SOCKS5 做流式传输。如果你的安全团队只会通过组策略和一个 PAC URL 下发代理设置，那把它翻译成环境变量的就是你自己。这个翻译才是真正的活儿，也是每一个”就设个 HTTPS_PROXY”式回答略过的部分。

决策框架：什么时候该用这套配置（什么时候不该）

该用的时候

• 你们公司通过 PAC/WPAD 或组策略下发代理配置，而 CLI 工具只能自生自灭。
• 代理做 TLS 检查，于是任何不在系统信任库里的工具你都会看到证书错误。
• 有五个或更多开发者打同一个代理，你想要一份共享、有文档的配置，而不是人人各自瞎猜。

不该用的时候

• 你在家里或咖啡店网络，根本没有代理。把 HTTPS_PROXY 设成一个死地址只会搞坏 Codex。把它取消掉。
• 你的代理是透明代理（在网络层拦截，无需客户端配置）。那就没什么可设的，手动设代理变量反而会把请求代理两遍。
• 你只想改 API key 或端点。那是一行 config.toml 的修改，不是一个代理项目。直接跳到进阶章节。

代理值本身有个干净的停手规则。如果 curl -x http://your-proxy:port https://api.openai.com/v1/models 返回的是一个 HTTP 状态码而不是卡住，那你的代理地址就是对的，可以停止折腾它了。此后的一切都是 CA 信任和认证问题，那是另外的问题，有另外的修法。

为什么 Codex 无视你的 PAC/WPAD 代理

Codex 无视 PAC 和 WPAD，是因为它是一个建立在 HTTP 客户端之上的 CLI，那个客户端只懂代理环境变量，不懂浏览器的代理栈。这个设计事实造成了大部分困惑，所以值得说清楚。

PAC 文件（Proxy Auto-Config）是一个小型 JavaScript 程序，里面有个 FindProxyForURL(url, host) 函数。你的浏览器对每个请求运行这个函数，拿回一个答案，像 PROXY proxy.corp.example.com:8080 或者 DIRECT。WPAD（Web Proxy Auto-Discovery）是告诉浏览器那个 PAC 文件在哪里的协议，通常通过一个 DHCP 选项或一条 wpad.<yourdomain> DNS 记录。浏览器、Office 应用和 Windows 网络栈都会讲这套。按照 PyPAC 项目对 PAC 文件的概述，几乎没有命令行工具会。

Codex 的 HTTP 客户端认 HTTPS_PROXY、HTTP_PROXY、ALL_PROXY 和 NO_PROXY，这是 curl、git 和大多数语言运行时共享的标准 Unix 约定。目前有一个未关闭的请求，希望让每个 Codex HTTP 客户端一致地认代理环境变量，但截至 Codex 0.142.x，自己设置这些变量才是受支持的方式。所以那条对你浏览器有效的链条（WPAD 找到 PAC，PAC 返回代理，浏览器用它）在 Codex 内部没有对应物。没设 HTTPS_PROXY 时，Codex 尝试直连，防火墙把它丢掉，你得到的是卡住而不是一个干净的报错。那个悄无声息的丢弃，就是为什么这看起来像 Codex 的 bug，而它其实是一个缺失的翻译步骤。

把两条发现路径并排看会更清楚。你的浏览器在启动时，要么读一个你管理员通过组策略下发的 PAC URL，要么通过 DHCP 和 DNS 广播一个 WPAD 查询去找一个。然后它对每一个 URL 运行 FindProxyForURL，所以不同主机能拿到不同答案：内网返回 DIRECT，公网返回 PROXY。Codex 什么都不做。它在启动时从环境读四个字符串，然后对整个会话套用。没有按主机的脚本，没有自动发现广播，也没有重新求值。这就是为什么”我别的工具都行”并不能证明 Codex 也会行：你别的工具几乎肯定读的是你正准备设置的同一批环境变量，而不是 PAC 文件。

系统要求

在你动代理设置之前，先确认基础项，因为代理会痛快地掩盖一个不相干的安装问题。

• Codex CLI 用正确的包安装。npm install -g @openai/codex。npm 上没有作用域的那个 codex 是另一个项目，装了它是后面冒出 command not found 或怪异行为最常见的原因。
• Node.js 16 或更新，走 npm 安装路径需要（@openai/codex 声明了 engines: node >=16）。更旧的 Node 会在你还没碰到网络之前就让安装失败。
• 你的代理端点，写成 host:port。如果你手上只有一个 PAC URL，下一步会把它解析出来。
• 如果你的代理做 TLS 检查，需要 PEM 格式的公司根 CA。找你的平台团队要”根 CA 证书包”，或者从系统钥匙串里导出。

分步操作：把 Codex 指向你的公司代理

按顺序做完。每一步都有个检查点，让你在往下走之前知道它落地了。

第 1 步：确认浏览器能用但 Codex 不行

在浏览器里打开你的 API 主机看它加载，然后从终端跑一个裸请求。

# In a browser: https://api.openai.com/v1/models loads (401 JSON is fine)
# In the terminal, this should hang or fail fast if there's a proxy:
curl -sS --max-time 10 https://api.openai.com/v1/models ; echo "exit=$?"

如果浏览器能到达主机而 curl 超时，你就是经典的只有 PAC 的场景。那个落差就是你的全部问题，下一步来堵上它。

第 2 步：解析 PAC 文件找出真实代理

你需要 PAC 对该 API 主机会返回的实际 host:port。在 macOS 上，读出 auto-config URL，然后测试它。pactester 随 pacparser 包一起提供。

# macOS: find the PAC URL your system is configured with
scutil --proxy | grep -i ProxyAutoConfig
# Download it and ask which proxy serves the API host
curl -s "$PAC_URL" -o wpad.dat
pactester -p wpad.dat -u https://api.openai.com
# → PROXY proxy.corp.example.com:8080; DIRECT

在 Windows 上，PowerShell 读同一个 auto-config URL 以及实际生效的 WinHTTP 代理：

Get-ItemProperty 'HKCU:\Software\Microsoft\Windows\CurrentVersion\Internet Settings' AutoConfigURL
netsh winhttp show proxy

取解析器打印出的第一个 PROXY host:port。那就是你接下来要硬编码的值。如果你的 PAC 有多条规则，pactester 手册讲了各个参数。

第 3 步：设置 HTTPS_PROXY、HTTP_PROXY 和 NO_PROXY

为 HTTPS 和 HTTP 导出代理，并在 NO_PROXY 里列出每一个必须跳过代理的内部主机。

export HTTPS_PROXY="http://proxy.corp.example.com:8080"
export HTTP_PROXY="http://proxy.corp.example.com:8080"
export NO_PROXY="localhost,127.0.0.1,.corp.example.com,.internal"

注意代理 URL 的 scheme 是 http://，即便它承载的是 HTTPS 流量。这是对的；scheme 描述的是你怎么跟代理对话，而不是它转发什么。如果代理需要凭证，把它们内联进去：

export HTTPS_PROXY="http://alice:s3cret@proxy.corp.example.com:8080"

把这几行放进 ~/.zshrc 或 ~/.bashrc，让新开的 shell 继承它们。缺 NO_PROXY 是代理设上去之后内部 Git 或仓库调用坏掉的常见原因，所以别跳过它。

第 4 步：信任做 TLS 检查的代理的 CA

如果你的代理做 TLS 检查，它会用一个私有根 CA 重新签发每一张证书。在你告诉 Codex 信任这个 CA 之前，它会拒绝。登录之前，把 CODEX_CA_CERTIFICATE 指向那个 PEM 证书包。

export CODEX_CA_CERTIFICATE="/etc/pki/tls/certs/corporate-root-ca.pem"
# Fallback that also covers curl, git, and other tools:
export SSL_CERT_FILE="/etc/pki/tls/certs/corporate-root-ca.pem"
codex login

CODEX_CA_CERTIFICATE 优先级更高且只影响 Codex；当它没设时，Codex 退回去用 SSL_CERT_FILE，大多数企业镜像已经设好了这个。Codex 的进阶配置文档描述了你在下面进阶章节会用到的模型提供方和端点选项。

第 5 步：用 RUST_LOG=debug 验证

确认这些变量对 Codex 可见，并观察代理协商。

env | grep -i proxy
RUST_LOG=debug codex exec "print the current date" 2>&1 | grep -i proxy

如果调试输出里显示了你的代理主机、且命令返回了结果，你就完成了。如果还是失败，报错信息会告诉你哪一层坏了，下一节把每条信息映射到一个修法。

配置过程中的常见报错（及修法）

大多数代理故障都会产生少数几条信息中的一条。在你开始瞎改设置之前，先在这里对上你的那条。

其中两条值得说一句。证书错误是被检查网络上最常见的单一拦路虎，而修它靠的是 CA 信任，不是关掉校验。关掉 TLS 校验来”让它能用”，等于把你的流量交给线路上任何东西，所以别这么干。SOCKS5 卡住也是真的：SOCKS5 在某些 Codex 路径能用，但对 agent 依赖的流式响应不稳定，所以在公司网络里优先用 HTTP 代理。

一眼看懂的诊断流程

flowchart TD
    A[Browser reaches internet, codex hangs] --> B{Proxy env vars set?}
    B -->|No| C[Resolve PAC, set HTTPS_PROXY + NO_PROXY]
    B -->|Yes| D{SSL / certificate error?}
    C --> D
    D -->|Yes| E[Set CODEX_CA_CERTIFICATE to corporate CA]
    D -->|No| F{407 auth error?}
    E --> F
    F -->|Yes| G[Add user:pass@ or run a cntlm/px relay]
    F -->|No| H[Run RUST_LOG=debug codex exec to trace]

什么时候你仍然需要 HTTPS_PROXY（哪怕 PAC 说 DIRECT）

只要 Codex 得访问一个被你 PAC 路由到代理的主机，你就仍然需要 HTTPS_PROXY，而在大多数公司网络里，那意味着每一个外部 API 主机。PAC 再聪明也帮不了 Codex，因为 Codex 从不运行 PAC。这在三种具体情形里绊倒人，值得点出来。

第一种是分流路由。你的 PAC 对内部主机返回 DIRECT，对公网返回 PROXY。所有内部的东西不设任何变量就能从终端用，于是你以为网络是开着的，然后第一个外部 API 调用卡住了。修法是为外部主机设 HTTPS_PROXY，并把内部主机列进 NO_PROXY，让它们保持直连。

第二种是带分流隧道的 VPN。在 VPN 上，PAC 可能把公司流量走代理、其他全部直连，或者反过来。当你连上或断开时，实际生效的代理变了，但你导出的变量没变。如果切换 VPN 之后 Codex 马上开始失败，重新解析 PAC 并更新 HTTPS_PROXY。

第三种是透明代理的假设。有些网络在路由器上拦截流量、无需客户端配置，所以浏览器什么都不用设。如果你的网络就是这样，你可能根本不需要 HTTPS_PROXY，而把它设成一个不存在的主机只会搞坏 Codex。决策框架里那个 curl 测试会告诉你身处哪个世界：如果一个裸 curl 打 API 主机能通，你就是透明代理，应该让那个变量保持不设。

短说：当 API 主机被代理时设 HTTPS_PROXY，当网络透明代理时取消它。中间没有一个 Codex 会替你读 PAC 的地带。

团队 / 多开发者配置

一台机器搞定之后，目标是让下一个开发者不用重走你那个下午。能规模化的模式，是把共享的、非机密的配置和每个用户的机密分开。

把代理和 CA 的值放进一个版本化的 profile 片段，让你的团队从他们的 shell rc 文件里 source 进来：

# proxy.env — committed to the team dotfiles repo (no secrets here)
export HTTPS_PROXY="http://proxy.corp.example.com:8080"
export HTTP_PROXY="$HTTPS_PROXY"
export NO_PROXY="localhost,127.0.0.1,.corp.example.com,.internal"
export CODEX_CA_CERTIFICATE="/etc/pki/tls/certs/corporate-root-ca.pem"

把每一个 API key 都从那个文件里剔出去，放进每个开发者自己设一次的用户变量里。对需要凭证的代理，别把任何人的密码提交进 HTTPS_PROXY；让每个人在本地加自己的 user:pass@，或者跑一个本地认证中继，让任何凭证都不出现在共享配置里。

在 NTLM 或 Kerberos 代理上，整个团队都需要一个本地中继，因为 Codex 做不了那个握手。跑一个每机器的中继，比如 cntlm 或 px，然后把所有人的 HTTPS_PROXY 指向它：

# px handles enterprise NTLM auth; Codex talks plain HTTP to localhost
px --proxy=proxy.corp.example.com:8080 --port=3128 &
export HTTPS_PROXY="http://localhost:3128"

有一个铺开时的细节每次都坑到团队：一个开发者从 IDE 终端或启动器里跑 Codex，而不是从登录 shell 里跑。macOS 和 Windows 上的 GUI 应用不继承你在 ~/.zshrc 里设的变量，所以在 Terminal 里能用的那套配置，在编辑器里就失败。把这一条写进你们的入职说明。在 macOS 上，把变量设在一个 launchd 用户代理或应用自己的环境里；在 Windows 上，用系统环境变量对话框，让每个进程都继承它们，而不只是新 shell。在你告诉任何人配置搞定之前，开一个全新终端跑 RUST_LOG=debug codex exec "print ok"，验证一次全新 checkout 能用。

进阶：自定义 base_url 与多提供方路由

代理和 CA 就位之后，Codex 现在能通过那同一个公司出口到达任何 OpenAI 兼容端点，而不只是 api.openai.com。这正是 config.toml 里的自定义模型提供方派上用场的地方。

定义一个指向 OpenAI 兼容网关的提供方块。配置参考记录了每一个键：

# ~/.codex/config.toml
model_provider = "ofox"
model = "openai/gpt-5.4"

[model_providers.ofox]
name = "ofox OpenAI-compatible gateway"
base_url = "https://api.ofox.ai/v1"
env_key = "OFOX_API_KEY"

如果你只想把内置的 OpenAI 提供方换到另一个端点，设 openai_base_url 就行，不用写一整个提供方块。无论哪种方式，请求依然通过你配好的 HTTPS_PROXY 离开你的机器，依然信任你设的 CA，所以代理那套工作原封不动地延续下来。

团队在被锁死的网络上会用到这个，原因是收敛。与其求防火墙团队去放行好几个厂商 API 主机、再维护好几把 key，不如把 Codex 指向一个 OpenAI 兼容网关，改个字符串就换模型。在 ofox 上，这意味着一个端点、一把 key 就覆盖了像 openai/gpt-5.4 这样的模型，外加 Claude、Gemini 等等，从而让代理放行清单保持短小。如果你想先试某个具体模型，openai/gpt-5.4 模型页有它的最新详情。流量依然流经你的公司代理；这里没有任何东西绕过它。

FAQ

Codex CLI 支持 PAC 或 WPAD 代理自动配置吗？ 不支持。Codex 读 HTTP_PROXY、HTTPS_PROXY、ALL_PROXY 和 NO_PROXY，但不会解析 PAC 文件、也不会通过 WPAD 发现代理。你得自己解析 PAC，把结果放进 HTTPS_PROXY。

为什么浏览器能上网，Codex 却卡住？ 你的浏览器通过 WPAD 从 PAC 文件拿到代理，Codex 不会。没设代理变量时，Codex 会打开一个被防火墙丢掉的直连，于是请求一直卡到超时。

怎么给 Codex CLI 设置代理？ 导出 HTTPS_PROXY 和 HTTP_PROXY 指向你的代理主机和端口，再给内部主机设 NO_PROXY。config.toml 里没有代理配置项，所以环境变量就是那条路。

Codex 在代理后面报 SSL 证书错误怎么修？ 做 TLS 检查的代理会呈现一张由私有根 CA 签名的证书，而 Codex 不信任它。在 codex login 之前，把 CODEX_CA_CERTIFICATE 指向你的公司根 CA PEM。没设的话，Codex 退回去用 SSL_CERT_FILE。

Codex CLI 支持 SOCKS5 代理吗？ 部分支持。SOCKS5 在某些路径能用，但对流式和 websocket 流量不稳定，而这正是 Codex 重度使用的路径。在公司网络里，通过 HTTPS_PROXY 的 HTTP 代理更可靠。

怎么给整个团队配置 Codex 代理？ 把代理和 CA 变量放进一个共享、非机密的 profile 片段，再把一个 config.toml 提供方块提交进你们的 dotfiles 仓库。API key 和代理凭证按每用户保存，绝不提交。

对 Codex 来说 HTTP_PROXY 和 HTTPS_PROXY 有什么区别？ HTTP_PROXY 作用于普通 http:// 请求，HTTPS_PROXY 作用于 https:// 请求。Codex 的 API 流量全是 HTTPS，所以真正起作用的是 HTTPS_PROXY，但把两个都设成同一个值。

怎么让 Codex 通过 NTLM 或 Kerberos 代理认证？ Codex 没法直接做 NTLM 或 Kerberos 认证。跑一个本地中继，比如 cntlm 或 px，然后把 HTTPS_PROXY 指向 http://localhost:<中继端口>。

参考来源

公司代理的问题几乎从来不是 Codex 坏了；而是 Codex 诚实地只讲一种没人给它配过的代理方言——纯环境变量。以上全部内容都在 2026-07-05 对照过这些来源：

• OpenAI Codex 进阶配置与配置参考：https://developers.openai.com/codex/config-advanced
• OpenAI Codex 代理环境变量 issue：https://github.com/openai/codex/issues/4242
• PyPAC “About PAC files” 讲 PAC/WPAD 行为：https://pypac.readthedocs.io/en/latest/about_pac.html
• pactester 手册页：https://manpages.ubuntu.com/manpages/focal/man1/pactester.1.html
• ofox 模型目录与文档快照：https://ofox.io/models