【Bug已解决】OPENAI_API_KEY not set / Authentication failed — CodeX CLI API Key 认证失败解决方案1. 问题描述运行 CodeX CLI 时报 API Key 未设置或认证失败# API Key 未设置 $ codex Error: OPENAI_API_KEY not set Please set your OpenAI API key as an environment variable: export OPENAI_API_KEYsk-... # 或认证失败 $ codex Error: 401 Unauthorized {error:{type:authentication_error,message:Incorrect API key provided}} # 或 Key 已过期 $ codex Error: 401 Unauthorized {error:{message:API key revoked}} # 或 Key 余额不足 $ codex Error: 402 Payment Required {error:{message:You exceeded your current quota}}这个问题在以下场景中特别常见未设置 OPENAI_API_KEY 环境变量API Key 拼写错误或过期使用了错误的 API Key如非 OpenAI 的 Key账户余额不足Key 被吊销或限制配置文件中的 Key 与环境变量冲突2. 原因分析核心原理拆解CodeX CLI 启动 → 读取 OPENAI_API_KEY ↓ Key 未设置/错误/过期/余额不足 ↓ 认证失败 (401/402)原因分类表原因分类具体表现占比Key 未设置环境变量缺失约 40%Key 错误拼写错误或非 OpenAI Key约 25%Key 过期/吊销Key 被撤销约 15%余额不足402 Payment Required约 10%配置冲突多个配置来源约 5%Shell 缓存旧会话的环境变量约 5%3. 解决方案方案一设置环境变量最推荐# 步骤 1设置 API Key export OPENAI_API_KEYsk-proj-xxxxxxxxxxxxxxxxxxxx # 步骤 2永久设置 echo export OPENAI_API_KEYsk-proj-xxxxxxxxxxxxxxxxxxxx ~/.zshrc source ~/.zshrc # 步骤 3验证 echo $OPENAI_API_KEY | head -c 10 # 应显示 sk-proj-x # 步骤 4启动 CodeX codex方案二获取正确的 API Key# 步骤 1登录 OpenAI Platform # https://platform.openai.com/api-keys # 步骤 2创建新 Key # 点击 Create new secret key # 复制 Key只显示一次 # 步骤 3确保 Key 格式正确 # 新版 Key: sk-proj-xxxxxxxxxxxx # 旧版 Key: sk-xxxxxxxxxxxxxxxx # 步骤 4设置环境变量 export OPENAI_API_KEYsk-proj-xxxxxxxxxxxx方案三检查账户余额# 步骤 1登录 OpenAI Platform # https://platform.openai.com/account/billing # 步骤 2查看余额 # 如果余额为 $0充值 # 步骤 3查看用量限制 # Settings → Limits # 确认月度限额是否已用完 # 步骤 4充值后重试 codex方案四使用 .env 文件管理# 步骤 1创建 .env 文件 cat ~/.codex/.env EOF OPENAI_API_KEYsk-proj-xxxxxxxxxxxx EOF # 步骤 2在 .zshrc 中加载 echo source ~/.codex/.env ~/.zshrc source ~/.zshrc # 步骤 3保护 .env 文件 chmod 600 ~/.codex/.env # 步骤 4验证 echo $OPENAI_API_KEY | head -c 10 codex方案五检查 Shell 缓存# 步骤 1当前 Shell 可能缓存了旧 Key unset OPENAI_API_KEY # 步骤 2重新设置 export OPENAI_API_KEYsk-proj-NEWKEY # 步骤 3或开新终端 # 关闭当前终端开新终端 codex # 步骤 4验证 env | grep OPENAI_API_KEY方案六使用配置文件# 步骤 1如果 CodeX 支持配置文件 cat ~/.codex/config.json EOF { apiKey: sk-proj-xxxxxxxxxxxx, model: gpt-4o } EOF # 步骤 2或通过命令设置 codex config set apiKey sk-proj-xxxxxxxxxxxx # 步骤 3验证 codex config get apiKey4. 各方案对比总结方案适用场景推荐指数难度方案一环境变量通用方案⭐⭐⭐⭐⭐低方案二获取 KeyKey 错误⭐⭐⭐⭐⭐低方案三检查余额余额不足⭐⭐⭐⭐⭐低方案四.env 文件长期管理⭐⭐⭐⭐⭐低方案五清缓存Shell 缓存⭐⭐⭐⭐低方案六配置文件持久配置⭐⭐⭐⭐低5. 常见问题 FAQ5.1 如何获取 OpenAI API Key在 https://platform.openai.com/api-keys 创建。需要 OpenAI 账户。5.2 API Key 的格式是什么新版:sk-proj-xxxxxxxxxxxxxxxxxxxxxxxx旧版:sk-xxxxxxxxxxxxxxxxxxxxxxxx5.3 401 和 402 的区别401 Unauthorized: Key 错误或过期402 Payment Required: 余额不足5.4 API Key 存储在哪些位置环境变量OPENAI_API_KEY~/.codex/config.json.env文件CI/CD 的 secret5.5 Key 被吊销怎么办在 OpenAI Platform 创建新 Key更新所有使用旧 Key 的位置。5.6 如何检查余额在 https://platform.openai.com/account/billing 查看。或通过 APIcurl https://api.openai.com/v1/organization/costs \ -H Authorization: Bearer $OPENAI_API_KEY5.7 CI/CD 中如何设置 Keyenv: OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}5.8 Docker 中传入 Keydocker run -e OPENAI_API_KEY$OPENAI_API_KEY codex-env5.9 多人共享 Key 安全吗不安全。每人应使用独立的 Key便于追踪用量和管理权限。5.10 排查清单速查表□ 1. export OPENAI_API_KEYsk-proj-xxx 设置 Key □ 2. echo $OPENAI_API_KEY 验证已设置 □ 3. 在 platform.openai.com/api-keys 确认 Key 有效 □ 4. 检查 platform.openai.com/account/billing 余额 □ 5. 使用 .env 文件持久管理 □ 6. unset 重新设置 清除 Shell 缓存 □ 7. 开新终端避免旧缓存 □ 8. CI/CD: secrets.OPENAI_API_KEY □ 9. Docker: -e OPENAI_API_KEY □ 10. chmod 600 保护 .env 文件6. 总结根本原因认证失败最常见原因是 API Key 未设置40%环境变量缺失和 Key 错误25%拼写错误或非 OpenAI Key最佳实践在~/.zshrc中设置export OPENAI_API_KEYsk-proj-xxx或使用.env文件管理Key 获取在 https://platform.openai.com/api-keys 创建新 Key确保格式正确sk-proj-xxx余额检查402 错误时检查 https://platform.openai.com/account/billing充值后重试最佳实践建议使用~/.codex/.env文件管理 API Keychmod 600保护文件权限轮换 Key 时只需编辑一个文件故障排查流程图flowchart TD A[API Key 认证失败] -- B{Key 已设置?} B --|否| C[export OPENAI_API_KEYsk-xxx] B --|是| D{Key 格式正确?} C -- E[source ~/.zshrc] D --|否| F[在 platform.openai.com 获取新 Key] D --|是| G{认证成功?} E -- G F -- C G --|是| H[✅ 认证成功] G --|否, 401| I[Key 过期或吊销] G --|否, 402| J[余额不足] I -- F J -- K[充值 OpenAI 账户] K -- L[等待几分钟生效] L -- G H -- M[配置 .env 持久管理] M -- N[chmod 600 保护文件] N -- O[✅ 长期方案]