Codex CLI 接入 OpenAI 兼容接口：config.toml 逐行讲解与常见报错排查（2026）

Codex CLI 默认连的是 OpenAI 官方接口。如果你用的是公司内部网关、聚合服务或者自己搭的兼容服务，只需要改一个文件：~/.codex/config.toml。这篇把每一行配置的含义、怎么验证是否生效、出错了从哪查，一次讲清楚。

1. 先确认 Codex 装好了

bash 复制代码

npm install -g @openai/codex
codex --version

能打印出版本号就行。macOS 也可以用 brew install codex 安装。

2. 一份最小可用的配置

下面的示例用的是我自己在用的模驿API 的接口地址，换成你自己的服务地址，改 base_url 一行即可：

toml 复制代码

model_provider = "moyiapi"
model = "gpt-6.1-sol"
model_reasoning_effort = "high"

[model_providers.moyiapi]
name = "模驿API"
base_url = "https://api.moyi-api.com/v1"
env_key = "OPENAI_API_KEY"
wire_api = "responses"

文件位置：macOS / Linux 是 ~/.codex/config.toml，Windows 是 C:\Users\你的用户名\.codex\config.toml。目录不存在就先建一个。

3. 每一行是什么意思

字段	作用	容易踩的坑
`model_provider`	指定用哪一组接口配置	必须和下面 `[model_providers.xxx]` 里的 xxx 完全一致
`model`	默认用的模型名	要和服务端支持的名字一字不差，比如 `gpt-6.1-sol`
`model_reasoning_effort`	思考深度，可选 `low` / `medium` / `high`	越高越慢、越费 token，简单任务用 `medium` 就够
`name`	这组配置的显示名	随便起，只影响展示
`base_url`	接口根地址	以 `/v1` 结尾，不要写到 `/responses` 或 `/chat/completions`
`env_key`	从哪个环境变量读 Key	Key 不要直接写进配置文件，放环境变量里
`wire_api`	用哪种协议调用	`responses` 走 Responses API；服务端只支持 Chat Completions 时改成 `chat`

4. 把 Key 放进环境变量

macOS（默认 zsh）：

bash 复制代码

echo 'export OPENAI_API_KEY="你的Key"' >> ~/.zshrc && source ~/.zshrc

Linux（bash）：

bash 复制代码

echo 'export OPENAI_API_KEY="你的Key"' >> ~/.bashrc && source ~/.bashrc

Windows（PowerShell）：

powershell 复制代码

[Environment]::SetEnvironmentVariable("OPENAI_API_KEY", "你的Key", "User")

Windows 设完要重新打开 PowerShell，新窗口才读得到。

5. 验证配置是否生效

不用进交互界面，直接跑一条非交互命令：

bash 复制代码

codex exec "用一句话介绍你自己"

能正常返回一句话，说明地址、Key、模型名三样都对了。报错的话看第 8 节。

6. 模型怎么选

GPT-6 系列目前三档，官方价格如下（每百万 tokens，输入 / 输出）：

模型	模型名	适合	价格
GPT-6.1 Sol	`gpt-6.1-sol`	日常写代码、改 bug，性价比最高	$2/2 /$ 2/10
GPT-6 Astra	`gpt-6-astra`	复杂重构、跨文件设计，上下文 1M	$10/10 /$ 10/50
GPT-6 Luna	`gpt-6-luna`	批量、简单、对速度敏感的任务	$0.1/0.1 /$ 0.1/0.5

经验上，默认用 GPT-6.1 Sol 配 high，遇到它解决不了的难题再切 Astra；跑批量脚本、写注释这类活用 Luna 配 low，成本只有 Sol 的二十分之一。进入 Codex 后输入 /model 可以临时切换。

7. 用 profile 管理多套配置

不同任务要不同模型时，不用每次改默认值，在配置文件里加几个 profile：

toml 复制代码

[profiles.quick]
model_provider = "moyiapi"
model = "gpt-6-luna"
model_reasoning_effort = "low"

[profiles.deep]
model_provider = "moyiapi"
model = "gpt-6-astra"
model_reasoning_effort = "high"

启动时指定：

bash 复制代码

codex --profile deep

8. 常见报错排查

现象	最常见原因	怎么查
401 / Unauthorized	Key 没读到或写错	执行 `echo $OPENAI_API_KEY`（Windows 用 `echo $env:OPENAI_API_KEY`）看能不能回显；Windows 记得重开窗口
404 / Not Found	`base_url` 少了 `/v1`，或者多写了路径	对照第 3 节，根地址以 `/v1` 结尾
400 / 不支持的接口	`wire_api` 和服务端不匹配	把 `responses` 改成 `chat` 再试
model not found	模型名拼错或服务端没有这个模型	到服务商控制台核对模型名
一直没响应	地址写错或服务暂时不可用	用浏览器打开服务商官网，确认能访问

小结

接入任何兼容接口，本质上就三件事：在 config.toml 里写对 base_url 和 model，把 Key 放进 env_key 指定的环境变量，再用 codex exec 跑一条命令验证。剩下的模型选择和 profile，按任务难度和预算慢慢调就行。