OpenAI Codex CLI - 自定义 API 配置教程

[!info] 文章信息

作者: 林恒（博客园）

来源: 博客园 - vue知识分享

发布时间: 2025-12-26

许可证: BY-NC-SA

本文介绍如何为 OpenAI Codex CLI 配置自定义 API，包括安装步骤、配置文件编写、环境变量设置和高级配置选项。

概述

Codex 是 OpenAI 推出的一系列人工智能编码工具，通过将任务委托给强大的云端和本地编码代理，帮助开发人员提升工作效率。

官网: https://openai.com/codex/

支持场景:

原生终端
VS Code 插件
Cursor 插件

系统要求

Node.js 22+（推荐）
macOS / Linux / Windows
终端环境

步骤一：安装 Codex CLI

方式一：npm 安装（通用）

bash

# 使用 npm 全局安装
npm i -g @openai/codex

# 或使用原生包名（如需要）
npm i -g @openai/codex@native

# 验证安装
codex --version

方式二：Homebrew（macOS 推荐）

bash

# 更新 Homebrew
brew update

# 安装 Codex
brew install codex

# 验证安装
codex --version

[!tip] 故障提示如遇 codex 无法执行或 Node 版本过旧，请升级 Node（推荐 Node 22+），或改用 Homebrew 安装。

步骤二：配置 Codex

背景

如果你是 OpenAI Plus 会员，可以直接在 Codex 中登录 Plus 账号使用。但如果你想使用第三方中转平台的 API，需要进行以下配置。

1. 获取 API Key

在第三方中转平台（如 api.v3.cm）注册并充值，然后在「令牌管理」页面复制 API Key（格式为 sk-xxxxxx）。

2. 创建配置文件

Codex 启动时会在 ~/.codex/ 读取 config.toml 文件。

bash

# 创建配置目录
mkdir -p ~/.codex

# 编辑配置文件
nano ~/.codex/config.toml
# 或使用 vim
vim ~/.codex/config.toml

3. 配置内容

toml

# 模型供应商设置
model_provider = "vapi"  # 设置 API 供应商
model = "gpt-5"          # 填写支持 codex 的模型
# model_reasoning_effort = "low"  # 思考级别: low/medium/high/minimal，不需要可注释

# 供应商详细配置
[model_providers.vapi]
name = "VAPI"
base_url = "https://api.v3.cm/v1"
env_key = "V_API_KEY"              # 保留此值，不需要替换为实际 key
wire_api = "chat"                  # 使用 /v1/chat/completions 协议
query_params = {}
request_max_retries = 4            # 失败最大重试次数
stream_max_retries = 10            # 流中断后最大重试次数

# Profile 配置（可选）
[profiles.vapi]
model_provider = "vapi"
model = "gpt-5"
approval_policy = "on-request"     # 需要时再询问是否执行
sandbox_mode = "workspace-write"   # 允许在当前工程写文件，依旧禁网

步骤三：设置环境变量

Windows 用户

cmd

# 永久设置（推荐）
setx V_API_KEY "sk-xxxxxx"

# 临时设置，切换窗口后失效
set V_API_KEY=sk-xxxxxx

PowerShell:

powershell

$env:V_API_KEY="sk-xxxxxx"

Mac/Linux 用户

方法一：永久设置（推荐）

bash

# 如果使用 bash
nano ~/.bash_profile
# 或
nano ~/.bashrc

# 如果使用 zsh（Mac 默认）
nano ~/.zshrc

在文件最后添加：

bash

export V_API_KEY="sk-xxxxxx"

保存并生效：

bash

# bash
source ~/.bash_profile

# zsh
source ~/.zshrc

方法二：临时设置

bash

export V_API_KEY="sk-xxxxxx"

验证环境变量

bash

# Windows (CMD)
echo %V_API_KEY%

# Windows (PowerShell)
echo $env:V_API_KEY

# Mac/Linux
echo $V_API_KEY

如果显示 sk-xxxxxx 则说明设置成功！

启动命令

CLI 原生命令

bash

# 直接提问
codex "你好"

# 选择提供商并提问（如果有多个提供商）
codex --profile vapi "你好"

VS Code 中使用

[!warning] 重要如果在 VS Code 中使用 Codex 插件，配置好后需要完全退出 VS Code 并重新启动才能生效。

高级配置

模型上下文协议（MCP）

通过在 ~/.codex/config.toml 中定义 mcp_servers 部分，可以将 Codex CLI 配置为使用 MCP 服务器。

toml

# 注意：顶层键是 `mcp_servers` 而不是 `mcpServers`
[mcp_servers.server-name]
command = "npx"
args = ["-y", "mcp-server"]
env = { "API_KEY" = "value" }

CI 模式（非交互模式）

在管道中以无头方式运行 Codex。示例 GitHub Action 步骤：

yaml

- name: Update changelog via Codex
  run: |
    npm install -g @openai/codex
    export OPENAI_API_KEY="${{ secrets.OPENAI_KEY }}"
    codex exec --full-auto "update CHANGELOG for next release"

配置参数说明

参数	说明	可选值
`model_provider`	API 供应商标识	自定义名称
`model`	使用的模型	`gpt-4`, `gpt-5` 等
`model_reasoning_effort`	思考级别	`low`, `medium`, `high`, `minimal`
`base_url`	API 基础 URL	第三方 API 地址
`env_key`	环境变量名	保持配置值，不替换
`wire_api`	API 协议类型	`chat`
`approval_policy`	审批策略	`on-request`, `auto`
`sandbox_mode`	沙箱模式	`workspace-write`, `none`

常见问题

问题 1: Node 版本过旧

症状: codex 无法执行

解决方案:

bash

# 升级 Node（推荐使用 nvm）
nvm install 22
nvm use 22

# 或使用 Homebrew
brew install node@22

问题 2: 配置不生效

症状: 修改配置后没有效果

解决方案:

检查配置文件路径：~/.codex/config.toml
完全退出并重启编辑器（VS Code/Cursor）
确认环境变量已正确设置

问题 3: API 调用失败

症状: 提示认证失败或连接错误

解决方案:

验证 API Key 是否正确
检查 base_url 是否可访问
确认环境变量 V_API_KEY 已设置

字节笔记本

OpenAI Codex CLI - 自定义 API 配置教程

概述

系统要求

步骤一：安装 Codex CLI

方式一：npm 安装（通用）

方式二：Homebrew（macOS 推荐）

步骤二：配置 Codex

背景

1. 获取 API Key

2. 创建配置文件

3. 配置内容

步骤三：设置环境变量

Windows 用户

Mac/Linux 用户

验证环境变量

启动命令

CLI 原生命令

VS Code 中使用

高级配置

模型上下文协议（MCP）

CI 模式（非交互模式）

配置参数说明

常见问题

问题 1: Node 版本过旧

问题 2: 配置不生效

问题 3: API 调用失败

相关链接