根据 OpenAI 官方 2026 年 Error codes、Codex Authentication 和 Troubleshooting 文档，Codex 502 是请求经过网关或上游服务时未获得正常响应的故障表现，不等于账号失效或本地代码出错。官方将服务端、连接、超时、认证和限流问题分开处理，因此排查应先看状态页，再区分服务、网络代理、登录会话、provider 配置和日志。偶发错误等待后重试；持续失败则用另一入口和网络对照，并收集脱敏日志、版本、时间与 request ID。
先说结论：Codex 502 的正确处理顺序
Codex 502 最有效的处理顺序是“确认范围 → 检查状态 → 短暂重试 → 排查网络和认证 → 收集日志”。
建议按下面 5 步执行：
- 记下完整报错、出现时间、使用的入口和当前任务。
- 打开 OpenAI 状态页，确认是否存在相关服务事件。
- 等待几十秒后重试一到两次，不要在短时间内无限循环重试。
- 用另一入口或另一网络做一次对照，判断是服务范围问题还是本地链路问题。
- 仍然失败时，检查登录状态、代理、证书和 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 入口。状态页没有事件，只能说明当前没有公开事件，不能证明你的本地网络一定正常。
低成本对照测试
按下面顺序做对照，通常可以快速缩小问题范围：
- 在同一设备上刷新或重新启动 Codex。
- 用浏览器打开 ChatGPT，发起一个最短请求。
- 将当前网络临时切换到手机热点。
- 如果使用 CLI，再运行版本和登录状态检查。
|
1 2 |
codex --version codex login status |
如果 Web 和 CLI 都失败，但更换网络后恢复，重点看本地出口；如果不同网络、不同入口都失败，优先等待官方状态更新或准备支持工单信息。
第二步：检查 Codex CLI 的登录会话
登录问题通常更常见地返回 401、403 或登录流程错误，但过期会话、代理中断和网关异常也可能让用户只看到 502，因此应检查登录状态而不是猜测。
官方认证文档说明，Codex 本地工作支持两种主要登录方式：使用 ChatGPT 订阅登录，或使用 OpenAI API Key 登录。两种方式的权限、计费和可用功能不同；切换方式前，先确认自己原本使用的是哪一种。
查看、退出和重新登录
|
1 2 3 4 5 6 |
# 查看当前认证方式和状态 codex login status
# 仅在确认需要刷新会话时执行 codex logout codex login |
如果你使用 API Key 登录，确认密钥属于正确的组织或项目，并检查环境变量中没有多余空格。不要把 OPENAI_API_KEY、~/.codex/auth.json、浏览器 Cookie 或完整请求头贴到社区和工单中。官方文档明确提醒，文件式认证缓存包含访问凭证，应按密码保护。
什么时候不要反复登录
如果 codex login status 正常、登录页面也能打开，但每次执行任务仍然 502，反复注销登录通常不会解决服务端或代理问题。此时应把注意力转向状态页、网络出口和日志，而不是继续更换账号。
第三步：排查代理、证书和防火墙
OpenAI 官方把 APIConnectionError 的常见原因归为网络设置、代理配置、SSL 证书和防火墙规则；这几项也是本地持续出现 502 时最值得优先检查的链路。
看环境里是否设置了代理
|
1 |
env | grep -E '^(HTTP|HTTPS|ALL|NO)_PROXY=' |
重点核对：
- 代理地址是否仍然有效；
- HTTPS 请求是否被企业网关重新签发证书；
- 代理是否只允许浏览器，不允许 CLI 子进程；
- 公司防火墙是否按域名、SNI 或地区策略拦截请求；
- 是否存在旧的 NO_PROXY 规则，导致部分请求绕过代理。
不要为了“验证一下”直接关闭所有 TLS 校验。更安全的做法是让网络管理员提供企业根证书，并按官方方式设置 Codex 的自定义 CA：
|
1 2 |
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 执行联网命令，官方示例是：
|
1 2 |
[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、认证方式和模型名。
|
1 |
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 日志：
|
1 |
RUST_LOG=debug codex -c log_dir=./.codex-log |
复现一次问题后，可以查看日志文件：
|
1 |
tail -n 200 ./.codex-log/codex-tui.log |
如果不想持续跟踪，使用 tail -n 200 保留最近片段即可。官方文档列出的常用日志级别包括 error、warn、info、debug 和 trace；排查 502 通常从 debug 开始，避免一上来产生过多无关输出。
桌面端日志
macOS 桌面端日志默认位于：
|
1 |
~/Library/Logs/com.openai.codex/YYYY/MM/DD |
官方排障文档还列出会话记录目录 $CODEX_HOME/sessions，默认通常是 ~/.codex/sessions。分享之前先搜索并删除 API Key、访问令牌、Cookie、项目机密和完整请求体。
什么时候应该提交支持请求
当问题持续、跨网络复现，或者状态页存在相关事件时，提交一份结构化信息比只写“Codex 502”更容易得到有效处理。
建议准备：
- 使用的入口：Web、桌面端、CLI 或 IDE 扩展。
- Codex 版本、操作系统和认证方式。
- 完整错误文本、HTTP 状态码和 request ID（如有）。
- 发生时间，注明时区，最好同时记录 UTC。
- 是否换过网络、浏览器或入口，以及结果是否变化。
- 脱敏后的日志片段，不要包含密钥、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 状态页信息；错误码、客户端版本和状态组件会持续变化，遇到新故障时应以官方状态页和最新文档为准。
