Codex CLI API Key 配置指南 2026

Codex CLI 支持两种认证方式

在开始配置之前，先了解两种方式的区别，选最适合自己的：

方式一：ChatGPT 账号登录

如果你已经订阅了 ChatGPT Plus、Pro、Business、Edu 或 Enterprise，可以直接用账号登录，无需单独管理 API Key。

登录步骤

# 启动 OAuth 登录流程
$ codex login

运行命令后，Codex CLI 会：

1. 在终端输出一个授权 URL 并尝试自动打开浏览器
2. 浏览器跳转到 ChatGPT 的 OAuth 授权页面
3. 用你的 ChatGPT 账号登录并点击「Authorize」
4. 浏览器跳回本地回调地址，终端显示登录成功

登录成功后，认证 token 会保存到 ~/.codex/auth.json，之后运行 codex 无需再次登录。

确认已登录

# 启动 codex 后查看左下角状态栏
$ codex
# 左下角显示 ● connected 表示认证成功并连上了 OpenAI

# 或者查看认证文件（不会暴露完整 token）
$ ls ~/.codex/
$ cat ~/.codex/auth.json

方式二：OpenAI API Key

API Key 方式更灵活，不需要 ChatGPT 订阅，适合需要精细控制用量和成本的开发者，也支持按项目使用不同的 Key。

在哪里获取 API Key

OpenAI API Key 在 platform.openai.com/api-keys 管理：

1. 登录 platform.openai.com（需要代理）
2. 点击左侧菜单「API keys」
3. 点击「Create new secret key」
4. 给 Key 起个名字（如「codex-cli-dev」），便于后续管理
5. 立即复制，Key 只显示一次，关闭弹窗后无法再查看完整内容

设置 API Key

有两种方式把 API Key 配置给 Codex CLI：

方法一：通过 codex login 命令（推荐）

$ codex login --with-api-key
# 命令行提示输入 API Key，输入后回车
# Key 会加密保存到 ~/.codex/auth.json

方法二：通过环境变量

# 临时设置（只对当前终端会话有效）
$ export OPENAI_API_KEY=sk-proj-xxxxxxxxxxxxxxxx
$ codex "帮我测试一下连接"

永久生效：写入 Shell 配置文件（~/.zshrc 或 ~/.bashrc）：

# 用编辑器打开（推荐，避免意外覆盖）
$ nano ~/.zshrc

# 在文件末尾添加这一行（替换为你的实际 Key）：
export OPENAI_API_KEY=sk-proj-xxxxxxxxxxxxxxxx

# 保存后让配置生效
$ source ~/.zshrc

多账号 / 多 Key 管理

如果你需要在不同项目中使用不同的 OpenAI 账号或 API Key（比如个人账号和工作账号分开），有以下几种方案：

认证信息存储位置

Codex CLI 将当前认证信息存储在 ~/.codex/auth.json。你可以查看（API Key 会被部分遮蔽）：

$ cat ~/.codex/auth.json
# 输出类似：{"type":"api-key","key":"sk-proj-xxx...xxx"}

切换账号

重新运行对应的 codex login 命令即可切换，新认证会覆盖 auth.json 中的旧认证：

# 切换到 ChatGPT OAuth 登录
$ codex login

# 切换到 API Key
$ codex login --with-api-key

# 登出（删除认证信息）
$ codex logout
# 或手动删除
$ rm ~/.codex/auth.json

使用 direnv 按项目切换 API Key

如果你在不同项目中需要使用不同的 API Key，direnv 是最优雅的方案——进入项目目录时自动切换环境变量，离开时自动恢复：

# 安装 direnv（macOS）
$ brew install direnv

# 在 Shell 配置文件末尾添加 hook（以 zsh 为例）
$ echo 'eval "$(direnv hook zsh)"' >> ~/.zshrc
$ source ~/.zshrc

# 在项目目录创建 .envrc 文件（注意：不要提交到 Git！）
$ cd /path/to/your/project
$ echo 'export OPENAI_API_KEY=sk-proj-工作账号key' > .envrc
$ direnv allow .

# 确保 .envrc 在 .gitignore 里
$ echo '.envrc' >> .gitignore

此后进入该目录时，OPENAI_API_KEY 会自动切换为项目专用的 Key，离开目录后恢复到全局设置。

API Key 安全注意事项

API Key 一旦泄露，他人可以用你的账号余额发起任意 API 请求。以下是必须养成的安全习惯：

不要把 Key 写进代码仓库

• 永远不要 git add .env 或含有 API Key 的任何文件
• 项目根目录加一个 .gitignore 规则：.env、.env.local、.envrc
• 推荐用 gitleaks 等工具扫描历史提交，确认没有泄露过 Key

# API Keys 和环境变量文件
.env
.env.*
.envrc
*.key
*_secret*

设置 API 使用额度限制

在 platform.openai.com/settings/organization/limits 可以设置每月最大用量上限，即使 Key 泄露也能限制损失：

• Monthly budget（每月预算上限）：达到上限后 API 调用直接返回 429 错误
• Usage alert（用量告警）：消费超过阈值时发邮件提醒

对于个人开发者，建议设置月用量上限为 5～20 美元，防止意外超支。

Key 泄露后如何立即撤销

如果发现 API Key 可能已经泄露（比如不小心推送到了公开 GitHub 仓库），立即采取以下步骤：

1. 登录 platform.openai.com/api-keys
2. 找到对应的 Key，点击右侧的「Revoke」按钮
3. 确认撤销——被撤销的 Key 立即失效，无法恢复
4. 创建一个新的 Key 并更新本地配置
5. 在 GitHub 仓库搜索历史提交中的 Key，如有必要重写 Git 历史（git filter-branch 或 BFG Repo Cleaner）

# 撤销旧 Key 后，用新 Key 重新登录
$ codex login --with-api-key
# 输入新的 API Key

常见认证报错

401 Unauthorized

含义：API Key 无效、已过期或已被撤销。

解决：

• 检查 OPENAI_API_KEY 环境变量是否正确设置（没有多余空格或换行）
• 在 platform.openai.com/api-keys 确认 Key 状态显示为 Active
• 如果用的是 codex login --with-api-key 方式，重新运行该命令重新录入 Key

# 检查环境变量是否设置（不会显示完整内容）
$ echo ${OPENAI_API_KEY:0:10}...
# 应该输出 sk-proj-xx...

# 用 curl 直接测试 Key 是否有效
$ curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -s | head -c 200

403 Forbidden：地区限制

含义：请求来自 OpenAI 不支持的地区（中国大陆 IP 会触发此错误）。

解决：必须通过代理让 API 请求走出中国大陆。配置 HTTPS_PROXY 环境变量指向本地代理：

$ export HTTPS_PROXY=http://127.0.0.1:7890
$ codex "测试连接"

详细代理配置参见 国内使用与代理配置。

Authentication required

含义：Codex CLI 找不到有效的认证信息，未完成登录。

解决：运行 codex login（ChatGPT 账号）或 codex login --with-api-key（API Key），完成认证流程后重试。

常见问题