程序员必踩的一个坑：Codex 报错 Missing environment variable `OPENAI_API_KEY`，完整解决指南（附架构图）

最近在使用 OpenAI Codex CLI 调试 AI API 平台时，我遇到一个看似简单却非常容易踩坑的问题。

启动 Codex 后输入任意内容：

在吗？

终端直接报错：

Missing environment variable: OPENAI_API_KEY

刚开始很多人会怀疑：

API Key 配错了？
config.toml 写错了？
Codex 版本问题？

实际上 80% 的原因只有一个：环境变量没有正确生效。

这篇文章我会完整讲清楚：

1️⃣ 为什么会出现这个错误 2️⃣ Codex 的认证机制 3️⃣ 如何正确配置 API Key 4️⃣ 如何让环境变量全局生效 5️⃣ AI API Gateway 的推荐架构

如果你正在使用 Codex / Cursor / Cline / 自建 AI API 平台，这篇文章应该能帮你省掉不少排查时间。

一、问题现象

启动 Codex：

codex

终端界面类似：

>_ OpenAI Codex (v0.120.0)

model: gpt-5.x
directory: ~/workspace/project

输入任意问题：

hello

立即出现报错：

Missing environment variable: OPENAI_API_KEY

说明 Codex 没有读取到 API Key。

Codex CLI 需要通过 API Key 才能调用模型，如果系统中没有这个变量，就会直接报错。 ([Medium][1])

二、Codex 的认证机制

Codex 的认证方式主要有两种：

方式一：登录账号

codex login

优点：

不需要手动配置 Key

缺点：

不方便接入第三方 API
不方便做 API 网关

方式二：API Key

这是大多数开发者使用的方式。

Codex 会读取系统环境变量：

OPENAI_API_KEY

如果这个变量不存在，就会报错。

三、很多人会犯的两个错误

错误一：把 Token 写进 config.toml

很多人会这样写：

env_key = "sk-xxxx"

其实 env_key 指的是 环境变量名，而不是 Key。

正确写法：

env_key = "OPENAI_API_KEY"

然后在系统环境变量中设置 Key。

否则 Codex 会去找：

$sk-xxxx

当然找不到。

错误二：只在当前终端设置

很多人执行：

export OPENAI_API_KEY=xxxx

这种方式 只对当前终端有效。

关闭终端后变量就消失。

四、正确配置方式（推荐）

如果你使用 Mac + zsh，建议写入 ~/.zshrc。

1 打开配置文件

nano ~/.zshrc

加入：

export OPENAI_API_KEY="你的API_KEY"

如果使用 AI API 网关：

export OPENAI_BASE_URL="http://localhost:8080/v1"

2 重新加载

source ~/.zshrc

3 验证是否成功

echo $OPENAI_API_KEY

如果输出 Key（部分隐藏），说明成功。

五、Codex 配置文件示例

Codex 配置文件在：

~/.codex/config.toml

示例：

model = "deepseek-chat"
model_provider = "local"

[model_providers.local]
name = "local-api"
base_url = "http://localhost:8080/v1"
env_key = "OPENAI_API_KEY"
wire_api = "responses"

Codex 会自动读取环境变量。

另外 Codex 也支持 .env 文件，只要放在项目根目录即可自动加载。 ([OpenAI Developer Community][2])

例如：

OPENAI_API_KEY=xxxxx

六、快速排查环境变量

如果再次报错，可以执行：

env | grep OPENAI

正常情况应该看到：

OPENAI_API_KEY=xxxxx
OPENAI_BASE_URL=http://localhost:8080/v1

如果没有输出，就说明变量没有生效。

七、AI API 平台的典型架构

现在很多开发者会搭建 AI API Gateway。

架构一般如下：

                ┌───────────────┐
                │   Codex CLI   │
                │   Cursor IDE  │
                │   Cline / Roo │
                └───────┬───────┘
                        │
                        ▼
              ┌───────────────────┐
              │   AI API Gateway  │
              │  (统一API平台)    │
              └─────────┬─────────┘
                        │
        ┌───────────────┼───────────────┐
        ▼               ▼               ▼
   DeepSeek API     Qwen API        GPT API

这种架构的好处：

统一 API Key 管理
多模型统一调用
Token 统计
成本控制
支持多个客户端

目前很多 AI SaaS 平台（例如 OpenRouter、n1n）本质上就是这种模式。

八、Codex 配置结构图

Codex 的配置结构通常如下：

~/.codex/
│
├── config.toml
├── auth.json
├── history.jsonl

其中：

config.toml

用于配置：

模型
API 地址
Provider
API Key 环境变量

Codex 默认会在用户目录 ~/.codex 中读取这些配置。 ([OpenAI开发者][3])

九、总结

如果 Codex 报错：

Missing environment variable: OPENAI_API_KEY

基本只需要检查三件事：

1 是否设置环境变量

echo $OPENAI_API_KEY

2 是否写入 shell 配置

~/.zshrc

3 是否 reload

source ~/.zshrc

只要这三步完成，Codex 基本都能正常运行。

十、写在最后

如果你正在开发：

AI API Gateway
AI 开发平台
多模型聚合系统

建议统一使用 环境变量管理 API Key。

这样：

Codex
Cursor
Cline
RooCode

都可以直接接入你的平台。

开发效率会高很多。

程序员必踩的一个坑：Codex 报错 Missing environment variable `OPENAI_API_KEY`，完整解决指南（附架构图）