报错定位：先看 401 出现在哪个环节
Codex 401 Unauthorized 最容易让人误判的地方在于，报错本身几乎不携带病因信息，却可能由完全不同的环节触发。处理顺序一旦搞错，反复折腾账号也未必有效。建议先按下表判断报错出现的时机，再进入成因对照。
- 启动或登录阶段即弹 401：多为认证方式未被识别或令牌已失效，优先运行 codex login status 确认认证方式。
- 任务执行中途突然 401：多为令牌失效或会话状态异常，先保存任务再重登，观察是否一登录就复发。
- 新增密码或完成安全验证后出现：常见于社交登录会话断裂，需走原 Apple/Google 入口重建网页登录。
- 同一时段大量用户同时报错：大概率是官方服务端事故，查看官方状态页并等待恢复。
四类成因对照与可控性判断
官方认证文档明确把 ChatGPT 订阅与 API Key 划为两种认证方式，排查路径完全不同。不要因为报错文案里出现 API key 字样，就要求订阅用户去更换自己的密钥。
- 登录令牌过期或会话失效：典型表现是重登后短暂恢复、随后复发，提示 token invalidated 或要求重新登录；可先重新授权验证，但仍可能复发。
- 社交登录会话断裂：Apple/Google 登录的账号在新增密码后出现 401 循环，仅删本地凭证无效；需重建原社交入口的网页会话，可控性中等。
- API Key 或网关认证错误：提示 Incorrect API key，或自定义网关返回 401；可控性高，核对密钥、项目与网关配置即可。
- 官方服务端事故：同一时段大面积出现，重登、清凭证均无效；可控性低，只能等待官方恢复。
需要提醒的是，2026 年 9 月 26 日曾发生一次官方确认的认证事故（状态页已标 Resolved），当时重登、清认证、换版本都无效。这类历史窗口不能拿来解释今天的每一次 401。
按认证方式分流的六步排查
以下每一步都给出具体操作与判定结果，原则是一次只改一个变量。
- 查官方服务状态：前置打开官方状态页。若有进行中的事件，按官方指引等待或使用其建议的临时路径；否则继续下一步。
- 确认认证方式：终端运行 codex login status。显示 ChatGPT 订阅登录走步骤 3，显示 API Key 走步骤 5。
- 订阅用户重建真实登录：保存未发送的提示词，CLI 执行 codex logout 后 codex login，完成真实浏览器授权；桌面端与 IDE 插件在各自的退出、重登入口操作，CLI 命令并非所有入口的通用修复。判定标准是回到原失败会话并实际完成请求，登录页能打开或新会话偶尔成功都不算恢复。
- 社交登录会话修复：仅适用于 Apple/Google 登录且在新增密码或修改安全设置后出现 401 循环的账号。清理相关浏览器登录会话，改回原登录提供方并重新授权桌面端，不建议所有用户清空浏览器数据。
- API Key 用户核对凭证：核对实际请求目标、所用项目、密钥有效性与权限，必要时在官方平台重新生成并更新客户端。仅当错误明确为 IP not authorized 且项目确实配置了 IP 白名单时，才检查实际出口是否匹配；不要把普通 401 泛化成 IP 封禁。
- 凭证文件清理：先确认当前版本的凭证存储方式并备份，只处理相关的单个凭证文件。当前版本可能使用系统凭证库，删某个 json 文件并非对所有版本有效，更不能删整个 .codex 目录。
此外需保留一条纪律：自定义网关返回 401 时，先区分是网关自身的密钥问题还是向上游传递认证的问题，由网关方查日志定位 401 产生端，不要把网关故障当成账号故障处理。
重登后仍复发：该保留哪些证据
若重登后仍反复 401，先记录完整错误正文、认证方式、客户端版本、失败时间与 request ID，并检查错误中是否明确出现 refresh_token_invalidated、权限错误或 IP not authorized。不同环境下的结果差异可作为进一步排查线索；但单凭反复 401，不能认定出口触发令牌吊销，固定出口能否恢复认证同样无法据此下结论。
若想把登录环境纳入对照，前提是可重复的路径对照：固定账号、版本与任务，只切换网络环境这一变量，记录 401 是否随之变化。网络方案在这一步才进入视野，它只是排除变量的手段，并非认证修复的证明。已完成可重复路径对照、希望固定一条登录线路继续验证的开发者，可参考 https://www.ipxss.com/ 提供的固定归属出口资源，其服务可用性 SLA 达 99.9%，适合固定账号与任务后小批量验收，验收以真实请求完成为准，通过后再放量。需要强调的是，网络对照修不了密钥配错、账号权限或官方事故；证据不足时，把材料交官方支持定位比反复换环境更有价值。
常见问题解答
401 是账号被封了吗
通常不是。401 表示认证未通过，常见情况是令牌过期、会话断裂或撞上官方事故，与账号封禁不属于同一类问题。只有当同一账号跨环境反复出现且伴随其他异常信号时，才需要评估账号侧风险。
为什么重登后恢复，过一会儿又 401
先看刷新失败的完整原文，是否出现 refresh_token_invalidated、权限错误或 IP not authorized，核对认证持久化与登录状态；仍无法定位时，整理完整材料交官方支持。不能仅凭反复 401 就断定是登录环境或出口问题。
报错写着 API key，订阅用户也要换 Key 吗
不要。官方文档明确区分两种认证方式，报错文案不等于你的实际认证方式，先用 codex login status 确认自己属于哪一种。
删除整个 .codex 目录能修 401 吗
不建议。401 发生在认证环节，即使确需重建凭证，也应备份后只移走单个凭证文件。当前版本可能使用系统凭证库，旧教程中的文件路径已不适用。
什么时候该等官方而不是自己排查
同一时段大量用户同时报错、官方状态页有相关事件时。已确认服务端事故时，反复本地清理往往无济于事，应按官方指引等待或使用其建议的临时路径；官方事故也可能与本地问题并存，恢复后仍报错需继续排查本地环节。
总结
Codex 401 Unauthorized 的排查主线是：先查官方状态页排除服务端事故，用 codex login status 分清认证方式，订阅用户重建真实登录，社交登录用户按历史个案条件修复网页会话，API Key 用户核对密钥与权限，凭证清理只动单个文件。重登后仍复发时保留完整证据交官方支持定位；已完成可重复路径对照、希望固定登录线路的开发者，可注册 IPxSS 海外AI网络做小批量对照验收。