PAYATHON 2026

MacBook 上 Codex 无法使用 API key 登录

架构老王

结论

preferred_auth_method = "apikey" 只是指定优先使用 API key，不会自动把 $OPENAI_API_KEY 提交给 Codex。即使 echo $OPENAI_API_KEY 能输出内容，也只能说明变量存在于当前 shell，不能说明 Codex 已经完成 API key 登录。

先退出原有的 Web 登录状态，再通过专用登录命令将环境变量中的 key 传给 Codex：

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

如果仍然出现 Login Failed，请继续检查 key 格式、环境变量作用域、网络代理，以及 API 项目的余额和权限。

为什么配置后仍然登录失败

下面的配置：

preferred_auth_method = "apikey"

以及命令：

codex --config preferred_auth_method="apikey"

只控制认证方式的选择，不包含凭据。它们不会把环境变量中的值写入 Codex 的认证存储，也不能代替登录操作。

登录界面中的 Login Failed 是通用错误，并不一定表示 Codex 完全没有读取到 key。常见原因包括：

  • key 中含有引号、空格或换行；
  • key 已被撤销、复制不完整，或者属于其他 API 项目；
  • 当前进程没有继承该环境变量；
  • 旧的 Web 登录状态或本地认证缓存发生冲突；
  • 网络、代理、证书或防火墙阻止了 API 请求；
  • API 账户没有可用额度，或者项目设置了预算上限；
  • Codex 版本较旧，不支持当前的登录命令或配置方式。

推荐的重新登录方法

先确认变量是否存在于当前终端会话，但不要直接打印完整 key：

if [ -n "$OPENAI_API_KEY" ]; then
  echo "OPENAI_API_KEY is set"
else
  echo "OPENAI_API_KEY is not set"
fi

退出已有认证：

codex logout

通过标准输入完成 API key 登录：

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

最后检查登录状态：

codex login status

如果当前安装的版本不识别 --with-api-key，请先查看该版本支持的参数：

codex login --help
codex --version

不同版本的命令行界面可能有所不同，请以本机 --help 的输出为准。

检查环境变量的内容

设置变量时，不要把引号保存为 key 的一部分：

export OPENAI_API_KEY="sk-..."

这里的双引号由 shell 处理，不会进入变量值。需要重点排查的是首尾空白和换行。可以只检查长度，不输出凭据：

printf '%s' "$OPENAI_API_KEY" | wc -c

也可以重新设置变量：

unset OPENAI_API_KEY
export OPENAI_API_KEY="粘贴完整的 API key"
printenv OPENAI_API_KEY | codex login --with-api-key

不要使用下面这种可能引入额外字符的写法：

export OPENAI_API_KEY="'sk-...'"

内层的单引号可能成为变量值的一部分，导致认证失败。

检查变量是否对 Codex 进程可见

在 macOS 中，终端 shell、图形界面应用和 IDE 内置终端中的环境变量并不总是相同。即使变量已经写入启动文件，也不会自动进入之前打开的终端。

如果使用 zsh，可以加入以下配置：

export OPENAI_API_KEY="sk-..."

常见的配置文件位置是：

~/.zshrc

保存后重新打开终端，或者在当前会话中加载配置：

source ~/.zshrc

然后在同一个终端中执行登录命令：

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

如果 Codex 是从 IDE、Launchpad 或其他图形界面启动的，不能根据普通 Terminal 中的 echo 结果判断它能否读取该变量。更稳妥的做法是在确认变量存在的同一个终端进程中完成登录。

排除旧登录状态和本地凭据冲突

从 Web 登录切换到 API key 时，应先执行：

codex logout

然后再重新登录。不要直接删除 ~/.codex，这个目录中可能还保存着配置、会话或其他本地数据。

如果退出后仍然自动恢复为原来的 Web 登录状态，请先确认 codex logout 是否成功，并检查当前状态：

codex login status

只有在明确确认本地认证数据已经损坏，并且备份了相关内容后，才考虑清理认证存储。具体存储位置可能随 Codex 版本和系统密钥链的实现而变化，不要盲目删除整个配置目录。

检查 API 账户和计费状态

ChatGPT 或 Codex Web 的订阅额度与 OpenAI API 余额属于两个独立的计费体系。API key 必须来自已经启用 API 计费的项目。

请确认：

  • key 尚未被撤销；
  • key 属于当前准备付费的 API 项目；
  • API 账户有可用余额或有效付款方式；
  • 项目预算、组织预算和使用上限没有设为 0；
  • 该项目允许调用 Codex 当前使用的模型；
  • 没有使用其他账户或其他组织创建的 key。

“已经充值”本身不能证明该 key 所属项目一定可以消费。账户、组织、项目和 key 的归属必须相互对应。

检查网络和代理

如果 key 确实有效，但登录仍然失败，请检查当前网络能否连接 OpenAI API。企业网络、代理软件、HTTPS 检查和自定义证书都可能导致 CLI 登录失败。

先检查是否设置了代理变量：

env | grep -i proxy

如果正在使用代理，请确认 HTTPS_PROXY、HTTP_PROXY 和 NO_PROXY 的配置正确。也可以暂时切换到不经过企业代理的网络进行对比，从而判断问题是否出在网络层。

建议的最短排查流程

按下面的顺序执行，通常可以定位问题：

codex --version
codex login --help
codex logout

if [ -n "$OPENAI_API_KEY" ]; then
  echo "API key environment variable is available"
else
  echo "API key environment variable is missing"
fi

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

如果最后仍然失败：

  1. 在 API 控制台重新创建一个 key，并撤销旧 key。
  2. 确认新 key 与已经充值的 API 项目属于同一账户和项目。
  3. 在同一个终端中重新执行 export 和登录命令。
  4. 排查代理、防火墙和证书问题。
  5. 根据 codex --version 和 codex login --help 的输出，核对当前版本支持的认证方式。

不要在截图、日志、工单或命令历史中暴露完整的 API key。如果 key 曾被公开输出或复制到不可信的位置，应立即撤销并重新创建。

备注：内容仅供参考。