Codex 配置自定义 AI API 完整指南：从0到1接入你的专属模型

Codex 配置自定义 AI API 完整指南：从零到一接入你的专属模型

你是否曾想过，让 Codex 不再依赖 OpenAI 官方服务器，而是接入你自己的本地模型、国产大模型或第三方中转服务？OpenAI Codex CLI 在设计之初就思考了模型的可扩展性，通过 Provider 机制让这一切成为可能。本文将从零开始，带你完成 Codex 自定义 API 的完整配置。

一、前置准备

1. 安装 Codex CLI

确保本地已安装 Node.js 22+，通过 npm 全局安装：

npm install -g @openai/codex

验证安装成功：codex –version

2. 配置文件位置

Codex 默认读取 ~/.codex/config.toml 作为主配置文件。如果该目录不存在，手动创建即可：

mkdir -p ~/.codex && touch ~/.codex/config.toml

Codex 的配置系统支持多种来源，优先级从高到低为：命令行参数 → Profile 设置 → config.toml 顶层配置 → 默认值。这意味着你可以通过命令行灵活覆盖文件配置。

二、理解核心配置字段

打开 config.toml，自定义 API 配置围绕三个关键字段展开：

字段	说明
base_url	API 服务的基础地址（末尾必须带 /v1）
wire_api	通信协议类型，填 “chat” 或 “responses”
env_key	用于读取 API Key 的环境变量名

⚠️ wire_api：配置中最容易踩的坑

Codex 在 0.80.0 版本存在一个关键分界线：

0.80.0 及以下：使用 Chat Completions API，wire_api = “chat”
0.81.0 及以上：使用 Responses API，wire_api = “responses”

目前大多数国产大模型和本地部署服务（如 Ollama、vLLM 旧版）仅支持 Chat Completions。如果你用的是新版 Codex，两种选择：

降级安装：npm install -g @openai/codex@0.80.0
寻找支持 Responses API 的推理后端（如新版 vLLM）

MiniMax 官方文档甚至明确提议使用 0.57.0 版本以避免兼容性问题。版本选择不是小事，这是决定后续配置能否生效的第一道关口。

三、实战配置详解

以下给出三种最常见的部署场景配置。

场景 1：接入本地模型（Ollama / vLLM）

使用 Ollama 部署本地模型（默认端口 11434），配置如下：

model = "qwen3.6-plus"
model_provider = "local_qwen"

[model_providers.local_qwen]
name = "Local Qwen"
base_url = "http://localhost:11434/v1"
wire_api = "chat"
env_key = "QWEN_API_KEY"

关键点：

本地服务使用 http 而非 https，否则会报 SSL 错误
base_url 末尾必须带 /v1，不要多写 /chat/completions
如果后端不需要认证（如本地 Ollama），env_key 可随意填一个值

如果你使用 vLLM 部署并启用了 Responses API 支持，可以这样配置：

model = "Qwen3.6-27B"
model_provider = "vllm"

[model_providers.vllm]
name = "Local vLLM"
base_url = "http://localhost:8000/v1"
wire_api = "responses"
env_key = "VLLM_API_KEY"

启动 vLLM 时确保启用工具调用支持。Codex 要求模型具备较强的 tool calling 能力，模型必须支持 OpenAI-Responses tool calling API。

场景 2：接入第三方中转服务

以 api.v3.cm 为例，完整配置如下：

model_provider = "vapi"
model = "gpt-5"

[model_providers.vapi]
name = "VAPI"
base_url = "https://api.v3.cm/v1"
env_key = "V_API_KEY"
wire_api = "chat"
request_max_retries = 4
stream_max_retries = 10

然后在终端设置环境变量：

export V_API_KEY="你的API密钥"

场景 3：多 Provider 切换

Codex 支持在一个配置文件中定义多个 Provider，通过 model_provider 字段自由切换：

model_provider = "cloud_gpt"
model = "gpt-5"

[model_providers.cloud_gpt]
name = "Cloud GPT"
base_url = "https://api.openai.com/v1"
wire_api = "responses"
env_key = "OPENAI_API_KEY"

[model_providers.local_qwen]
name = "Local Qwen"
base_url = "http://localhost:8080/v1"
wire_api = "chat"
env_key = "QWEN_API_KEY"

切换模型时，只需修改顶部的 model_provider 和 model 值即可。

四、Profile 进阶用法

如果你需要针对不同任务使用不同配置，Profile 是更好的组织方式：

profile = "production"

[model_providers.gac]
name = "gac"
base_url = "https://gaccode.com/codex/v1"
wire_api = "responses"
env_key = "CODEX_API_KEY"

[profiles.production]
model_provider = "gac"
model = "gpt-5.4"
model_reasoning_effort = "high"
approval_policy = "on-request"

[profiles.local_dev]
model_provider = "local_qwen"
model = "qwen3.6-plus"
sandbox_mode = "workspace-write"

启动时通过 –profile 切换：

codex --profile production   # 使用云端模型
codex --profile local_dev    # 使用本地模型

Codex 会优先加载 Profile 配置，再合并顶层默认值。

五、环境变量：安全红线和最佳实践

API Key 必须通过环境变量传入，绝不能直接写死在配置文件中 。你可以在 ~/.bashrc 或 ~/.zshrc 中添加：

export OPENAI_API_KEY="sk-xxx"
export QWEN_API_KEY="your-key"

保存后执行 source ~/.zshrc 使其生效。用 echo $QWEN_API_KEY 验证是否加载成功。

如果在 Windows 上使用 PowerShell：

$env:INTELLIGROW_API_KEY="sk-xxxx"

六、故障排查速查表

常见报错	可能缘由	解决方法
missing api key	环境变量未加载	执行 source ~/.zshrc 或重启终端
SSL 连接错误	base_url 用了 https 而本地服务是 http	检查 base_url，本地服务改为 http
wire_api no longer supported	版本与协议不匹配	降级到 0.80.0 或切换到 Responses API 后端
模型列表为空	协议不兼容或 base_url 路径错误	确认 base_url 只到 /v1，不要接 /chat/completions

总结

完成 Codex 自定义 API 配置只需把握三个要点：确认版本与 wire_api 匹配、正确填写 base_url（末尾 /v1，本地用 http）、API Key 通过环境变量注入。在此基础上，利用 Profile 实现多模型管理，就能让 Codex 灵活切换于云端模型与本地推理之间，真正成为一个属于你自己的 AI 编程助手。