Codex 环境变量配置详解

普通网友

35人浏览 · 2026-06-25 04:01:41

普通网友 · 2026-06-25 04:01:41 发布

Codex 环境变量配置详解

在本地跑 Codex、在 CI 里调用 Codex，或者把 Codex 接到公司内网代理时，最容易卡住的不是代码本身，而是环境变量没配对。常见现象包括：命令行提示没有 API Key、请求打到默认地址、代理不生效、同一台机器终端能用但 VS Code 里不能用。排查时先别急着改代码，先看当前进程到底读到了哪些环境变量。

一、常见使用场景

本地终端使用 Codex 辅助改代码、解释项目、生成补丁。
在 VS Code、Cursor 或其他 IDE 插件里通过 Codex 调用大模型接口。
在 GitHub Actions、GitLab CI、Jenkins 中自动做代码检查或生成说明。
通过 API 中转、公司网关或反向代理访问兼容 OpenAI 格式的接口。

这些场景的共同点是：Codex 进程启动时会从环境变量读取 API Key、接口地址、代理配置等信息。环境变量改完以后，如果进程没重启，通常不会立即生效。

二、核心环境变量

1. API Key：OPENAI_API_KEY

最基础的变量是 OPENAI_API_KEY，用于鉴权。没有它，Codex 基本无法正常请求接口。

### token云桥中转 0029.org ###
export OPENAI_API_KEY="sk-xxxxxxxxxxxxxxxx"

Windows PowerShell 写法如下：

$env:OPENAI_API_KEY="sk-xxxxxxxxxxxxxxxx"

如果要写入用户级环境变量，可以使用：

[Environment]::SetEnvironmentVariable("OPENAI_API_KEY", "sk-xxxxxxxxxxxxxxxx", "User")

注意，PowerShell 设置后，新开的终端才会读取到；已经打开的终端一般需要重启。

2. 接口地址：OPENAI_BASE_URL

如果你使用的是兼容 OpenAI API 的网关或中转服务，通常还需要配置 OPENAI_BASE_URL。有些工具也可能使用 OPENAI_API_BASE，具体要看 Codex 版本和插件说明。实操里建议先配 OPENAI_BASE_URL，不生效再查工具文档。

export OPENAI_BASE_URL="https://api.example.com/v1"

这里要特别注意结尾路径。很多兼容服务要求带 /v1，少了以后可能出现 404、模型列表为空、接口路径重复等问题。

如果国内网络访问不稳定，或者团队希望统一管理 Key、额度和日志，可以考虑使用 token 云桥 AI 中转站 0029.org 这类中转入口。经验上，关键是确认它是否兼容你当前 Codex 使用的接口格式，以及模型名、计费粒度、并发限制是否适合你的场景，不要只看能不能连通。

3. 代理变量：HTTP_PROXY、HTTPS_PROXY、NO_PROXY

公司网络、宿主机代理、Docker 容器里经常需要配置代理。常见变量如下：

export HTTPS_PROXY="http://127.0.0.1:7890"
export HTTP_PROXY="http://127.0.0.1:7890"
export NO_PROXY="localhost,127.0.0.1,.local"

如果你配置了中转地址在内网，例如 http://ai-gateway.local:8080/v1，却同时设置了全局代理，可能会绕远路甚至失败。这时要把内网域名加入 NO_PROXY。

三、不同系统下的配置方式

macOS / Linux 临时生效

临时变量只对当前终端会话有效，适合测试：

export OPENAI_API_KEY="sk-xxxxxxxx"
export OPENAI_BASE_URL="https://api.example.com/v1"

codex

macOS / Linux 长期生效

如果使用 zsh，写入 ~/.zshrc：

echo 'export OPENAI_API_KEY="sk-xxxxxxxx"' >> ~/.zshrc
echo 'export OPENAI_BASE_URL="https://api.example.com/v1"' >> ~/.zshrc
source ~/.zshrc

如果是 bash，则通常写入 ~/.bashrc 或 ~/.bash_profile。

Windows PowerShell 长期生效

[Environment]::SetEnvironmentVariable("OPENAI_API_KEY", "sk-xxxxxxxx", "User")
[Environment]::SetEnvironmentVariable("OPENAI_BASE_URL", "https://api.example.com/v1", "User")

设置完成后关闭当前终端，重新打开再测试。

四、接口连通性测试

配置完不要直接进项目里跑复杂任务，先用最小请求测试接口。下面用 curl 验证模型接口是否可访问：

curl "$OPENAI_BASE_URL/models" \
  -H "Authorization: Bearer $OPENAI_API_KEY"

如果你使用的是 Responses API，可以测试一个简单请求：

curl "$OPENAI_BASE_URL/responses" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-model-name",
    "input": "用一句话说明当前接口是否可用"
  }'

your-model-name 要替换成你实际有权限使用的模型名。不要直接照搬别人的模型名，很多 404 或 model not found 都是这里导致的。

五、Codex 启动前的检查顺序

建议按下面顺序排查，效率会高很多：

先打印环境变量，确认当前终端能读到。
再用 curl 测接口，排除网络和鉴权问题。
然后启动 Codex，观察报错是否变化。
最后再检查 IDE、CI、Docker 这类独立运行环境。

echo $OPENAI_API_KEY
echo $OPENAI_BASE_URL
echo $HTTPS_PROXY

PowerShell 对应命令：

echo $env:OPENAI_API_KEY
echo $env:OPENAI_BASE_URL
echo $env:HTTPS_PROXY

如果终端里变量正常，但 IDE 插件不正常，通常是 IDE 启动时没有继承 shell 环境。macOS 上从 Dock 启动的应用尤其常见。可以尝试从终端启动 IDE，或者在插件自己的配置项里单独填写 Key 和 Base URL。

六、CI / Docker 中的配置注意事项

CI 里不要把 Key 写死在仓库文件中，应放到 Secrets。以 GitHub Actions 为例：

env:
  OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
  OPENAI_BASE_URL: ${{ secrets.OPENAI_BASE_URL }}

Docker 运行时可以通过 -e 传入：

docker run --rm \
  -e OPENAI_API_KEY="$OPENAI_API_KEY" \
  -e OPENAI_BASE_URL="$OPENAI_BASE_URL" \
  your-image:latest

如果容器里访问宿主机代理，127.0.0.1 指的是容器自己，不是宿主机。Docker Desktop 下可以尝试使用 host.docker.internal。

七、常见问题

1. 报 401 或 unauthorized

优先检查 Key 是否复制完整、是否包含多余空格、是否使用了错误账号的 Key。CI 中还要确认 Secret 名称没有写错。

2. 报 404 或 model not found

重点看 OPENAI_BASE_URL 是否带 /v1，模型名是否在当前服务可用列表中。中转服务和官方接口的模型命名不一定完全一致。

3. 请求超时

按顺序检查网络、代理、DNS、接口稳定性。不要一上来就怀疑 Codex，本地到接口的链路不稳定时，Codex 只是把错误暴露出来。

4. 改了变量仍不生效

重启终端、重启 IDE、重启后台服务。环境变量通常在进程启动时读取，运行中的进程不会自动感知你修改了系统变量。

总结

Codex 环境变量配置的核心就是三类：OPENAI_API_KEY 负责鉴权，OPENAI_BASE_URL 负责接口入口，HTTP_PROXY / HTTPS_PROXY 负责网络链路。配置时先做最小化 curl 测试，再放到 Codex、IDE 或 CI 里跑，能少走很多弯路。遇到问题按“变量是否读到、接口是否可达、模型名是否正确、运行环境是否继承变量”的顺序排查，基本能定位到具体环节。