
Codex CLI API Key 配置:auth.json 五步到位
Codex CLI 支持两种登录方式,用哪种直接决定了你走订阅额度还是按量计费。选错方式的人,往往会在 auth.json 上折腾一整晚,最后还是 401。这篇把两种方式的选择标准、配置文件的确切位置和格式、以及 401 的六个成因一次讲清。
前置条件只有一个:Node.js 和 npm 装好,并且能用官方源装包。
先决定用哪种登录方式
| 维度 | ChatGPT 账号登录 | OpenAI API Key 登录 |
|---|---|---|
| 计费方式 | 走 ChatGPT 订阅额度 | 按 OpenAI Platform 标准按量计费 |
| 适合场景 | 日常交互式开发 | 自动化、CI/CD、脚本调用 |
| 获取凭证 | 浏览器 OAuth 授权,凭据自动缓存 | 在 OpenAI 平台后台创建 sk- 开头的 key |
| 额度归属 | 订阅内的用量池 | 账户余额,用多少扣多少 |
| 首次配置成本 | 一条命令 | 需要手写或注入凭证文件 |
如果你每天坐在终端里写代码,选第一种,省事且不按 token 心疼。如果你要把 Codex 塞进流水线、定时任务、或者团队共用一个执行环境,选第二种。
这两种方式在官方层面都支持,CLI 和 IDE 扩展都能用。本文只讲官方路径。把配置文件指向非官方端点的做法不在讨论范围内,那类做法会带来凭证外泄和计费不可控的问题。

安装与确认版本
官方推荐 npm 全局安装,macOS 也可以用 Homebrew cask,GitHub 官方仓库还提供各平台 Release 二进制包,OpenAI 开发者文档里有完整的命令参考。
npm install -g @openai/codex
装完先确认命令能找到:
codex --version
有版本号输出说明 PATH 没问题。codex: command not found 是第一步最常见的卡点,通常是 npm 全局 bin 目录没进 PATH,先 npm bin -g 找到目录,再加进 shell 配置。
Windows 原生支持相对较弱,官方生态里更稳的路径是用 WSL 装 Node 再装 CLI,或者直接用 Codex 应用和 VS Code 扩展。
5 步把 API Key 配置到位
第一步:在 OpenAI 平台创建 key
登录 OpenAI 平台后台,在 API keys 页面创建新密钥,复制下来。这个 key 只会完整显示一次,关掉页面就看不到了。不要把它提交进任何 git 仓库,也不要用别人的 key。
第二步:创建配置目录
Codex 的配置根目录默认是 ~/.codex,也可以用环境变量 CODEX_HOME 指定别的位置。
mkdir -p ~/.codex
第三步:写入 auth.json
这一步是 401 的高发区。文件内容必须是一个合法的 JSON 对象,键名是 OPENAI_API_KEY,值是你的 key:
{"OPENAI_API_KEY": "sk-你的真实密钥"}
三个硬要求:必须是英文双引号;不能有注释、空行、尾随逗号;除了这一个键不要塞别的东西。漏一个大括号、引号用了中文全角、末尾多一个逗号,都会让解析失败并表现成认证错误。
用编辑器直接创建更稳妥,不要用会插入换行或 BOM 的富文本工具存这个文件:
vi ~/.codex/auth.json
第四步:或者改用环境变量注入
不想把 key 落盘的话,可以在启动 Codex 前注入环境变量。macOS 和 Linux 下:
export OPENAI_API_KEY="sk-你的真实密钥"
codex
Windows PowerShell 下:
$env:OPENAI_API_KEY="sk-你的真实密钥"
codex
也可以直接执行 codex login 走一次显式登录流程,它支持设备授权方式,也能通过标准输入把 key 传进去。自动化环境里这一条比手写文件更可控。
第五步:管理凭据存储位置
这一步是很多人不知道的:Codex 的凭证不一定存在明文文件里。config.toml 里有个 cli_auth_credentials_store 配置项,三个取值:
file:凭证明文或简单编码存在CODEX_HOME下的auth.json,最方便也最不安全keyring:交给操作系统凭证存储,macOS 是 Keychain,Windows 是凭据管理器,Linux 是 Secret Serviceauto:优先尝试安全存储,失败再退回文件
个人开发机想快点跑通,用 file。团队环境、共享机器、带生产凭证的机器,换成 keyring。
这里有一个必须提醒的认知差:在 ~/.codex 下找不到 auth.json,并不代表没登录。如果用的是 keyring 模式,凭证被加密存在系统里,目录里当然没有文件。看到空目录就去网上下一个所谓的「auth.json 生成器」,等于把 key 直接送去第三方,这是本末倒置。

验证是否真的跑通了
看三件事,按顺序确认:
codex --version有版本号,说明安装没问题- 启动
codex进入交互界面,模型名能正常显示 - 发一条最简单的任务,能拿到模型回复而不是报错
三步都过,说明认证链路通了。如果第 2 步就卡住,往下看错误码。

401 的六个真实成因
| 现象 | 原因 | 处理 |
|---|---|---|
| 401 Unauthorized,配置看似正确 | auth.json 有多余空格、中文引号、尾随逗号或注释 | 用 cat 逐字核对,或直接重写整个文件 |
| 换了 key 仍然 401 | shell 里残留旧的环境变量,优先级盖掉了文件里的新 key | env 里查 OPENAI_API_KEY,unset 后重启 |
| 明明登录过却提示未认证 | 凭证存在 keyring 里,你以为在文件里 | 检查 cli_auth_credentials_store 的值 |
| 改了 base URL 后全挂 | base URL 与协议类型不匹配,或路径缺 /v1 |
确认端点与 wire_api 设置一致 |
| 模型名报错而非认证错误 | 模型 ID 写错或该 key 无权访问该模型 | 换成账户可用的模型名 |
| 一段时间后突然 401 | key 被撤销、过期或余额耗尽 | 去平台后台看 key 状态和余额 |
排查顺序建议从外到内:先确认请求发到了哪个地址,再确认带的是哪份 key,最后才换 key。跳过前两步直接换 key 的人,换四五个仍然是 401。
一份可照着打勾的检查清单
codex --version有输出~/.codex目录存在auth.json只有一行合法 JSON,键名OPENAI_API_KEYenv | grep OPENAI_API_KEY的结果与你预期一致,没有互相打架的两份cli_auth_credentials_store的值和你实际的凭证位置一致- 没有把 key 写进项目仓库的任何文件
六项全对,剩下的问题一般不在认证层。
想搞清楚 Codex CLI 和 OpenAI 另一套命令行工具的分工,看OpenAI CLI 与 Codex CLI 的区别。额度怎么算、怎么查用量,Codex 使用量查询指南里有具体做法。
刚接触的话建议先读OpenAI Codex 完整指南,用 Plus 额度跑 Codex 的人可以看 GPT Plus 与 Codex 额度说明。
进阶:多 provider 与项目级配置
config.toml 的用户级位置是 ~/.codex/config.toml,项目级放在当前目录的 .codex/config.toml,后者优先级更高。配置的优先级从高到低大致是命令行参数、profile、项目级、用户级、系统级、内置默认值。
这意味着团队可以在项目里固化模型和审批策略,个人在用户级保留自己的偏好,互不干扰。CLI 和 IDE 扩展共用同一套配置体系,改一处两边都生效。
如果遇到「配置文件改了没反应」,先确认路径对不对,再确认 model_provider 名称是否与 [model_providers.xxx] 段匹配,这两个名字不一致是配置静默失效的主要原因。
常见问题
Codex CLI 的 auth.json 应该放在哪个路径?
默认在 `~/.codex/auth.json`,也可以用 `CODEX_HOME` 环境变量指定到其他目录。Windows 下对应的是用户目录下的 `.codex` 文件夹。
auth.json 的正确格式是什么?
内容是一个合法的 JSON 对象,键名 OPENAI_API_KEY,值为 sk- 开头的密钥:{"OPENAI_API_KEY": "sk-xxx"}。不能有注释、空行、尾随逗号,也不能使用中文全角引号。
Codex CLI 提示 401 Unauthorized 怎么排查?
先 `cat ~/.codex/auth.json` 核对格式,再查环境变量里有没有残留的 OPENAI_API_KEY 覆盖了新值,最后确认 base URL 与协议的配置是否匹配。绝大多数 401 出在前两项。
找不到 auth.json 是不是说明没登录成功?
不一定。如果 `cli_auth_credentials_store` 设成了 keyring,凭证会被存在操作系统凭证存储里,目录里不会有明文文件。用 `codex login` 或交互界面确认状态即可。
ChatGPT 账号登录和 API Key 登录可以同时配置吗?
两套凭证来源同时存在时容易互相干扰,表现为换了 key 仍然报错。建议按场景二选一:交互开发用账号登录,自动化和 CI 用 API Key。
用 API Key 后额度和订阅额度会混着扣吗?
API Key 走的是 OpenAI Platform 的按量计费,与 ChatGPT 订阅额度是两套体系,具体扣费以平台后台用量页面为准。

京ICP备2024094994号-29