这阵子折腾 Codex CLI 的人不少但很多人的真实需求其实不是连官方云服务而是把手头已有的第三方 API 接进去——要么是公司内部搭好的统一接口网关要么是云厂商提供的兼容接口要么是自建推理服务对外暴露的 endpoint。官方文档对新接入方不太友好config.toml 里几个字段藏得深Key 放错地方、路径写错、模型标识对不上都是日常。更烦的是 401、404 这种错误表面看都是请求没成功实际根因差了十万八千里。这篇文章干脆把我自己配置和排障的全过程拆开讲。config.toml 的几种写法、Key 到底放在哪、401 和 404 分别怎么定位都会覆盖。配置片段直接抄思路讲清楚看完你至少能少踩一半的坑。1. 配置结构config.toml 和 Key 为什么要分开先搞清楚 Codex CLI 的配置目录长什么样。以默认安装为例它把配置放在用户主目录下的.codex目录里核心文件就两个一个config.toml一个auth.json。很多人的第一反应是这不都是配置文件吗写一起不就行了但这两者的职责完全不同拆开是有明确理由的。config.toml存的是不敏感的运行参数模型名、用哪个 provider、base_url 指向哪、超时、日志级别等。这类信息即使被同步到工作电脑、提交进团队仓库也不会有泄露风险。而auth.json存的是真正的凭证也就是 API Key 或登录态 token属于高度敏感信息权限默认是只读给当前用户也不应该被任何版本管理工具捕获。~/.codex/ ├── config.toml # 模型、provider、base_url 等非敏感配置 ├── auth.json # 密钥/登录态权限通常为 600 └── logs/ # 运行时日志这个配置和密钥分离的设计几乎是现代 CLI 工具的共识。好处有两个第一密钥不会误入仓库第二你可以放心地把 config.toml 分享给同事对方只需要自己配 Key。如果你刚接触 Codex CLI建议先养成一个习惯——凡是sk-开头的东西默认只放进环境变量或 auth.json永远不要手滑写进 config.toml。另一个容易忽略的点是Codex CLI 支持通过环境变量CODEX_HOME指定配置目录也支持在启动命令里显式传--config。我见过有人改了半天 config.toml 没生效结果发现当前 shell 里CODEX_HOME指向了另一个目录改错了地方。先执行echo $CODEX_HOME和codex --version确认你正在操作的是哪一份配置这是排障的第一步。文件/变量用途是否可提交仓库config.tomlprovider、模型、路径、运行参数可以auth.jsonAPI Key、登录 token不行CODEX_HOME覆盖默认配置目录按需环境变量注入 Key 或开关调试看情况2. 实操在 config.toml 里接入第三方 API 的配置写法接第三方 API本质上就是告诉 Codex CLI别去默认的官方地址了去我给的地址用我给的模型标识。所以核心动作是改两个东西一是model_provider二是model。2.1 最简配置一个自定义 provider假设你拿到的第三方服务信息是这样的接口地址https://api.example.com/v1模型标识my-model-name给你的 Keysk-xxxxx那 config.toml 可以这样写model my-model-name model_provider my-provider [model_providers.my-provider] name My Provider base_url https://api.example.com/v1 env_key MY_API_KEY wire_api chat requires_openai_auth false字段逐个说明。base_url是请求的根地址Codex CLI 会根据wire_api自动拼后面的路径。如果base_url写到/v1wire_api设成chat那实际请求路径就是https://api.example.com/v1/chat/completions。所以你要确认服务商给你的 endpoint 已经包含了 API 版本前缀别自己多写或少写一层。env_key是本次接入最关键的一个字段它告诉 Codex CLI去哪个环境变量里取 API Key。上面例子中你需要先在 shell 里导出这个变量然后 Codex 会自动把它放到请求的 Authorization 头里。Key 放在哪一节详细讲这里先记住config.toml里填的只是环境变量的名字不是 Key 本身。wire_api有两种取值chat和responses。绝大多数第三方兼容服务只实现了/chat/completions所以设chat最稳。如果你的服务商明确说支持新的 Responses API才设responses。设错了最常见的报错就是 404因为请求路径压根不对。requires_openai_auth是一个很容易踩的开关。它的意思是这个 provider 是否需要 Codex 的官方登录态。接第三方接口时务必显式写成false。如果不写某些版本会沿用默认行为往请求里附加一个官方登录 token第三方服务一验签就直接 401。2.2 用 profile 管理多个第三方服务如果你手里不止一个第三方 API甚至同时还要保留官方服务的配置别来回改 config.toml用 profile 就够了。Codex CLI 的配置支持profiles区块每一个 profile 是一套完整的哪家服务、哪个模型、哪个 Key的组合。[profiles.work] model my-model-name model_provider work-provider [profiles.work.model_providers.work-provider] name Work Provider base_url https://gateway.example.com/v1 env_key WORK_API_KEY wire_api chat requires_openai_auth false [profiles.personal] model another-model-name model_provider personal-provider [profiles.personal.model_providers.personal-provider] name Personal Provider base_url https://api.personal-example.com/v1 env_key PERSONAL_API_KEY wire_api chat requires_openai_auth false用的时候加一个--profile参数codex --profile work codex --profile personal这样切换不同接口服务只需要改启动参数不用动文件也不怕改错回不去。我个人的建议是只要接了两个以上 provider就立刻切到 profile 方案。否则你迟早会因为来回改配置搞混某次请求到底走了哪家服务。2.3 base_url 的常见坑多一层少一层关于base_url我见过太多因为路径层级出问题的案例。这里把规则讲透如果服务商的文档写的是https://api.example.com/v1/chat/completions那你的base_url要填https://api.example.com/v1因为wire_api chat会自动拼上/chat/completions。如果服务商的文档写的是https://api.example.com根地址但实际接口在根路径下直接就是/chat/completions没有/v1这一层那base_url可能得填https://api.example.com但这种情况极少见大多数兼容服务都有/v1前缀。如果服务商提供的是部署式接口路径里还可能带上具体的部署名比如https://api.example.com/v1/deployments/my-model/chat/completions这种路径很难直接套进 Codex 的base_url自动拼路径逻辑里。能不用这种特殊路径就不用非用不可的话优先考虑在网关侧把路径转发成标准/v1/chat/completions形态。一句话总结base_url写到API 版本根路径这一层不要带具体的接口名也不要落下/v1。3. Key 放哪里三种方式与优先级刚才配置里出现了env_key这只是告诉 Codex 去哪里找 KeyKey 本身怎么填进去还有讲究。我按推荐的优先级把方法列出来。3.1 环境变量最推荐的方式既然 config.toml 里指定了env_key MY_API_KEY那你只需要在启动 Codex 之前把这个环境变量导出就行export MY_API_KEYsk-xxxxx codex --profile work这里有个很容易忽略的细节环境变量是跟着当前 shell 生命周期的。你今天在终端里 export 了关掉终端窗口再打开变量就没了。所以至少要把它写进 shell 的启动文件里比如# 追加到 ~/.zshrc 或 ~/.bashrc export MY_API_KEYsk-xxxxx更讲究一点的做法是用 direnv 之类的工具按目录注入环境变量避免把 Key 写死在全局启动文件里。不过对大多数人来说写进~/.zshrc已经够用了只要保证你启动 Codex 的终端环境里能echo $MY_API_KEY看到值就行。调试的时候可以用一行代码快速确认环境变量是否生效[ -n $MY_API_KEY ] echo Key is set || echo Key is missing如果显示 missing后面的 401 排障就是白费劲问题根本不在服务商而是 Codex 压根没拿到 Key。3.2 auth.json官方服务的默认位置auth.json通常是执行官方登录流程后自动生成的里面存的是登录态 token 或官方 API Key。如果你只是接第三方 API严格来说不需要依赖这个文件用环境变量注入就够干净了。但有一个例外场景某些版本允许直接在这个文件里按配置项写入 Key。我建议你不要手动猜字段名去改它因为不同版本结构不一样改坏了 Codex 可能直接起不来。正确做法是让程序自己写优先跑官方的登录/设置命令让它把凭证塞进 auth.json。如果第三方服务商提供了专门针对 Codex CLI 的接入说明以服务商给的命令为准。无论哪种方式只要 auth.json 里出现了明文 token就记住两个底线一是不要把它提交进任何仓库二是文件权限最好保持 600只有当前用户可读写。检查权限的命令ls -l ~/.codex/auth.json如果不是-rw-------建议立刻chmod 600 ~/.codex/auth.json。3.3 Key 的优先级和从哪来的判断当环境变量和 auth.json 同时存在时Codex CLI 到底用哪一个不同版本可能有差异。但排障时可以按最朴素的原则来推先看 config.toml 里那个 provider 有没有指定env_key。指定了说明它优先从环境变量取没指定才会走 auth.json 或其他默认鉴权路径。我自己遇到过一次很诡异的 401config.toml 里明明写了 A 服务的env_key环境变量也导出了但请求还是打到官方服务上去了。后来发现是 shell 启动文件里老早 export 过一个OPENAI_API_KEY而 Codex 在某个环节把OPENAI_API_KEY当成了兜底 Key。所以排障第一步永远是确认实际生效的 Key 是哪一份别想当然。还有一点不要把 Key 直接当成参数写进 shell 历史里。比如codex --api-key sk-xxxxx这种命令执行完 Key 会留在.zsh_history文件里哪天文件被同步走等于明文泄露。用环境变量的方式就能避开这个问题。4. 401/404 排障从现象到根因的完整排查路径HTTP 401 和 404 是所有接入第三方 API 时遇到最多的错误。很多人一看到这两个状态码就懵其实它们的含义完全不同定位路径也不一样。4.1 401 Unauthorized先确认 Key 到底有没有被正确送到401 的意思是服务端知道你是谁但不想理你说白了就是鉴权失败。触发原因列表如下常见根因排查方法环境变量没设置或名字和env_key不一致echo $MY_API_KEY确认有值config.toml 里误填了 Key 本身而不是变量名检查env_key是否是FOO_BAR格式Key 已经过期或被服务商吊销到服务商控制台查看 Key 状态requires_openai_auth未设置成 false导致附加了错误鉴权显式写false重启后重试请求实际发到了别的服务而不是你配置的服务看日志确认实际请求的 Host 路径某些服务商要求 Header 里必须附带额外字段参考服务商文档补充配置最有效的定位方法不是反复改配置猜而是直接用 curl 模拟一次请求绕开 Codex 单独验证第三方接口本身是否正常curl -i https://api.example.com/v1/chat/completions \ -H Authorization: Bearer $MY_API_KEY \ -H Content-Type: application/json \ -d { model: my-model-name, messages: [{role: user, content: hi}] }重点看三件事返回状态码是不是 200。如果 curl 都返回 401说明配置层的可能性不大问题在 Key 本身或服务商侧。返回体里的错误信息。很多服务商会附带message字段告诉你key expired还是invalid key比状态码有用得多。curl 到api.example.com都通但 Codex 报错那说明 Codex 请求的地址、Header、路径或模型名与实际请求不一致回到配置上找差异。有个技巧是给 curl 加-v参数看握手细节重点看Authorization头是不是你预期的那串 Key 前缀。很多第三方的响应头里还会带WWW-Authenticate提示也能辅助判断。4.2 404 Not Found路径或模型标识不对404 的意思是你的请求地址不存在。接第三方 API 时404 基本都不是网络问题而是请求拼出来的路径在服务商那边没有对应资源。常见根因如下常见根因排查方法base_url缺少/v1前缀检查服务商文档里的 endpoint 层级base_url多写了/chat/completions只保留到版本根路径wire_api设错第三方只支持 chat 却设成 responses路径会变成/responses必 404模型标识不对服务商叫gpt-xx你配置里写成了别家名字服务商要求模型名带部署前缀按服务商提供的精确标识填写别凭记忆写我在实际项目里遇到的 404十次里有七次是wire_api设错或模型标识多空格、大小写不一致。有一位朋友排查了整整一个下午最后发现模型名末尾多了一个不可见空格。所以碰到 404先复制服务商文档里的模型标识再用引号包起来看长度别手敲。还有一个隐蔽场景某些服务商把兼容接口放在/openai/v1这种前缀下而不是标准的/v1。这时base_url要写完整比如https://api.example.com/openai/v1。这种信息通常只在文档最不起眼的地方写遇到 404 先翻 endpoint 说明。4.3 让排障更快的两个动作开日志和抓实际请求如果 curl 能通但 Codex 还是 404那就必须看清楚 Codex 实际发出的请求长什么样。Codex CLI 支持调试模式建议启动时加上--debug或设置环境变量打开详细日志具体以你安装版本的帮助输出为准。日志会记录它使用的 base_url、模型名、鉴权 header 是否存在以及收到的响应头。codex --profile work --debug看到实际请求路径后再和 curl 通的那个路径逐字符比对。只要路径、模型名、鉴权三者完全一致不可能一个通一个 404。不一致的话差异点就是根因。4.4 401/404 速查定位表状态码核心信号优先检查方向次要检查方向401鉴权失败env_key 是否设置、Key 是否过期requires_openai_auth 是否显式 false404路径/资源不存在base_url 层级、wire_api 类型模型标识、部署前缀、空格429限流Key 配额或请求频率服务商套餐500服务端异常服务商服务状态请求体格式是否异常这张表我建议存一下。大多数第三方 API 接入问题最后都可以归到路径对不对、Key 对不对、模型名对不对这三件事上没有任何玄学。5. 我的配置习惯与几条实用经验写到最后分享几条长期折腾下来的个人习惯不一定写进文档但确实能帮你省时间。第一永远先 curl 通再动 Codex。拿到任何第三方服务的 endpoint 和 Key第一件事是拿 curl 发一条最简单的消息。如果 curl 都过不了那不管 config.toml 怎么改都是白搭。这个动作能把服务商问题和Codex 配置问题快速切分开。第二把 config.toml 当成会被反复改的草稿养成备份习惯。我有一次升级 Codex CLI 之后配置格式被新版本不再兼容直接启动报错。当时幸好留了一份旧配置备份对照着才把新格式填对。所以每次大改配置前复制一份到一个固定的备份目录花不了几秒关键时刻很值。第三环境变量名要有区分度。不要所有第三方服务都用API_KEY这种名字否则你同时接两三个服务时环境变量互相污染查都查不出来。我习惯用服务名_API_KEY这种风格比如WORK_API_KEY、PERSONAL_API_KEY。config.toml 里的env_key和 shell 里 export 的名字必须严格一致大小写也不能差。第四关注版本变化。Codex CLI 的配置 schema 在快速迭代wire_api、requires_openai_auth这些字段都是后来才出现的。网上很多旧教程里少了这些字段抄过来不一定能跑。最稳的做法是每次安装新版本后先跑一下codex --help或codex config --help看看当前版本的配置项再对照填。最后再补一个具体的实用技巧如果你在局域网环境里访问第三方 API注意确认 DNS 解析和网络连通性。有时候 401 或 404 是因为请求压根没到达目标服务中途被拦截了返回了一个形似错误页的响应。这种时候curl -v的握手阶段信息能帮你先判断网络链路是否畅通再回来查配置。我自己排障时永远是先 curl再看日志最后才改 config.toml。这个顺序基本不会错。