Codex对接中转API配置指南

猛勇无比的一匹狼

2427人浏览 · 2026-04-30 11:34:37

猛勇无比的一匹狼 · 2026-04-30 11:34:37 发布

Codex CLI 通过配置 OPENAI_BASE_URL 和 OPENAI_API_KEY 环境变量或使用配置文件来对接中转 API，其核心在于将请求重定向到兼容 OpenAI API 格式的第三方服务端点。

一、核心配置方法对比

Codex CLI 支持多种配置方式，可根据使用场景和操作系统选择。

配置方式	适用场景	优点	缺点
环境变量	临时测试、脚本调用、系统级全局配置	优先级最高，配置简单，可动态修改	重启终端或系统后可能失效（需持久化配置）
配置文件 (`config.toml` 或 `config.json`)	长期使用、多环境切换、项目级配置	配置持久化，便于版本管理，可分层配置	需要手动创建和编辑配置文件
CLI 参数	单次命令执行时的临时覆盖	最灵活，可覆盖其他配置	每次命令都需输入，较为繁琐

二、详细配置步骤与示例

1. 通过环境变量配置（推荐用于快速启动）

这是最直接的方法，通过在终端会话中设置环境变量来覆盖默认的 OpenAI 端点。

设置中转 API 基础 URL：将 OPENAI_BASE_URL 指向你的中转服务地址。
设置 API 密钥：将 OPENAI_API_KEY 设置为从中转服务商处获取的密钥。

Windows (PowerShell) 示例：

# 设置环境变量（仅当前会话有效）
$env:OPENAI_API_KEY="sk-your-transit-api-key-here"
$env:OPENAI_BASE_URL="https://your-transit-api.com/v1"

# 验证配置并测试 Codex
codex --version
# 尝试一个简单的命令，如列出模型（具体命令取决于你的中转服务支持）
codex models list

注意：在 PowerShell 中，以上设置仅对当前窗口有效。若要永久生效，需通过系统属性或 [Environment]::SetEnvironmentVariable 设置用户/系统环境变量。

Linux/macOS (Bash/Zsh) 示例：

# 设置环境变量（仅当前会话有效）
export OPENAI_API_KEY="sk-your-transit-api-key-here"
export OPENAI_BASE_URL="https://your-transit-api.com/v1"

# 验证配置
echo $OPENAI_API_KEY
echo $OPENAI_BASE_URL

# 测试 Codex 连接
codex completions create --model gpt-3.5-turbo-instruct --prompt "Hello, world"

为了使环境变量在每次打开终端时自动生效，可以将 export 命令添加到 ~/.bashrc、~/.zshrc 或 ~/.profile 文件中。

2. 通过配置文件配置（推荐用于持久化部署）

Codex CLI 会读取用户主目录下的配置文件。配置文件的格式和位置因版本或安装方式而异，常见的有 config.toml 和 config.json。

TOML 格式配置 (常见于 Snap 安装)
配置文件通常位于 ~/.codex/config.toml。

# ~/.codex/config.toml
[default]
# 指定模型提供商，对于中转API通常设为 "openai"
model_provider = "openai"
# 你的中转API密钥
api_key = "sk-your-transit-api-key-here"
# 中转API的基础URL
base_url = "https://your-transit-api.com/v1"
# 可选：指定默认使用的模型
# default_model = "gpt-3.5-turbo"

创建并编辑此文件后，Codex CLI 将自动读取其中的配置。

JSON 格式配置 (常见于 npm 安装)
配置文件可能位于 ~/.codex/config.json 或项目目录下。
```
{
  "apiKey": "sk-your-transit-api-key-here",
  "baseURL": "https://your-transit-api.com/v1",
  "defaultModel": "gpt-3.5-turbo-instruct",
  "organization": null // 通常中转服务不需要此项
}
```
有些教程还提到了 auth.json 文件用于专门存储认证信息，但核心配置通常集中在 config.json 中。

3. 使用 CLI 参数临时指定

在执行任何 codex 命令时，可以直接通过参数指定 API 密钥和基础 URL。

codex --api-key sk-your-transit-api-key-here --base-url https://your-transit-api.com/v1 completions create --model gpt-3.5-turbo-instruct --prompt "Translate hello to French"

三、与具体中转服务（如 88API）对接的完整流程示例

以使用 “88API” 这类国内中转服务为例，展示从零开始的配置流程。

环境准备：确保系统已安装 Node.js (>=18 版本) 和 npm。
安装 Codex CLI：
```
npm install -g @openai/codex
```
获取中转 API 配置信息：
- 从中转服务商（如 88API）后台获取你的 API Key。注意，部分服务商（如 88API）有专门的 codex 分组，需从中获取专属密钥以获得更佳兼容性。
- 获取服务商提供的 Base URL，例如 https://api.88api.com/v1。

创建并编写配置文件：
在用户主目录下创建配置文件。

mkdir -p ~/.codex
vim ~/.codex/config.json

将以下内容写入 config.json，替换为你自己的 API Key 和 Base URL。

{
  "apiKey": "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "baseURL": "https://api.88api.com/v1",
  "defaultModel": "gpt-3.5-turbo-instruct"
}

验证配置：

# 检查版本，确认CLI安装成功
codex --version
# 尝试调用一个简单的补全任务
codex completions create --model gpt-3.5-turbo-instruct --prompt "写一个Python的hello world程序" --max-tokens 100

如果配置正确，你将收到来自中转 API 的模型响应。

四、常见问题与排查

401 或 403 错误：API 密钥无效或未正确传递。请检查密钥是否填写正确，并确认中转服务是否支持 Codex 使用的 API 格式。
404 错误：Base URL 不正确，或中转服务的端点路径与 OpenAI API 不完全兼容。确保 Base URL 包含 /v1 后缀，并咨询服务商其兼容性。
命令未找到 (codex: command not found)：Codex CLI 未正确安装或未添加到系统 PATH。对于 npm 全局安装，可尝试 npx @openai/codex 来运行。
配置优先级：Codex CLI 的配置加载优先级通常为：CLI 参数 > 环境变量 > 用户配置文件 > 全局配置文件。如果配置未生效，检查是否有更高优先级的配置覆盖了你的设置。
使用代理：如果网络访问需要代理，除了配置中转 API，可能还需要在系统或终端中设置 HTTP/HTTPS 代理环境变量（如 HTTP_PROXY, HTTPS_PROXY）。