Codex auth.json 是什么：位置、风险与安全排错

Codex auth.json 是什么？位置、作用、安全风险与 401 排错指南

AI Code With · Codex 实用教程

很多人第一次折腾 Codex 的 API Key、自定义 Provider 或 Base URL 时，最后都会碰到一个文件：

~/.codex/auth.json

然后很容易产生一个误解：既然它是 JSON 文件，那应该就是 Codex 的配置文件吧？

其实不是。

auth.json 更接近一张存着登录凭证的“门禁卡”，而不是一份告诉 Codex“该用哪个模型、请求哪个地址”的普通配置文件。

这一点如果没有弄清楚，后面很容易出现一些奇怪的问题：为了换模型去改 auth.json、401 以后反复覆盖这个文件，甚至把完整内容截图发给别人排错。

更严重的是，如果 Codex 使用文件形式保存登录状态，auth.json 中会包含敏感访问凭证，应该像密码一样对待，不能提交到 Git、贴到工单里或者发到聊天群。

先说结论：auth.json 管“你是谁”，config.toml 管“你要怎么用”

理解 Codex 本地配置，最简单的办法不是背文件名，而是先把两件事情拆开。

auth.json：解决认证问题

它主要负责保存 Codex 已经获得的登录凭证。

你可以把它理解成：Codex 用什么身份去访问对应服务。

config.toml：解决运行方式

例如：当前使用哪个 model、使用哪个 model provider、Base URL 是什么、Provider 怎么定义、请求使用哪种 API。这类东西更接近真正意义上的“配置”。

所以，如果你只是想换模型，通常应该看 config.toml；如果你想把 Codex 从 OpenAI 官方 Provider 换成自定义 Provider，也主要看 config.toml 和对应认证方式。

如果你遇到“明明配置都对，但服务器一直说 401、缺少 API Key”，这时候才应该把“认证凭证到底有没有正确送进去”纳入排查范围。

最重要的一条线：模型、Provider、Base URL 属于配置层；认证凭证属于另一层。

Codex 的 auth.json 到底在哪里？

默认情况下，Codex 的本地状态目录通常是：

~/.codex/

如果使用文件形式缓存凭证，文件通常就是：

~/.codex/auth.json

在 macOS 和 Linux 中，~ 代表当前用户的 Home 目录，例如：

/Users/你的用户名/.codex/auth.json

Windows 则会对应当前用户目录下的 .codex。

但这里有一个特别容易误判的地方：你没找到 auth.json，并不代表 Codex 没登录。

Codex 可以使用文件存储，也可以使用操作系统的凭证存储。常见配置类似：

# file | keyring | auto

cli_auth_credentials_store = "keyring"

其中：

• file：存到 CODEX_HOME 下的 auth.json。

• keyring：交给操作系统的凭证存储。

• auto：能使用系统凭证存储就优先使用，否则再回退到文件。

所以遇到“别人电脑上有 auth.json，为什么我的没有？”时，先别急着自己建一个，你可能只是用了 keyring。

auth.json 为什么不能当普通配置文件？

因为里面不是“无所谓泄露的参数”。如果采用文件型认证缓存，auth.json 里会包含访问 token，因此应该像密码一样保护。

这和下面这种配置完全不是一个安全等级：

model = "gpt-5.6-sol"

模型名被别人看到通常问题不大，但 API Key、Access Token、登录凭证一旦泄露，别人可能直接获得你的调用权限。

所以，下面这种事情看起来只是“问问题”，实际上风险很高：

“我的 Codex 不能用了，谁帮我看看 auth.json？”

然后把整个文件复制到群里。别这么干。排错时应该提供脱敏后的配置、报错文本、Provider 名、Base URL 和模型名称，而不是完整凭证。

哪些情况下，你根本不应该先去改 auth.json？

情况一：只是想换模型

比如你当前模型是 gpt-5.6-sol，想换成另一个模型。这属于模型配置问题，不是认证问题，别去折腾 auth.json。

情况二：只是想换 Provider

如果你准备把 OpenAI 官方 Provider 换成自定义 Provider，核心配置依然应该在 Provider 定义里解决。概念上类似：

model_provider = "my_provider"

[model_providers.my_provider]

base_url = "..."

wire_api = "responses"

这里需要分清楚：Provider 决定请求往哪里发，凭证决定你有没有资格调用。这是两个问题。

情况三：Base URL 写错

这也是配置问题。比如正确请求应该去 A，结果你写成了 B。你就算把 API Key 改十遍，也解决不了 URL 本身错误的问题。

情况四：CLI 能用，Desktop 却一直 401

这个场景非常典型。比如 Codex CLI 正常，但桌面端一直返回 401 Unauthorized。很多人的第一反应是 auth.json 坏了，实际上未必。

这时至少还要检查：CLI 和 Desktop 是否真的用了同一 Provider、API Key 是否都能访问到、Base URL 是否一致、桌面端是否拿到了需要的环境变量、两边是否使用相同认证方式。

“看见 401 = 删除 auth.json”是一个很危险的排错习惯。401 只能证明请求已经到了某个服务，但认证没有通过。

Codex 官方登录应该怎么排查？

如果你走的是 OpenAI 官方认证，第一步不要删文件，先看状态：

codex login status

如果确实需要清掉已有登录状态，再执行：

codex logout

然后重新登录：

codex login

如果使用 API Key，应优先按照当前官方认证方式把 Key 安全地传给 Codex，而不是把完整 Key 长期写进公开脚本或聊天记录。

特别提醒：优先使用官方 logout / login 流程，而不是直接删除整个 ~/.codex 目录。后者可能把你其他配置一起删掉。

一个更实用的 401 排错顺序

1. 先看认证状态

先确认自己现在到底是 ChatGPT 登录、API Key，还是其他认证方式。

2. 再看 Provider

检查 model_provider，避免你以为走 OpenAI，实际请求却发到了自定义 Provider。

3. 再看 Base URL

错误信息里的实际请求 URL 往往比模型名更有价值。

4. 再看 API Key 是否真正进入当前进程

尤其是 CLI 能用、Desktop 不能用时，不要默认两边运行环境完全一样。

5. 最后才考虑重新认证

确认凭证状态异常后，再使用 logout / login，而不是直接删目录。

如果你用 AI Code With 接 Codex，auth.json 又是什么角色？

通过 AI Code With 这类自定义 Provider 接入 Codex 时，通常会同时涉及“凭证”和“Provider 配置”两层。

一个典型思路是：auth.json 或其他安全凭证存储负责保存 Key；config.toml 负责 Provider、Base URL、模型和请求方式。

{

"OPENAI_API_KEY": "你的_API_KEY"

}

与此同时，Provider 与 Base URL 应在 config.toml 中配置。

auth.json = Key；config.toml = Provider + Model + Base URL。

虽然两个文件经常一起配置，但职责不同。遇到问题时，把它们拆开排查会快很多。

更推荐的做法：给 Codex 单独建一个 Key

不要把同一个 Key 到处复制给 Codex、Claude Code、测试脚本、网站和其他设备。短期看方便，长期非常难排查。

更好的方式是按用途创建独立 Key，例如：

Codex-MacBook

Claude-Code-MacBook

测试项目-A

服务器-B

这样哪天 Codex 这把 Key 真泄露了，你只需要撤销它，其他项目不会一起被牵连。

AI Code With 的 API Key 管理也适合这种“专钥专用”的方式：不同用途单独创建、清晰命名，需要轮换时只动对应 Key。

现实例子：为什么专钥专用很重要？

假设你同时在用 Codex、Claude Code 和公司内部脚本，为了省事全部用了 Key-A。

有一天你为了排查 Codex，不小心把 auth.json 截进了教程截图。

这时候问题不是“Codex 的 Key 泄露了”，而是三个系统共用的 Key 都可能泄露。你必须一起检查和迁移。

如果一开始就是：

Key-Codex

Key-Claude

Key-Internal

那你只需要：

撤销 Key-Codex

↓

创建新 Key

↓

重新配置 Codex

事情就结束了。

Key 管理真正有价值的地方，不是“能不能创建”，而是出了问题能不能把影响范围锁小。

auth.json 泄露以后，只删除文件是不够的

假设你不小心把 auth.json push 到 GitHub、截图发进群、放进公开 Issue，或者粘到了在线工具。

这时候只执行：

rm ~/.codex/auth.json

并不能让已经泄露出去的凭证自动失效。你删除的只是自己电脑上的副本。

更稳的处理顺序是：

• 停止继续传播。

• 去对应服务撤销或轮换凭证。

• 如果进入 Git，检查提交历史，而不只是当前文件。

• 检查工单、聊天记录、截图等其他副本。

• 确认旧凭证确实无法继续使用。

特别是 Git：删掉当前文件 ≠ 从历史里消失

例如你执行 git rm auth.json 并重新提交，最新版本确实没有这个文件了，但之前的 Commit 仍可能包含敏感内容。

真正发生过凭证泄露时，优先级永远应该是：先撤销凭证，再考虑清理历史。因为只要旧 Key 已经被废掉，即使别人以后翻到了那个值，也不能再继续调用。

还有一个容易被误解的地方：auth.json 不是“永远不能复制”

正常个人使用中，不要随便复制、发送、上传 auth.json，这个原则没有问题。

但在受信任、受控的远程或无浏览器环境中，认证缓存可能存在迁移需求。这里的关键不是“能不能复制”，而是是否处于明确、可信、受控的基础设施场景。

更准确的说法是：auth.json 不是普通配置文件，不应该为了省事到处复制。

file、keyring、auto，到底应该选哪个？

keyring

把凭证交给操作系统的凭证存储。优点是减少敏感凭证以普通文件形式暴露的机会。

file

凭证存在 auth.json。优势是可见、容易迁移，但你必须真正把这个文件当密码管理。

auto

优先使用系统凭证存储，不可用时再回退到文件。

重点不是神化某一种方式，而是知道自己现在用了哪一种。否则排错时你可能一直找一个根本不存在的 auth.json。

我到底能不能打开 auth.json 看？

可以看。“敏感文件”不代表“用户自己不能打开”。真正需要避免的是随便修改、完整截图、复制进在线工具、提交 Git、发给客服或群聊。

如果只是为了确认它到底存不存在，可以先看目录：

ls -la ~/.codex

但如果真的需要查看内容，注意终端屏幕本身也可能进入截图、录屏或日志。能不展示完整凭证，就别展示。

遇到 401 时，可以按这张表快速判断

最后，把 auth.json 当成钥匙，而不是说明书

auth.json 管认证，config.toml 管配置。

模型、Provider、Base URL 配错了，不要反复折腾认证文件。认证真的有问题，也不要上来就删除整个 .codex。

更稳的思路是：

先确认认证方式

↓

再确认 Provider

↓

检查 Base URL

↓

确认 Key 是否真正生效

↓

必要时重新登录

如果你走的是 AI Code With 这类自定义 Provider，最好再多做一步：给 Codex 单独创建一个 Key。这样以后碰到 401、换电脑、换 Provider 或怀疑 Key 泄露时，排查起来会简单很多。

真正安全的凭证管理，不是让你“不敢碰配置”，而是让你清楚知道：哪个文件负责什么，哪把钥匙出了问题，以及出了问题以后该换哪一把。

相关阅读

• Codex API Key 怎么配置

• Codex config.toml 配置指南

• Codex Provider 怎么切换

• Codex Desktop 401 / Unauthorized 排错

• AI Code With 创建与管理 API Key

资料来源

OpenAI Codex Authentication：https://developers.openai.com/codex/auth

AI Code With 创建与管理 API Key：https://docs.aicodewith.com/zh/docs/create-api-key

AI Code With Codex CLI 文档：https://docs.aicodewith.ai/zh/docs/codex-cli