Codex 401 Unauthorized 怎么解决？API Key、登录过期与第三方 Provider 逐条排查

结论速查表：看到什么、为什么、怎么修

前四行的错误文本来自 OpenAI 错误码文档，只对 OpenAI 官方接口返回的 401 有效。第三方 Provider 的报错文字不一样，比如 AI Code With 返回的是 {"error":"请在请求中提供有效的 API Key。"}。

401 是什么意思

401 Unauthorized 表示认证没有通过，服务端不确定你是谁。它和 429 不是一回事：429 是“知道你是谁，但你请求太多了”，见《Codex 429 Too Many Requests 怎么解决》；503 容量不足则见《Codex 报错 Selected model is at capacity》。

排查 401 时，先把完整的错误文本留下来，再确认这次请求走的是哪条认证路径。一次只改一个地方，不要同时换 Key、地址和模型，否则修好了也不知道是哪一步起的作用。

第一步：确认你走的是哪条认证路径

Codex 有三条认证路径：

1. ChatGPT 登录：用 ChatGPT 账号登录，用的是订阅额度；
2. OpenAI API Key：用 codex login --with-api-key 登录，Key 存在 ~/.codex/auth.json 或系统凭据库里；
3. 第三方 Provider：在 ~/.codex/config.toml 里配置了 model_provider，比如 AI Code With。

前两条可以用这条命令查看当前状态：

codex login status

第三条路径要注意：Key 写在 config.toml 的 experimental_bearer_token 里时，codex login status 会显示 Not logged in，这是正常的，不代表配置有问题。我们实测时它显示未登录，请求照样跑通。判断这条路径通不通，要看下一节的 codex exec 预检。

显示登录成功，为什么一发请求就 401

很多人遇到的情况是：codex login 提示登录成功，codex login status 也显示已登录，可一干活就 401。原因是登录这一步只是把 Key 存到本地，并不会去服务端检查 Key 对不对。

我们用 Codex CLI 0.163.0 故意填了一个错的 Key 做测试：

codex-401-wrong-key-test

两次的 401 原文分别是这样的。直连 OpenAI、Key 填错时：

ERROR: unexpected status 401 Unauthorized: Incorrect API key provided: sk-wrong****0000. You can find your API key at https://platform.openai.com/account/api-keys., url: https://api.openai.com/v1/responses ... auth error code: invalid_api_key

接 AI Code With、experimental_bearer_token 填错时：

ERROR: unexpected status 401 Unauthorized: {"error":"请在请求中提供有效的 API Key。"}, url: https://api.aicodewith.ai/chatgpt/v1/responses

所以真正可靠的预检是两步：

# 1. 看登录状态（只对 ChatGPT 登录和 OpenAI API Key 有意义）
codex login status

# 2. 发一条最小请求，能回复 ok 才算认证通过
codex exec --skip-git-repo-check "只回复 ok" < /dev/null

第二条命令末尾的 < /dev/null 不能省。codex exec 会等待标准输入，在脚本里不给输入就会一直挂着。Windows PowerShell 里去掉这一段直接运行即可。

codex login status 没登录时退出码是 1，登录了是 0，脚本里可以用它做判断。但它只能说明“本地存了凭据”，不能说明 Key 有效，最终还是要看第二条命令。

路径一：ChatGPT 登录

没有配置 API Key 或自定义 Provider 时，按这条路径排查：

1. 关闭 Codex；
2. 运行 codex logout 清掉缓存的凭据；
3. 运行 codex login，在浏览器里重新登录，注意选对账号和工作区；
4. 重新打开 Codex，用上面的 codex exec 预检。

OpenAI 官方文档说明，ChatGPT 登录的会话会在使用中自动刷新 Token，正常使用时很少需要重新登录。还是 401 的话，先确认登录的是正确的账号和工作区。

服务器上打不开浏览器

没有图形界面的服务器，用设备码登录：

codex login --device-auth

在另一台有浏览器的设备上打开链接，登录后输入一次性代码。

路径二：OpenAI API Key

先确认 Codex 实际读到的是你预期的 Key。重点检查：

1. Key 是否复制完整，没有多出空格、引号或换行；
2. Key 是否属于你正在用的账户、组织或项目；
3. 改了 Key 之后，是否重开了终端或应用；
4. 项目或组织开了 IP 白名单的话，请求是不是从允许的网络发出的。

OpenAI 官方的登录写法是通过标准输入把 Key 交给 Codex：

printenv OPENAI_API_KEY | codex login --with-api-key
codex login status

Windows PowerShell：

$env:OPENAI_API_KEY | codex login --with-api-key
codex login status

OPENAI_API_KEY 怎么在系统里长期保存，见《Codex 环境变量怎么配》。再强调一次：登录成功不代表 Key 有效，最后一定要跑一次 codex exec 预检。

路径三：第三方 Provider

用第三方 Provider 时，Key、Provider 名称、地址和模型名要来自同一份全局配置。不同错误指向不同方向：

• 401：先查 Key 本身，以及配置有没有被 Codex 读到；
• 404：更像是地址或路径写错了；
• model not found：更像是模型名和 Provider 对不上。

两条容易踩的规则：

1. Provider 只能写在全局配置里。项目级 .codex/config.toml 不能覆盖 model_provider 和 model_providers。我们实测把 Provider 只写在项目级配置里，Codex 直接忽略了它，请求发到了 OpenAI 官方地址，报 401 Unauthorized: Missing bearer or basic authentication in header。
2. 命令行的 -c / --config 会覆盖配置文件。脚本里如果带了旧的 -c model_providers.aicodewith.experimental_bearer_token=...，配置文件改得再对也没用。

config.toml 的完整规则见《Codex config.toml 配置指南》。

如果你用的是 AI Code With

AI Code With 的团队标准写法是：Key 直接写在全局 config.toml 的 experimental_bearer_token 里，一个文件管完，不需要再配环境变量或 auth.json。地址以《Codex 接入 AICodeWith》和当天的官方接入文档为准，2026 年 10 月 18 日核对为 https://api.aicodewith.ai/chatgpt/v1。

第一步：创建 API Key

获取 API Key →

第二步：写全局配置

macOS / Linux，打开 ~/.codex/config.toml（没有就新建）：

mkdir -p ~/.codex && nano ~/.codex/config.toml

Windows PowerShell，打开 %USERPROFILE%\.codex\config.toml：

New-Item -ItemType Directory -Force "$env:USERPROFILE\.codex" | Out-Null
notepad "$env:USERPROFILE\.codex\config.toml"

两个系统写进去的内容完全一样：

model_provider = "aicodewith"
model = "gpt-6.1-sol"

[model_providers.aicodewith]
name = "aicodewith"
base_url = "https://api.aicodewith.ai/chatgpt/v1"
wire_api = "responses"
experimental_bearer_token = "sk-你的Key"

name = "aicodewith" 这一行不能少，少了 Codex 会报 provider name must not be empty。model 写的是我们实测跑通的 gpt-6.1-sol，换其他模型前先确认控制台里支持。

第三步：验证

codex exec --skip-git-repo-check "只回复 ok" < /dev/null

我们按上面的配置在 Codex CLI 0.163.0 上实测，第一次运行就跑通，2.7 秒返回 ok。

还是 401 的话，按这个顺序查：

1. experimental_bearer_token 引号里的 Key 前后有没有空格或换行。我们实测在 Key 前后各加一个空格，就会报 401；
2. 这段配置是不是写进了项目目录下的 .codex/config.toml，而不是全局的 ~/.codex/config.toml；
3. 启动命令里有没有 -c / --config 覆盖了 Key；
4. 登录控制台，确认这个 Key 没有被禁用或删除。Key 泄露了或者拿不准，直接新建一个替换。

按错误文本逐条处理

下面是 OpenAI 官方错误码文档里的四种 401。

Incorrect API key provided

请求用的 API Key 不对。最常见的原因是复制时少了字符、多了换行，或者用了一个已经删除的旧 Key。建议直接新建一个 Key，用复制按钮整段复制。

Invalid Authentication

Key 和请求所属的组织对不上。如果你在多个组织或多个项目里，确认这个 Key 是在你预期的那个组织和项目下创建的。

You must be a member of an organization to use the API

账户还不属于任何组织，要请组织管理员邀请你加入。这类 401 和 Codex 配置无关，改配置文件解决不了。

IP not authorized

出口 IP 不在白名单里。在公司网络、VPN、云服务器之间切换时，出口 IP 经常会变，最容易出现这一种。

凭据存在哪里，决定了你该去哪里查

ChatGPT 登录和 OpenAI API Key 这两条路径，凭据可能存在本地文件 ~/.codex/auth.json，也可能存在系统凭据库里，由配置项 cli_auth_credentials_store 决定：

• file：存在 auth.json 里；
• keyring：存在系统凭据库里，凭据库不可用时会失败；
• auto：凭据库能用就用，否则退回 auth.json；
• ephemeral：只存在当前进程的内存里，进程结束就没了。

如果是 keyring 或 auto，auth.json 可能根本不存在，改它自然没用，直接 codex logout 再 codex login 最省事。如果是 ephemeral，每次新开进程都要重新认证，看起来就像“过一会儿又 401 了”。auth.json 的细节见《Codex auth.json 是什么》。

自动化和 CI 里的 401

在 CI、定时任务这类没人值守的环境里，401 的原因往往和本机不同：

1. 确认密钥真的注入了。比如外部贡献者提交的 PR 通常拿不到仓库密钥，Key 是空的，自然 401。
2. 先跑预检再干活。在正式任务前加一条 codex exec "只回复 ok" < /dev/null，失败就直接退出，省得重试十几秒后才发现。
3. 企业工作区可以用访问令牌。官方文档说明，ChatGPT Enterprise 管理员可以让成员创建 Codex 访问令牌，用 printenv CODEX_ACCESS_TOKEN | codex login --with-access-token 登录。

定时运行 Codex 的完整例子见《cron + codex exec 每天自动生成 GitHub Trending 中文日报》。

换了 Key 却还是旧的报错？

改了 Key 之后错误一模一样，先怀疑 Codex 读到的还是旧值：

1. 关掉所有终端和编辑器窗口，重新打开；
2. 检查全局 config.toml 是不是真的保存了，项目目录下有没有另一份 .codex/config.toml；
3. 检查启动命令或脚本里有没有 -c 覆盖；
4. 走 OpenAI API Key 路径的话，运行 codex login status 看显示的 Key 尾号有没有变。

预防 401 的几个习惯

• 一个用途一个 Key：本机、CI、不同项目分开建 Key，哪个出问题只换哪个。
• Key 不进仓库：config.toml、auth.json、.env 都不要提交。
• 改配置前先备份：改 config.toml 前先复制一份，出问题能马上回退。
• Key 泄露就在控制台新建一个替换：旧 Key 立刻禁用或删除，不要等。

常见问题

Codex 401 和 403 有什么区别？

401 是认证没通过，服务端不知道你是谁；403 通常是知道你是谁，但你没有权限访问这个资源。遇到 401，先查 Key 和登录状态。

刚创建的 Key 为什么也报 401？

常见原因是复制时多了空格或换行、Key 属于别的项目或组织，或者 Codex 读到的还是旧配置。重开终端，跑一次 codex exec 预检再看。

ChatGPT 能正常用，Codex 却报 401？

如果 Codex 配的是 API Key 或第三方 Provider，它就不走 ChatGPT 登录，两边互不影响。先确认 Codex 实际走的是哪条认证路径。

配了 experimental_bearer_token 还是 401？

按这个顺序查：

1. Key 前后有没有多余的空格、换行或多一层引号；
2. 是不是写进了项目级 .codex/config.toml，Provider 只认全局配置；
3. 启动时是不是被 --config（-c）覆盖了；
4. 控制台里这个 Key 是不是已经被禁用或删除。

以前用 auth.json 接 AI Code With，要改吗？

能用就不用急着改，新配置建议统一用上面的 experimental_bearer_token 写法。用 auth.json 的话，requires_openai_auth = true 必须写在 [model_providers.aicodewith] 下面，删掉才会报 401。

Failed to refresh token: 401 怎么办？

这个报错出现在 ChatGPT 登录路径上，意思是 Codex 想刷新登录会话，但服务端不认了，比如会话过期或在别处被撤销。处理办法：

1. 运行 codex logout，再 codex login 重新登录；
2. 如果是桌面应用或编辑器插件里报的，重新登录后把应用完全退出再打开；还不行，可以重启本机的 Codex 后台服务：

codex app-server daemon restart

用 experimental_bearer_token 接第三方 Provider 时，Key 是固定写在配置里的，没有刷新 Token 这一步。

插件用着用着突然 401？

插件和连接器（比如 Notion、Linear 这类）有自己独立的授权，和 Codex 本身的登录是两回事。它们的授权过期后，常见的报错是 401 Reauthentication required。处理办法：

1. 在 Codex 的插件设置里找到这个插件，重新连接、重新授权；
2. 用命令行配置的 MCP 服务器，可以先登出再登录：

codex mcp logout 服务器名称
codex mcp login 服务器名称

重新授权后重启 Codex。还是不行，就在插件对应的网站上撤销对 Codex 的授权，再重新授权一次。

401 应该一直重试吗？

不应该。401 是认证问题，重试不会让它自己好。我们实测 Codex 遇到 401 会自动重试，直连 OpenAI 时前后重试 10 次、约 14 秒才退出，这段时间是白等的。先修好认证，再用最小请求验证。

免费注册，换一个专用 Key 重新接入 Codex →

相关阅读

• 《Codex 接入 AICodeWith：专用地址、认证配置与调用验证》
• 《Codex config.toml 配置指南》
• 《Codex API Key 怎么配置》
• 《Codex auth.json 是什么》
• 《Codex 环境变量怎么配》
• 《Codex 429 Too Many Requests 怎么解决》
• 《Codex 报错 Selected model is at capacity 怎么办》

资料来源

• OpenAI：Error codes
• OpenAI：Codex Authentication
• OpenAI：Advanced Configuration