1. 为什么值得花时间搞懂 config.tomlCodex 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.tomlPowerShell 里可以这样建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 openaimodel是你要调用的模型标识符。这里有个大坑模型名必须和端点实际支持的名称完全一致。比如你接的是某个兼容服务它内部把模型映射成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/completionsresponses对应/v1/responses。绝大多数兼容端点只实现了 chat 协议所以填chat最稳。env_key是读取 API Key 的环境变量名。注意这里填的是变量名不是 Key 本身。Key 通过环境变量注入避免明文写进配置文件。3.3 环境变量注入的两种方式方式一写进 shell 配置文件echo export MY_API_KEYsk-xxxxxxxx ~/.bashrc source ~/.bashrc方式二临时注入适合测试MY_API_KEYsk-xxxxxxxx codex我推荐方式一但要注意如果你用的是 zsh得写进~/.zshrc如果用 fish语法不一样。写错文件的表现是配置里明明有 env_key但启动时报 Key 未设置。提示不要把 Key 直接写进config.toml的某个字段里。虽然某些版本支持api_key字段但明文存储风险太大而且一旦文件被同步到云端或提交到仓库后果很麻烦。3.4 可选字段超时、重试与代理网络不稳的环境下这两个字段很有用request_timeout_ms 60000 max_retries 3request_timeout_ms默认值偏短长任务容易超时中断。我一般设到 6000060 秒跑大文件分析时甚至设到 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_KEYsk-你的真实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 / 403Key 没读到或无效先确认环境变量真的导出了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.tomlTOML 语法错误用 tomllib 校验401 / 403Key 未导出或无效echo 环境变量curl 验证404模型名错或路径双 v1看报错 URLcurl /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 安全的一点经验配置文件本身不放 KeyKey 走环境变量这是底线。但环境变量也不是绝对安全同一台机器上的其他进程理论上能读到。如果多人共用一台开发机建议用独立的系统用户跑 Codex CLI或者用密钥管理工具注入环境变量。另外如果你不小心把带 Key 的配置或会话记录同步到了公开地方第一件事是去端点后台吊销那个 Key而不是删文件。删文件不能阻止已经泄露的 Key 被滥用。7. 我踩过的坑与最终建议折腾 config.toml 这件事说到底就是三个变量的对齐端点地址、模型名、Key。三者任何一个不对报错都会指向配置问题但真正的病灶可能在别处。我的经验是永远先用 curl 把端点验证通过再去配 Codex CLI这样能把问题范围缩小一半。另一个体会是别迷信文档里的默认值。不同版本的 Codex CLI 对字段的支持有差异有的版本认wire_api有的版本认api_type遇到字段不生效就去翻对应版本的源码或 release notes。社区答案时效性很差半年前的配置方法可能已经失效。最后分享一个小技巧把验证过的 config.toml 存一份到私有的笔记里标注好端点、模型、日期。下次换机器或者重装系统直接抄不用重新试错。这个习惯帮我省了至少好几次重复排查的时间。