Codex CLI API Key 配置:auth.json 五步到位封面图
AI 编程约 10 分钟

Codex CLI API Key 配置:auth.json 五步到位

AI 指南··◉ 0 浏览

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 扩展都能用。本文只讲官方路径。把配置文件指向非官方端点的做法不在讨论范围内,那类做法会带来凭证外泄和计费不可控的问题。

{{Codex CLI 首次启动时的登录方式选择界面截图}}

安装与确认版本

官方推荐 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 Service
  • auto:优先尝试安全存储,失败再退回文件

个人开发机想快点跑通,用 file。团队环境、共享机器、带生产凭证的机器,换成 keyring。

这里有一个必须提醒的认知差:在 ~/.codex 下找不到 auth.json,并不代表没登录。如果用的是 keyring 模式,凭证被加密存在系统里,目录里当然没有文件。看到空目录就去网上下一个所谓的「auth.json 生成器」,等于把 key 直接送去第三方,这是本末倒置。

{{Codex CLI 凭证存储模式 file keyring auto 对应位置示意图}}

验证是否真的跑通了

看三件事,按顺序确认:

  1. codex --version 有版本号,说明安装没问题
  2. 启动 codex 进入交互界面,模型名能正常显示
  3. 发一条最简单的任务,能拿到模型回复而不是报错

三步都过,说明认证链路通了。如果第 2 步就卡住,往下看错误码。

{{Codex CLI 交互模式启动后模型名与认证状态显示截图}}

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_KEY
  • env | 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 订阅额度是两套体系,具体扣费以平台后台用量页面为准。

评论 (0)

?
0/1

还没有评论,来发第一条吧

网站上的服务均为第三方提供,
请用户注意自行甄别。

北京酷讯互动科技有限公司

备案京ICP备2024094994号-29

© 2026 AI345 · All Rights Reserved

用户服务协议·隐私政策