发布日期：2026-09-07 | 话题标签：Codex、502、OpenAI、网络排查、Codex CLI

根据 OpenAI 官方 2026 年 Error codes、Codex Authentication 和 Troubleshooting 文档，Codex 502 是请求经过网关或上游服务时未获得正常响应的故障表现，不等于账号失效或本地代码出错。官方将服务端、连接、超时、认证和限流问题分开处理，因此排查应先看状态页，再区分服务、网络代理、登录会话、provider 配置和日志。偶发错误等待后重试；持续失败则用另一入口和网络对照，并收集脱敏日志、版本、时间与 request ID。

先说结论：Codex 502 的正确处理顺序

Codex 502 最有效的处理顺序是“确认范围 → 检查状态 → 短暂重试 → 排查网络和认证 → 收集日志”。

建议按下面 5 步执行：

  1. 记下完整报错、出现时间、使用的入口和当前任务。

  2. 打开 OpenAI 状态页，确认是否存在相关服务事件。

  3. 等待几十秒后重试一到两次，不要在短时间内无限循环重试。

  4. 用另一入口或另一网络做一次对照，判断是服务范围问题还是本地链路问题。

  5. 仍然失败时，检查登录状态、代理、证书和 Codex 日志，并准备脱敏后的支持信息。

502 和其他错误不要混为一谈

502 的表面表现是“网关没有拿到有效上游响应”，但具体原因要看发生在哪一层。OpenAI 官方错误码页当前重点说明了 500、503、APIConnectionError 和 APITimeoutError，它们分别对应服务端内部错误、模型暂时过载、无法建立连接和请求超时；502 可能出现在这些问题的网关表现层，因此不能仅凭数字判断责任归属。

现象

更接近的排查方向

先做什么

偶发 502，稍后自行恢复

上游服务或网关瞬时异常

等待后重试，查看状态页

所有入口都 502

服务端事件、账号区域或共享网络出口

对照状态页和另一网络

只有公司网络失败

代理、TLS 检查、防火墙或出口策略

检查代理与企业 CA

只有一个项目或配置失败

自定义 provider、地址或项目配置

检查 config.toml 和 provider

伴随 401/403

登录、API Key、工作区或地区权限

重新确认认证方式和权限

伴随 429

请求频率、额度或组织限制

降低速率并查看 Retry-After

官方资料中的 4 个关键数字

  • 2 个服务端 HTTP 错误码：OpenAI《Error codes》文档（2026）重点列出 500 内部服务错误和 503 模型暂时过载；当前页面没有把 502 单独列为一种固定根因。

  • 2 种本地认证方式：ChatGPT/Codex Authentication 文档（2026）说明本地 Codex 支持 ChatGPT 登录和 API Key 登录，两种方式的权限与计费边界不同。

  • 5 个常用日志级别：Codex 环境变量文档（2026）列出 error、warn、info、debug、trace 五个常用 RUST_LOG 级别，排查 502 通常从 debug 开始。

  • 2 类本地诊断位置：Codex Troubleshooting 文档（2026）列出 macOS 应用日志目录和 $CODEX_HOME/sessions 会话目录，收集资料时应先做脱敏。

第一步：判断是不是 OpenAI 侧故障

当多个 Codex 入口同时出现 502 时，先排查服务状态和共享网络出口，而不是立刻重装客户端。

观察 4 个信号

  • 时间是否集中：同一时间突然出现，且之前正常，优先怀疑临时服务异常。

  • 入口是否都受影响：ChatGPT 中的 Codex、Codex CLI、IDE 扩展是否同时失败。

  • 任务是否都受影响：新任务、继续会话、简单请求是否都返回 502。

  • 环境是否相关：手机热点、家庭网络、公司网络的结果是否一致。

OpenAI 状态页会把不同能力拆成独立组件。不要只看首页的总状态，还要展开事件详情，确认它是否覆盖你正在使用的 Codex 入口。状态页没有事件，只能说明当前没有公开事件，不能证明你的本地网络一定正常。

低成本对照测试

按下面顺序做对照，通常可以快速缩小问题范围：

  1. 在同一设备上刷新或重新启动 Codex。

  2. 用浏览器打开 ChatGPT，发起一个最短请求。

  3. 将当前网络临时切换到手机热点。

  4. 如果使用 CLI，再运行版本和登录状态检查。

codex --version
codex login status

如果 Web 和 CLI 都失败，但更换网络后恢复，重点看本地出口；如果不同网络、不同入口都失败，优先等待官方状态更新或准备支持工单信息。

第二步：检查 Codex CLI 的登录会话

登录问题通常更常见地返回 401、403 或登录流程错误，但过期会话、代理中断和网关异常也可能让用户只看到 502，因此应检查登录状态而不是猜测。

官方认证文档说明，Codex 本地工作支持两种主要登录方式：使用 ChatGPT 订阅登录，或使用 OpenAI API Key 登录。两种方式的权限、计费和可用功能不同；切换方式前，先确认自己原本使用的是哪一种。

查看、退出和重新登录

# 查看当前认证方式和状态
codex login status

# 仅在确认需要刷新会话时执行
codex logout
codex login

如果你使用 API Key 登录，确认密钥属于正确的组织或项目，并检查环境变量中没有多余空格。不要把 OPENAI_API_KEY、~/.codex/auth.json、浏览器 Cookie 或完整请求头贴到社区和工单中。官方文档明确提醒，文件式认证缓存包含访问凭证，应按密码保护。

什么时候不要反复登录

如果 codex login status 正常、登录页面也能打开，但每次执行任务仍然 502，反复注销登录通常不会解决服务端或代理问题。此时应把注意力转向状态页、网络出口和日志，而不是继续更换账号。

第三步：排查代理、证书和防火墙

OpenAI 官方把 APIConnectionError 的常见原因归为网络设置、代理配置、SSL 证书和防火墙规则；这几项也是本地持续出现 502 时最值得优先检查的链路。

看环境里是否设置了代理

env | grep -E '^(HTTP|HTTPS|ALL|NO)_PROXY='

重点核对：

  • 代理地址是否仍然有效；

  • HTTPS 请求是否被企业网关重新签发证书；

  • 代理是否只允许浏览器，不允许 CLI 子进程；

  • 公司防火墙是否按域名、SNI 或地区策略拦截请求；

  • 是否存在旧的 NO_PROXY 规则，导致部分请求绕过代理。

不要为了“验证一下”直接关闭所有 TLS 校验。更安全的做法是让网络管理员提供企业根证书，并按官方方式设置 Codex 的自定义 CA：

export CODEX_CA_CERTIFICATE=/path/to/corporate-root-ca.pem
codex login

/path/to/corporate-root-ca.pem 是示例路径，必须替换为实际 PEM 文件。官方认证文档说明，该设置会作用于登录、普通 HTTPS 请求和安全 WebSocket 连接。

不要把沙箱网络和 Codex 主连接混淆

Codex 文档中的 sandbox_workspace_write.network_access 控制的是模型生成命令及其子进程的网络访问；它不等同于 Codex 客户端自身访问服务的网络通道。也就是说，给命令沙箱打开网络，通常不能直接修复客户端界面的 502。

如果你的任务确实需要让 Codex 执行联网命令，官方示例是：

[sandbox_workspace_write]
network_access = true

这项配置会扩大命令执行权限，应结合项目风险使用。排查 502 时，先验证系统代理、企业证书和出口策略，再考虑是否需要修改沙箱配置。

第四步：确认是不是自定义 provider 或业务 API 的问题

如果你在 config.toml 中配置了自定义模型 provider，502 可能来自自定义 base_url、上游兼容性或 provider 的重试策略，而不一定来自 OpenAI 官方服务。

先确认配置层级

Codex 官方配置文档说明，配置可能来自用户级 ~/.codex/config.toml、项目级 .codex/config.toml、profile 和命令行覆盖项；命令行参数优先级最高。先查看最近是否改过这些位置，尤其是 provider、base URL、认证方式和模型名。

codex -c log_dir=./.codex-log

对于默认 OpenAI provider，项目级配置不能覆盖部分机器级 provider 和认证字段；如果你在项目目录里改了配置但行为没有变化，可能是配置层级本身不生效。不要把 API Key 写进项目仓库，也不要提交包含密钥的 config.toml。

用独立 API 请求做隔离测试

只有在你本来就使用 API Key 和业务代码时，才建议做独立 API 隔离测试。隔离测试的目的，是判断业务代码、网络出口和上游 API 是否正常，不是证明 Codex 客户端一定正常。

如果需要另一条可直接访问的模型调用链做对照，可以查看支持多款主流模型的七牛云 AI 大模型广场；它与 Codex 的账号、会话和故障域不同，测试结果只能作为业务侧网络和 SDK 的参考。

第五步：打开日志并保存最小诊断包

当 502 持续出现时，日志比截图更有价值，因为支持人员需要知道请求在哪一层失败。

CLI 日志

Codex 官方排障文档给出的调试方式是设置 RUST_LOG=debug，并指定 log_dir 生成可查看的 TUI 日志：

RUST_LOG=debug codex -c log_dir=./.codex-log

复现一次问题后，可以查看日志文件：

tail -n 200 ./.codex-log/codex-tui.log

如果不想持续跟踪，使用 tail -n 200 保留最近片段即可。官方文档列出的常用日志级别包括 error、warn、info、debug 和 trace；排查 502 通常从 debug 开始，避免一上来产生过多无关输出。

桌面端日志

macOS 桌面端日志默认位于：

~/Library/Logs/com.openai.codex/YYYY/MM/DD

官方排障文档还列出会话记录目录 $CODEX_HOME/sessions，默认通常是 ~/.codex/sessions。分享之前先搜索并删除 API Key、访问令牌、Cookie、项目机密和完整请求体。

什么时候应该提交支持请求

当问题持续、跨网络复现，或者状态页存在相关事件时，提交一份结构化信息比只写“Codex 502”更容易得到有效处理。

建议准备：

  1. 使用的入口：Web、桌面端、CLI 或 IDE 扩展。

  2. Codex 版本、操作系统和认证方式。

  3. 完整错误文本、HTTP 状态码和 request ID（如有）。

  4. 发生时间，注明时区，最好同时记录 UTC。

  5. 是否换过网络、浏览器或入口，以及结果是否变化。

  6. 脱敏后的日志片段，不要包含密钥、Cookie 和机密代码。

OpenAI 官方错误文档建议持久性错误提交模型、错误消息与代码、请求数据和请求时间等信息；对 Codex 场景可以沿用这一清单，但请求头中的认证字段必须先删除。也可以先查看 Codex 官方 GitHub issue 是否有相同现象，再决定是等待服务恢复还是提交新问题。

常见问题

Q：Codex 502 是不是账号被封了？
不一定。账号或权限问题更常见地表现为 401、403 或明确的登录提示；502 只说明请求链路中的网关没有拿到正常上游响应。先看状态页，再用另一网络和入口做对照。

Q：一直重试能解决 Codex 502 吗？
偶发服务端错误可能在短暂等待后恢复，但无限快速重试没有帮助，还可能叠加限流。建议等待几十秒后重试一到两次；持续失败就转向状态、网络、认证和日志排查。

Q：为什么浏览器能用，Codex CLI 却 502？
两者可能使用不同的代理、证书、网络权限和认证缓存。先运行 codex login status，再检查 HTTP_PROXY、HTTPS_PROXY 和企业 CA；浏览器成功不能证明 CLI 的请求链路完全相同。

Q：修改 sandbox_workspace_write.network_access 能修复 502 吗？
通常不能。这个设置控制 Codex 执行命令时的子进程网络权限，不是客户端访问 OpenAI 服务的开关。客户端 502 应先排查代理、证书、防火墙、登录状态和上游服务。

Q：我应该删除 ~/.codex 目录重新安装吗？
不建议把删除配置和认证缓存作为第一步。它可能丢失会话、配置和诊断线索，而且不能修复官方服务故障。先保留状态，使用 codex login status、日志和对照网络定位原因。

收尾：把 502 当成分层诊断题

Codex 502 的关键不是寻找一个万能命令，而是确认错误发生在官方服务、网络出口、登录会话、provider 配置还是业务 API。OpenAI 官方资料对服务端错误、连接错误、认证错误、限流和日志采集分别给出了处理方向，按层排查比反复重装更可靠。

本文内容基于 2026 年 9 月 7 日可访问的 OpenAI Developers、ChatGPT/Codex 帮助文档和 OpenAI 状态页信息；错误码、客户端版本和状态组件会持续变化，遇到新故障时应以官方状态页和最新文档为准。

延伸阅读