故障处理
Codex 登录失败怎么处理？401 与 token exchange failed 排查指南
Codex CLI 登录失败、401 Unauthorized 或 token exchange failed 时，按登录方式、凭据、浏览器回调和远程环境逐步排查，并确认修复是否生效。
浏览器已经显示登录完成，终端却仍报错；或者昨天还能用，今天出现 401 Unauthorized。这两种情况看起来都像“Codex 登录失败”，但检查起点不同：先确认错误发生在登录过程中，还是已经登录后的模型请求中，再选择下面的处理路径。
本文以 Codex CLI 为主。IDE 扩展也可参考凭据部分，但扩展的操作入口不同。不要先删除整个 ~/.codex：里面还可能有配置、规则和会话记录。
先对照错误现象，找到检查起点
| 你遇到的现象 | 先检查什么 | 应看到的结果 |
|---|---|---|
codex login 失败，出现 token exchange failed |
登录流程、浏览器回调、终端所在机器和网络 | 登录流程完成后，当前终端的登录状态有效 |
| 浏览器显示成功，终端仍等待或未登录 | 浏览器回调能否到达运行 CLI 的环境 | CLI 结束等待，codex login status 能识别登录方式 |
登录状态有效，开始任务才出现 401 Unauthorized |
本次使用的账号、API Key、模型服务配置 | 凭据与请求的服务匹配，最小请求不再返回 401 |
403 Forbidden |
返回错误的服务、账号或组织权限 | 先定位访问被拒绝的对象，不把它直接当密码错误 |
429、rate limit 或额度提示 |
完整错误正文中的限流或额度原因 | 按对应限制处理，不连续重登 |
certificate、TLS、连接超时 |
网络连接、企业证书和代理配置 | HTTPS 连接成功；不通过关闭证书校验解决 |
如果错误来自自定义服务地址，保留服务名称这一线索。 第三方服务返回的 401，不能仅靠重新登录 OpenAI 账号解决。
第一步：确认正在用哪个 Codex，以及登录状态
在出错的同一个终端中执行：
codex --version
codex login --help
codex login status前两个命令用来确认版本和当前版本支持的登录参数；第三个命令检查认证状态，不会启动新的模型任务。
- 没有有效登录：继续下一节，按你原本打算使用的登录方式登录。
- 有有效登录，但任务仍报 401：先检查“凭据与配置”一节，不必立刻注销。
- 命令不存在，或版本与你以为的不一样：先解决安装入口问题。macOS/Linux 可用
command -v codex，PowerShell 可用Get-Command codex检查实际执行位置。
如果你在 WSL、Docker 或 SSH 中运行 CLI，这些检查也要在那个环境里执行。宿主机终端登录成功，并不能证明容器或另一台主机也有相同凭据。
第二步：区分 ChatGPT 登录与 API Key 登录
这两种方式对应不同的认证和计费路径。你需要恢复的是原来的路径，而不是为了消除报错随意换一种方式。
使用 ChatGPT 账号登录
codex login按提示完成浏览器登录，然后回到原终端执行 codex login status。核对浏览器选择的账号与工作区是否就是你想使用的那个。
成功标准： CLI 不再等待登录回调，登录状态能识别认证方式。浏览器中的“成功”页面只是其中一步。
使用 API Key 登录
如果你已经将正确的 OpenAI API Key 放进当前进程的 OPENAI_API_KEY 环境变量，macOS/Linux 可按官方方式通过标准输入登录：
printenv OPENAI_API_KEY | codex login --with-api-keyPowerShell 对应写法：
$env:OPENAI_API_KEY | codex login --with-api-key变量不存在或值为空时，先在自己的本地环境中配置它。不要把真实密钥直接贴进命令、文章评论或求助截图。
成功标准： 登录状态对应你选择的认证方式。如果随后请求返回额度错误，再核对 API 账户的额度与权限。ChatGPT 订阅和 API 计费的关系可参考Plus、Codex 与 API 区别。
第三步：401 仍然出现，检查凭据与实际配置
按下面顺序核对，每次只纠正一个已经确认的差异，再重复登录状态检查。
- 确认配置目录。 检查当前进程是否设置了
CODEX_HOME；未设置时，默认目录通常是~/.codex。不同用户、WSL 或容器可能使用不同目录。此处只检查路径，不输出认证文件正文。 - 确认凭据保存位置。 官方支持文件和系统凭据存储等方式。没有
auth.json，不一定表示没有登录；使用系统凭据存储时，应通过codex login status检查，而不是强行创建该文件。 - 确认本次使用的服务配置。 如果使用了配置 profile、自定义
model_provider或服务地址，检查该服务要求哪一种凭据。向自定义服务发送请求时，默认 OpenAI 登录状态不能证明该服务会接受它。 - 确认组织限制。 受管理环境可能限制登录方式或工作区。报错明确指向这些限制时，将脱敏错误交给管理员核对，不自行绕过管理配置。
auth.json 可能包含访问令牌。不要用“把这个文件贴出来看看”的方式排查，也不要直接修改里面的 token 字段。
什么时候才需要注销后重新登录？
当你已经确认登录了错误账号、需要主动切换认证方式，或正确环境中的认证仍持续失败时，可以使用官方注销命令，再按上一节重新登录：
codex logout
codex loginAPI Key 用户重新登录时使用上一节的 API Key 命令。CLI 与 IDE 扩展可能共享缓存的认证信息，注销后另一个入口也可能需要重新登录。
验证结果： 新登录状态正确，原来失败的最小请求不再返回 401。仅看到登录成功，而未检查原错误是否消失，还不能算修复完成。
token exchange failed：检查浏览器回调与网络
token exchange failed 表示登录流程中的令牌交换没有完成。它本身并没有告诉你是账号、网络还是运行环境的问题，应结合相邻错误和发生步骤判断。
浏览器和 CLI 在同一台机器
重新发起一次登录，使用本次命令给出的链接完成流程，观察错误具体发生在哪一步。如果浏览器已经成功而终端仍在等待，检查本地回调连接是否被代理、端口占用或网络策略影响。
如果同时出现 TLS 或证书错误，应先处理那个明确的网络错误。在公司网络中使用受信任的证书配置，并按官方认证文档的证书说明处理；不要关闭 TLS 验证。
验证结果： 浏览器流程完成后，原终端退出登录等待，登录状态有效。如果仍出现同样的交换错误，记录时间、版本与脱敏错误，不无限重复登录。
CLI 在远程服务器、容器或 WSL 中
浏览器访问的 localhost 与运行 CLI 的环境未必相同。如果常规浏览器回调无法到达 CLI，且账号或工作区允许设备码登录，可使用：
codex login --device-auth设备码登录在官方资料中标为 beta，需要对应账号安全设置或工作区权限允许。使用自己终端中显示的官方链接完成认证；不要把一次性代码发给其他人。不可用时，查看官方 headless 登录说明中的适用方案，或请工作区管理员确认。
验证结果： 在远程环境内部运行 codex login status 能识别有效登录。不是只在本机浏览器中看到成功。
最后验证：登录状态与实际任务都要通过
先检查状态，再在一个不含敏感资料的测试目录中启动 codex，给它一个明确的只读任务，例如：
只回答 OK，不读取项目文件、不运行命令、不修改文件。
这个步骤会实际使用模型，并可能消耗订阅额度或 API 费用。它验证的是模型请求，不是免费的离线诊断命令。
- 状态有效、请求成功：认证路径可以工作，再回原项目重试。
- 状态有效、仍报 401：回查实际服务、配置和凭据匹配关系。
- 错误变成 403、429 或额度提示：说明下一步要按新的错误原因处理，继续注销通常没有帮助。
仍然失败时，准备哪些信息？
向官方支持、服务提供方或管理员求助时，提供 CLI 版本、系统与运行环境、登录方式、错误发生阶段、可重复步骤、出错时间及脱敏错误文本。近期版本还可参考官方说明中的 codex-login.log 登录诊断日志；路径和支持情况以当前版本为准。
删除密钥、访问令牌、Cookie、认证链接中的敏感参数和工作资料。不要上传完整认证文件。
如果问题涉及路径、依赖或一般权限，继续参考Codex 常见故障排查；登录恢复后需要继续原任务，可查看恢复上次会话的方法。