Codex 401 Unauthorized 报错原因与修复
截至 2026-10-07，Codex CLI 与 IDE 扩展报 401 Unauthorized 时，对照官方文档要查三处：当前的认证方式（codex login status）、凭据存放处（~/.codex/auth.json 或系统凭据库），以及自定义 provider 在 config.toml 里 model_provider、env_key 与 requires_openai_auth 的组合。修法是重新 codex login、用 printenv OPENAI_API_KEY | codex login --with-api-key 换成 API key，或把 key 放到 provider 实际读取的位置。本页按 OpenAI Codex 官方文档与 changelog 原句整理，并给出接 QCode 时的写法。
更新于 2026-10-08
先弄清这四点
官方登录方式
ChatGPT 登录用订阅额度，API key 登录按用量计费；官方写明用 API key 登录时按标准 API 价计费、不用 ChatGPT 套餐额度。CLI、IDE 扩展与桌面应用都支持这两种。
凭据缓存
登录信息缓存在 ~/.codex/auth.json 或系统凭据库，CLI 与 IDE 扩展共用；在其中一处退出登录，另一处下次启动也要重新登录。
自定义 provider 的 key 来源
env_key 指定 Codex 从哪个环境变量读 key；官方写明 requires_openai_auth = true 时 Codex 忽略 env_key，改用 OpenAI 认证。
QCode 文档的判读
QCode 文档的判读：401 是密钥问题，404 是路径前缀错了；Codex 的 base_url 多一段、少一段都会 404。
401 是什么意思、先查什么
截至 2026-10-07，Codex 报 401 Unauthorized，意思是服务端没有接受这次请求带的凭据，或者请求根本没带凭据。官方文档写明 Codex 有两种登录方式：Sign in with ChatGPT（订阅额度）与 Sign in with an API key（按用量计费），桌面应用、Codex CLI 与 IDE 扩展都支持，Codex cloud 只能用 ChatGPT 登录。没有有效会话时，codex login 走浏览器登录是默认路径；codex login status 显示当前的认证方式。接自定义 provider 时还要看 config.toml：model_provider 默认是 openai；provider 设了 requires_openai_auth = true 就用 OpenAI 认证并忽略 env_key；只设 env_key 就从那个环境变量读 key；两者都不设，官方写明 Codex 认为该 provider 不需要认证。
近期改动与用户报告
官方 changelog 里有几条与登录相关的改动（见下方时间线），其中 2026-10-01 的 0.160.0 在文档里澄清了 provider 凭据如何使用所配置的存储后端、env_key 如何指定存放 API key 的环境变量。另一方面，GitHub openai/codex 上 2026-09-25 开了一个标题为「unexpected status 401 Unauthorized issue」的 issue，有用户报告在 ChatGPT 登录模式下也看到 Incorrect API key provided（用户报告，官方没有说明原因）。本页只把这类 issue 当作「很多人遇到」的背景，处理步骤以官方文档为准。
官方 changelog 里与登录相关的三条
Codex CLI 0.156.0：登录可以经系统代理恢复；同一条还修了 OAuth 发现返回 503 错误时 MCP 凭据的刷新。
Codex CLI 0.159.0：本地 ChatGPT 登录能可靠地打开浏览器，引导界面还提供了复制登录链接的快捷方式。
Codex CLI 0.160.0：文档澄清 provider 凭据如何使用所配置的存储后端，以及 env_key 如何指定存放 API key 的环境变量。
已确认 vs 没有核实到的
已确认（官方文档逐字可核）
以下都能在官方文档里逐字核到：两种登录方式及适用范围；codex login、printenv OPENAI_API_KEY | codex login --with-api-key、codex login --device-auth、codex login status、codex logout 的作用；登录信息缓存在 ~/.codex/auth.json 或系统凭据库（官方示例配置把 cli_auth_credentials_store 的默认值标为 file，即存进 auth.json），CLI 与 IDE 扩展共用，两者也共用同一套配置层；ChatGPT 会话在使用中会在过期前自动刷新 token；model_provider 默认是 openai；requires_openai_auth = true 时忽略 env_key；项目内 .codex/config.toml 里的 model_provider、model_providers、openai_base_url 会被忽略并打印启动警告；0.134.0 起 --profile 不再读取 config.toml 里的 [profiles.名字] 表；wire_api 只支持 responses；不能自建 [model_providers.openai]，改内置 provider 的地址要用 openai_base_url。
未证实与官方未说明
两件事本页没有核实到，别据此下结论：① GitHub issue 里关于 ChatGPT 登录也出现 401 的原因，只有用户的推测，官方文档没有说明；② 本页没有在官方文档里检索到 Codex 各种 401 报错原文的完整对照表，下文引用的报错字符串，除注明出自文档的以外，都来自用户报告。
两组最容易混的设置
ChatGPT 登录 vs API key
ChatGPT 登录用订阅额度，走浏览器（codex login），远程或无浏览器环境用 codex login --device-auth；API key 登录按标准 API 价计费，CLI 用 printenv OPENAI_API_KEY | codex login --with-api-key，IDE 扩展在未登录界面选 Use API Key。官方把 API key 作为自动化的推荐默认方式；非交互的 Codex 进程也可以用 CODEX_API_KEY 环境变量提供 key。要换方式，先 codex logout 清掉当前凭据再登录。
env_key vs requires_openai_auth
这是自定义 provider 的两种认证方式。env_key = "变量名" 让 Codex 从这个环境变量读 key，变量名由你自己定，必须和你实际 export 的名字一致；requires_openai_auth = true 让 provider 用 OpenAI 认证（ChatGPT 登录或 API key），官方写明此时 Codex 忽略 env_key。两者都不设，Codex 认为该 provider 无需认证。官方另有 experimental_bearer_token 可直接写 token，但文档标注不推荐，建议用 env_key。
按这个顺序排查
① 跑 codex login status，看当前是 ChatGPT 登录还是 API key（已登录时以 0 退出）。② 用 OpenAI 自家服务时：先 codex logout，再按需要跑 codex login（浏览器登录 ChatGPT）、printenv OPENAI_API_KEY | codex login --with-api-key（换成 API key）或 codex login --device-auth（远程、无浏览器环境）；IDE 扩展与 CLI 共用登录缓存，CLI 修好后 IDE 扩展也会沿用。③ 用自定义 provider 时：把 model_provider 与 [model_providers.名字] 写在 ~/.codex/config.toml，项目内 .codex/config.toml 里的这两个键会被忽略；用 --profile 时把设置放进 ~/.codex/名字.config.toml。④ 接 QCode：docs 给出的 config.toml 是 model_provider = "crs"、model = "gpt-6-sol"、model_reasoning_effort = "high"、preferred_auth_method = "apikey"，再加 [model_providers.crs] 表：name = "crs"、base_url = "https://api.qcode.cc/openai"、wire_api = "responses"、requires_openai_auth = true、env_key = "CRS_OAI_KEY"（provider 名与变量名可自定，文档示例用 crs 与 CRS_OAI_KEY；因为有 requires_openai_auth = true，官方写明 Codex 会忽略 env_key，密钥以下面的 auth.json 为准）；~/.codex/auth.json 写 {"OPENAI_API_KEY": "cr_xxxxxxxxxx"}，换成你自己的 cr_ 密钥，文件权限设为 600。⑤ 自测：带 Authorization: Bearer 与你的密钥请求 https://api.qcode.cc/openai/v1/models，返回 JSON 列表说明地址与密钥都对。
在 QCode 上
在 QCode 上，Codex 只用 GPT 系模型；Claude 与 DeepSeek、GLM、Kimi、Qwen 等国产模型都不走 Codex 所用的 OpenAI Responses 协议。config.toml 的 base_url 写 https://api.qcode.cc/openai 并配 wire_api = "responses"；密钥是控制台里 cr_ 开头的 QCode 密钥，按 docs 写进 ~/.codex/auth.json 的 OPENAI_API_KEY。docs 另列了一种可选替代方案：只设 env_key 指定的环境变量，并把 auth.json 里的 OPENAI_API_KEY 设为 null；但这份配置里有 requires_openai_auth = true，官方写明此时 Codex 忽略 env_key，所以不建议只靠环境变量提供密钥。docs 的默认模型是 gpt-6-sol，也可以换成 gpt-6.1-sol 或 gpt-5.6-terra。报 401 时按 docs 查：密钥是否以 cr_ 开头、auth.json 里的密钥是否完整（没有多余空格或换行）、控制台里的密钥状态与剩余配额；密钥错时 QCode 返回 Invalid API key。base_url 多一段、少一段报的是 404，不是 401。按 token 计费，各模型单价见 /models。
常见问题
Codex 报 401 Unauthorized，第一步查什么？
先跑 codex login status。官方文档写明它显示当前的认证方式，已登录时以 0 退出。确认是 ChatGPT 登录还是 API key 之后，再看 Codex 连的是 OpenAI 还是自定义 provider：连 OpenAI 就重新登录或换 key；连自定义 provider 就检查 model_provider 指向的那个 provider 用哪种认证（env_key 还是 requires_openai_auth），以及 key 有没有放在它读取的位置。
ChatGPT 登录和 API key 怎么切换？
先 codex logout 清掉当前凭据，再用另一种方式登录。官方写法：ChatGPT 登录跑 codex login，在浏览器里完成；API key 用 printenv OPENAI_API_KEY | codex login --with-api-key 从标准输入读入；IDE 扩展在未登录界面选 Sign in with ChatGPT 或 Use API Key。CLI 与 IDE 扩展共用登录缓存。如果管理员设了 forced_login_method，凭据不符合限制时 Codex 会登出并退出。
用了一阵子突然 401，是 token 过期了吗？
如果用的是 ChatGPT 登录，先按登录态失效处理：codex logout 后重新 codex login。官方文档写明 ChatGPT 会话在使用中会在过期前自动刷新 token，正在用的会话通常不需要再走一次浏览器登录。GitHub 上有用户报告登录态失效时看到 Provided authentication token is expired. Please try signing in again. 或 Your access token could not be refreshed because your refresh token was revoked. Please log out and sign in again.（均为用户报告）。远程或无浏览器环境用 codex login --device-auth 登录。
自定义 provider 设了 env_key，key 也 export 了，为什么还是 401？
先看同一个 provider 里有没有 requires_openai_auth = true：官方文档写明这时 Codex 忽略 env_key，改用 OpenAI 认证（ChatGPT 登录或 API key）。没有这一项时，再核对 env_key 的值是否和你 export 的变量名完全一致；官方写明 Codex 读的是 env_key 指定的那个变量，变量名本身不是固定的。GitHub 上有用户报告，没配置凭据时看到 401 Unauthorized: Missing bearer or basic authentication in header（用户报告）。
改了 config.toml，Codex 好像还在用默认的 OpenAI？
先查 provider 设置是否写在 Codex 会读取的位置。官方文档写到三种情况：项目内 .codex/config.toml 里的 model_provider、model_providers、openai_base_url 会被忽略并在启动时警告；Codex 0.134.0 起 --profile 不再读取 config.toml 里的 [profiles.名字]，要改用 ~/.codex/名字.config.toml；内置 ID openai、ollama、lmstudio 不能被自定义 provider 占用，只想改 OpenAI 的地址就用 openai_base_url。另外，model_provider 不写时默认是 openai。
接 QCode 时报 401 怎么查？
按 QCode 文档的顺序查：密钥是否以 cr_ 开头、~/.codex/auth.json 里的密钥是否完整（没有多余空格或换行）、控制台里的密钥状态与剩余配额；docs 还把订阅过期列为 401 的原因之一。如果你用的是 docs 的可选方案（只设环境变量、auth.json 里是 null），先改回把密钥写进 auth.json：配置里有 requires_openai_auth = true 时，官方写明 Codex 忽略 env_key。环境里残留的旧变量会覆盖当前配置，可以跑 env | grep -i openai 清掉不用的。然后带 Authorization: Bearer 与密钥请求 https://api.qcode.cc/openai/v1/models 自测，返回 JSON 列表就说明地址与密钥都对。docs 的判读是 401 = 密钥问题、404 = 路径前缀错了；Codex 的 base_url 应写 https://api.qcode.cc/openai。
信息来源
OpenAI 侧：Codex 官方文档的 Authentication、Config basics、Advanced Configuration、Configuration Reference、Environment variables、命令行选项与 IDE 扩展设置页（developers.openai.com/codex 与 learn.chatgpt.com 上是同一套文档），以及 Codex changelog 与 GitHub openai/codex 的 0.156.0、0.159.0、0.160.0 发布说明，均于 2026-10-07 抓取。QCode 侧：QCode 文档的 Codex 完整教程（更新于 2026-09-30）、接入点与 API 格式、错误码参考、故障排查指南与 Cursor 接入页，同日抓取。需求背景：GitHub openai/codex 的 issue 48237 及另外几个与 401 相关的 issue，只作为用户报告引用。
相关阅读
Codex CLI 接第三方 API：config.toml 与报错
config.toml、base_url 的完整写法与常见报错。
Codex 与 ChatGPT Pro 封号原因解析
Codex 与 ChatGPT Pro 账号被停用的原因与处理。
Codex「Selected model is at capacity」怎么区分与处理
不是额度、不是 429：容量报错的判读与应对。
本页步骤与引语核对于 2026-10-07，以 OpenAI Codex 官方文档、changelog 与 QCode 文档为准，上游调整不另行通知。GitHub issue 中的报错与描述均为用户报告，不代表官方结论。模型可用性以 /models 为准。