1. 为什么值得花时间搞懂 config.toml
Codex CLI 是 OpenAI 推出的命令行编码代理工具，它能在终端里直接读写文件、执行命令、跑测试，把"对话式编程"搬到本地工作流里。但很多人装完之后卡在第一步：登录。官方默认走 ChatGPT 账号授权，浏览器一跳转、回调一失败，整个流程就断了。这时候config.toml就是唯一的出路——它允许你把 Codex CLI 接到任何 OpenAI 兼容接口上，用自己的 API Key 直接跑，绕开浏览器授权那一整套链路。
我最初接触这个配置，是因为团队里几台开发机没有图形界面，浏览器授权根本走不通。折腾了一下午，把config.toml的每个字段都试了一遍，也踩了不少坑：模型名写错导致 404、base_url 多了个斜杠导致连接被拒、环境变量没导出导致 Key 读不到。这些问题官方文档写得很简略，社区里的答案又散落在各个角落。所以我把整个配置过程、字段含义、报错排查整理成这篇东西，适合两类人看：一是刚装完 Codex CLI 还没跑通的新手，二是想把它接到自建兼容接口上的老手。
核心关键词先摆出来：Codex CLI、OpenAI 兼容接口、config.toml、报错排查。整篇内容围绕这四个词展开，从目录结构讲到字段逐行拆解，再到常见报错的一对一排查。读完你应该能做到：拿到任意一个 OpenAI 兼容端点，十分钟内配好并跑通第一个任务。
2. 配置文件到底放在哪，优先级怎么算
2.1 三个可能的路径与查找顺序
Codex CLI 读配置不是只看一个地方，它有一套查找顺序。搞不清楚这个，就会出现"我明明改了配置却不生效"的情况。按优先级从高到低：
- 当前工作目录下的
.codex/config.toml（项目级配置） - 用户主目录下的
~/.codex/config.toml（全局配置） - 环境变量注入的配置（部分字段支持）
项目级配置会覆盖全局配置的同名字段。这个设计很实用：你可以在全局配一个默认的兼容端点，然后在某个特定项目里覆盖成另一个模型或另一个 Key。
我实测下来，最省心的做法是只维护全局配置，项目级配置留给特殊场景。因为项目级配置容易跟着 git 提交上去，一不小心就把 Key 泄露了。如果你确实要用项目级配置，记得把.codex/加进.gitignore。
注意：不同版本对路径的支持略有差异，早期版本只认
~/.codex/config.toml。如果你改了项目级配置不生效，先确认版本，再确认文件名是不是config.toml而不是config.yaml或config.json。
2.2 目录不存在时的手动创建
装完 Codex CLI 后，~/.codex/目录不一定自动生成。如果直接vim ~/.codex/config.toml报"没有那个文件或目录"，先建目录：
mkdir -p ~/.codex touch ~/.codex/config.tomlWindows 下路径是%USERPROFILE%\.codex\config.toml，PowerShell 里可以这样建：
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.codex" New-Item -ItemType File -Force -Path "$env:USERPROFILE\.codex\config.toml"建完之后先别急着写内容，确认一下文件权限。Linux/macOS 下建议chmod 600 ~/.codex/config.toml，因为这个文件里会放 API Key，权限太松等于把钥匙挂在门上。
3. config.toml 逐行拆解
3.1 顶层字段：model 与 model_provider
一个最小可用的配置长这样：
model = "gpt-4o" model_provider = "openai"model是你要调用的模型标识符。这里有个大坑：模型名必须和端点实际支持的名称完全一致。比如你接的是某个兼容服务，它内部把模型映射成gpt-4o-2024-11-20，你写gpt-4o可能就报 404。排查方法很简单，先用 curl 打一下/v1/models接口，看返回列表里到底有哪些名字。
model_provider指向下面[model_providers.xxx]段的键名。默认值是openai，如果你要接自建端点，就得改成自定义的名字，并在下面定义对应的 provider 段。
3.2 model_providers 段：base_url 与 wire_api
这是整个配置的核心。以接入一个兼容端点为例：
[model_providers.myprovider] name = "My Compatible Endpoint" base_url = "https://api.example.com/v1" wire_api = "chat" env_key = "MY_API_KEY"逐行说：
name只是显示用的标签，随便写，不影响请求。base_url是端点根地址，必须包含/v1这一层（如果你的端点确实用/v1前缀）。很多人只写到域名，结果请求打到https://api.example.com/chat/completions，直接 404。wire_api决定用哪套协议。chat对应/v1/chat/completions，responses对应/v1/responses。绝大多数兼容端点只实现了 chat 协议，所以填chat最稳。env_key是读取 API Key 的环境变量名。注意这里填的是变量名，不是 Key 本身。Key 通过环境变量注入，避免明文写进配置文件。
3.3 环境变量注入的两种方式
方式一，写进 shell 配置文件：
echo 'export MY_API_KEY="sk-xxxxxxxx"' >> ~/.bashrc source ~/.bashrc方式二，临时注入（适合测试）：
MY_API_KEY="sk-xxxxxxxx" codex我推荐方式一，但要注意：如果你用的是 zsh，得写进~/.zshrc；如果用 fish，语法不一样。写错文件的表现是"配置里明明有 env_key，但启动时报 Key 未设置"。
提示：不要把 Key 直接写进
config.toml的某个字段里。虽然某些版本支持api_key字段，但明文存储风险太大，而且一旦文件被同步到云端或提交到仓库，后果很麻烦。
3.4 可选字段：超时、重试与代理
网络不稳的环境下，这两个字段很有用：
request_timeout_ms = 60000 max_retries = 3request_timeout_ms默认值偏短，长任务容易超时中断。我一般设到 60000（60 秒），跑大文件分析时甚至设到 120000。max_retries处理偶发的 5xx 错误，设 3 次比较平衡，设太多会在端点真的挂掉时卡很久。
如果你的网络需要走代理，Codex CLI 会读标准的HTTPS_PROXY环境变量，不需要在 config.toml 里单独配。这一点和很多工具不一样，别去翻文档找proxy字段，找不到的。
4. 完整配置模板与实操验证
4.1 一份可直接抄的模板
把下面这段存成~/.codex/config.toml，替换掉占位符即可：
model = "gpt-4o" model_provider = "myprovider" request_timeout_ms = 60000 max_retries = 3 [model_providers.myprovider] name = "My Compatible Endpoint" base_url = "https://api.example.com/v1" wire_api = "chat" env_key = "MY_API_KEY"然后：
export MY_API_KEY="sk-你的真实key" codex启动后如果看到交互界面，说明配置读到了。输入一句简单的话测试，比如"列出当前目录的文件"，看它能不能正常调用工具。
4.2 用 curl 先验证端点再配 Codex
这一步很多人跳过，结果把端点本身的问题误判成配置问题。配之前先手动打一发：
curl -s https://api.example.com/v1/chat/completions \ -H "Authorization: Bearer $MY_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-4o", "messages": [{"role": "user", "content": "hi"}] }'返回正常 JSON 说明端点、Key、模型名三者都对。如果这一步就失败，那问题不在 Codex CLI，别去改 config.toml，先解决端点侧的问题。这个排查顺序能帮你省掉大量无效折腾。
4.3 验证配置是否被正确加载
Codex CLI 有些版本支持打印当前配置。可以试：
codex config或者进交互界面后用/model命令看当前模型。如果显示的模型名和你配置的不一致，说明配置没被读到，回去检查路径和优先级。
5. 常见报错一对一排查
5.1 "无法加载 config.toml" 类报错
这个报错通常出现在启动瞬间，伴随"因此此对话串无法继续，请修复 config.toml"之类的提示。原因基本是 TOML 语法错误。TOML 对格式很敏感：
- 字符串必须用双引号，不能用单引号（虽然 TOML 支持单引号，但某些解析器实现不一致）
- 段名
[model_providers.xxx]里的点号不能有空格 - 布尔值是小写
true/false，不是True/False
排查方法：把配置贴到任意 TOML 校验器里过一遍。或者用 Python 快速验证：
import tomllib with open("config.toml", "rb") as f: print(tomllib.load(f))能打印出字典就说明语法没问题。
5.2 401 / 403：Key 没读到或无效
先确认环境变量真的导出了：
echo $MY_API_KEY如果输出为空，说明 shell 没加载。注意export只在当前会话有效，新开终端要重新 source，或者写进 rc 文件。
如果变量有值但还是 401，检查 Key 本身是否有效、是否过期、是否有额度。有些兼容服务的 Key 需要额外开通权限才能调用特定模型。
5.3 404：模型名或路径不对
404 有两个常见来源。一是模型名不匹配，二是 base_url 路径拼接错误。
判断方法：看报错信息里的完整 URL。如果 URL 是https://api.example.com/v1/v1/chat/completions，说明 base_url 里已经带了/v1，而 Codex 又拼了一次。这时候把 base_url 改成不带/v1的域名。反过来，如果 URL 缺了/v1，就补上。
这个"双 v1"问题我踩过两次，因为不同兼容服务的约定不一样，有的要求 base_url 带/v1，有的要求不带。没有统一标准，只能看报错 URL 反推。
5.4 连接超时 / 连接被拒
超时通常是网络问题，检查代理环境变量是否设置正确。连接被拒则可能是 base_url 写错了端口，或者端点本身没启动。
还有一种情况：base_url 末尾多了斜杠，比如https://api.example.com/v1/，某些实现会拼成//chat/completions，导致路径异常。养成习惯，base_url 末尾不加斜杠。
5.5 "没有可用的终端或文件读取工具"
这个报错和 config.toml 关系不大，通常是运行环境的问题。Codex CLI 需要能访问 shell 和文件系统。如果你在容器里跑，确认容器有可用的 shell；如果在受限环境里跑，确认权限足够。这个报错容易被误判成配置问题，其实改 config.toml 没用。
5.6 常见报错速查表
| 报错现象 | 最可能原因 | 排查动作 |
|---|---|---|
| 无法加载 config.toml | TOML 语法错误 | 用 tomllib 校验 |
| 401 / 403 | Key 未导出或无效 | echo 环境变量，curl 验证 |
| 404 | 模型名错或路径双 v1 | 看报错 URL，curl /v1/models |
| 连接超时 | 网络或代理问题 | 检查代理环境变量 |
| 连接被拒 | base_url 端口或斜杠问题 | 去掉末尾斜杠重试 |
| 无可用工具 | 运行环境权限问题 | 检查 shell 与文件权限 |
6. 几个容易忽略的实操细节
6.1 模型名的大小写与版本后缀
有些端点的模型名区分大小写，GPT-4o和gpt-4o可能一个能用一个报错。另外版本后缀很关键，gpt-4o和gpt-4o-mini是两个不同的模型，别混用。最稳的办法永远是先 curl/v1/models拿到准确列表。
6.2 配置改动后要重启
Codex CLI 在启动时读一次配置，运行中改 config.toml 不会热加载。改完必须退出重进。这个细节看起来废话，但我见过有人改完配置发现不生效，折腾半天才发现是没重启。
6.3 多端点切换的省事做法
如果你要在多个兼容端点之间切换，不用每次改 config.toml。定义多个 provider 段，然后改model_provider一行就行：
model = "gpt-4o" model_provider = "providerA" [model_providers.providerA] base_url = "https://api.a.com/v1" wire_api = "chat" env_key = "KEY_A" [model_providers.providerB] base_url = "https://api.b.com/v1" wire_api = "chat" env_key = "KEY_B"切换时只改model_provider的值，其他不动。这个做法在测试不同端点时特别省时间。
6.4 关于 Key 安全的一点经验
配置文件本身不放 Key，Key 走环境变量，这是底线。但环境变量也不是绝对安全，同一台机器上的其他进程理论上能读到。如果多人共用一台开发机，建议用独立的系统用户跑 Codex CLI，或者用密钥管理工具注入环境变量。
另外，如果你不小心把带 Key 的配置或会话记录同步到了公开地方，第一件事是去端点后台吊销那个 Key，而不是删文件。删文件不能阻止已经泄露的 Key 被滥用。
7. 我踩过的坑与最终建议
折腾 config.toml 这件事，说到底就是三个变量的对齐：端点地址、模型名、Key。三者任何一个不对，报错都会指向"配置问题"，但真正的病灶可能在别处。我的经验是永远先用 curl 把端点验证通过，再去配 Codex CLI，这样能把问题范围缩小一半。
另一个体会是，别迷信文档里的默认值。不同版本的 Codex CLI 对字段的支持有差异，有的版本认wire_api，有的版本认api_type，遇到字段不生效就去翻对应版本的源码或 release notes。社区答案时效性很差，半年前的配置方法可能已经失效。
最后分享一个小技巧：把验证过的 config.toml 存一份到私有的笔记里，标注好端点、模型、日期。下次换机器或者重装系统，直接抄，不用重新试错。这个习惯帮我省了至少好几次重复排查的时间。
