Codex 配置自定义 AI API 完整指南：从0到1接入你的专属模型，2026年本地模型 / 第三方中转一站式配置

如今 AI 编程工具早已成为研发提效的标配，OpenAI Codex CLI 凭借强大的代码理解、生成与调试能力，被大量开发者用于项目开发、脚本编写与自动化运维。很多使用者都会遇到一个问题：默认直连官方接口网络不稳定、无法自由切换本地部署模型、也不方便使用国内合规第三方中转平台。

Codex CLI 原生支持多服务商扩展机制，借助 Provider 配置能力，我们可以自由对接本地私有大模型、国产开源模型以及国内合规API中转服务。本文从环境准备、核心参数解读、多场景配置、高阶分组管理到排错方案，手把手带大家从零完成 Codex 自定义 API 全流程部署，兼顾新手与运维人员使用需求。

一、前期环境准备

在开始配置自定义接口前，需要先完成基础软件安装与目录初始化，全平台通用。

1. 安装 Codex CLI 客户端

Codex 依赖 Node.js 运行环境，要求版本 ≥22，打开终端执行全局安装命令：

npm install -g @openai/codex

安装完成后，输入以下命令校验是否部署成功：

codex –version

2. 初始化配置目录

Codex 所有自定义规则、接口信息都会统一存放在专属配置目录中，默认路径为 ~/.codex，主配置文件为 config.tom。
执行命令创建目录与空配置文件：

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

补充：Codex 配置存在明确的加载优先级，由高至低依次为：命令行临时参数 > 分组(Profile)配置 > 全局顶层配置 > 程序默认配置。我们可以利用这一特性，针对不同项目、不同模型灵活切换配置，无需反复修改文件。

二、核心配置参数详解

config.toml 是整个自定义接入的核心文件，所有接口适配都围绕三个关键参数展开，也是新手最容易出错的地方。

重点版本兼容提醒（高频踩坑点）

Codex 不同版本对通信协议强制区分，版本分界线为 0.80.0：

目前国内绝大多数开源模型、本地部署推理服务、第三方中转平台仅适配 chat 协议。如果你的 Codex 为新版，有两种解决方案：

• 方案一：降级至兼容版本，执行命令 npm install -g @openai/codex@0.80.0；
• 方案二：选用支持 Responses 协议的后端服务。

行业内部分工具为了降低适配难度，也会推荐使用 0.57.0 经典稳定版，可根据自身业务选择。

三、多场景实战配置

结合国内使用环境，划分本地私有模型、Token173第三方中转、多服务商快速切换三大主流场景，附上完整可直接复用的配置代码。

场景一：接入本地部署模型（Ollama / vLLM）

适用于内网开发、数据隔离、私有化部署场景，本地服务默认使用 http 协议，注意区分协议类型。

1. Ollama 本地模型配置（默认端口 11434）

```toml
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` 等子路由；
– 本地无鉴权服务时，`env_key` 可随意自定义变量名。

#### 2. vLLM 推理服务配置（支持 Responses 协议）

```bash
```toml
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 对模型函数调用有硬性要求。

### 场景二：接入 Token173 国内中转服务
国内开发者直连海外官方接口普遍存在延迟高、连接失败、风控拦截等问题，`Token173` 作为聚合中转平台，全面兼容 OpenAI 标准协议，可无缝对接 Codex。
完整配置示例：

```bash
```toml
model_provider = "token173"
model = "gpt-5"

[model_providers.token173]
name = "Token173 中转服务"
base_url = "https://token173.com/v1"
wire_api = "chat"
env_key = "TOKEN173_API_KEY"
request_max_retries = 4
stream_max_retries = 10

配置完成后，在终端声明环境变量（写入你的 Token173 平台密钥）：
```bash
export TOKEN173_API_KEY="你的SK密钥"

场景三：多服务商一键切换配置

当你需要在海外官方接口、Token173中转、本地模型之间频繁切换时，可以在同一个配置文件中定义多个 Provider，修改顶部字段即可快速切换：

```toml
# 默认使用Token173中转
model_provider = "token173"
model = "gpt-5"

# 配置1：Token173 中转
[model_providers.token173]
name = "Token173"
base_url = "https://token173.com/v1"
wire_api = "chat"
env_key = "TOKEN173_API_KEY"

# 配置2：OpenAI 官方接口
[model_providers.openai]
name = "OpenAI Official"
base_url = "https://api.openai.com/v1"
wire_api = "responses"
env_key = "OPENAI_API_KEY"

# 配置3：本地模型
[model_providers.local_qwen]
name = "Local Qwen"
base_url = "http://localhost:8080/v1"
wire_api = "chat"
env_key = "QWEN_API_KEY"

## 四、Profile 分组高阶用法
针对不同业务场景（正式生产、本地调试），可以使用 `Profile` 分组功能独立管理多套配置，不用反复修改全局文件。
示例配置：

```bash
```toml
# 默认加载生产分组
profile = "production"

# 通用服务商配置
[model_providers.token173]
name = "Token173"
base_url = "https://token173.com/v1"
wire_api = "chat"
env_key = "TOKEN173_API_KEY"

# 生产环境分组
[profiles.production]
model_provider = "token173"
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"

启动命令按需指定分组：
```bash
# 加载生产环境配置
cod –profile production

# 加载本地调试配置
cod –profile local_dev

五、环境变量规范（安全最佳实践）

严禁将 API 密钥明文写入配置文件，这是开发安全基本准则。所有密钥统一通过系统环境变量注入。

Linux / macOS（bash / zsh）

编辑环境变量配置文件：

# zsh 用户
vim ~/.zshrc
# bash 用户
vim ~/.bashrc

写入变量：

export TOKEN173_API_KEY="你的密钥"
export QWEN_API_KEY="本地模型密钥"

保存后生效：

source ~/.zshrc

验证变量是否加载成功：

echo $TOKEN173_API_KEY

Windows PowerShell

临时设置（当前会话生效）：

$env:TOKEN173_API_KEY="你的密钥"

六、常见问题与排错方案

整理国内使用过程中高频报错、原因及对应解决办法，快速定位问题：

七、总结

Codex CLI 强大的自定义扩展能力，让它不再局限于 OpenAI 官方服务。整套配置的核心逻辑可以总结为三点：

结合 Token173 等中转平台，搭配本地私有化模型，我们可以根据业务自由切换服务端，兼顾网络稳定性、数据安全性与使用成本。掌握这套配置方案后，Codex 可以完全适配国内各类研发场景，成为全场景通用的 AI 编程工具。