很多人把 Codex CLI 接到第三方中转或自建兼容层时，卡在同一类地方：Base URL 填了却没生效、环境变量和配置文件打架、一跑就 401 或 404 分不清是谁的问题。这篇不重复讲 Key 怎么拿、也不讲报错码的通用含义，只围绕 Codex 这一条链路，把该配的项、鉴权怎么对、报错先查哪一步列成清单，照着核对一遍基本能自己定位。
把 Codex CLI 接到第三方中转或自建兼容层，卡住的地方高度集中：地址填了没生效、环境变量和配置文件互相盖、一跑就 401 或 404 分不清是谁的锅。这篇不聊 Key 去哪申请，也不解释每个状态码的通用含义，只盯着 Codex 这一条链路，把该配的项、鉴权怎么对、报错先查哪一步拆成可核对的清单。
动手前先建立一个判断标准：任何一次失败，都要能说清是「连接没通」「身份没认」「模型不认」「额度不够」四类里的哪一类。说不清就别急着换 Key、换地址，那只会把变量越搞越多。下面按配置、鉴权、报错、兼容差异、收尾五段来。
该配的几项：一个都不能少，也别多
Codex 的配置分散在三处：环境变量、用户级配置文件、项目级配置文件。优先级不是靠猜的，改完必须新开终端或重启进程才生效——很多人「改了没反应」，其实是旧进程还捧着老值。第一次接新源，建议只留一处、其余清空，确认通了再谈覆盖。
- 接口地址：指向对方的兼容入口，注意尾部路径写法，多一个或少一个斜杠都可能落到 404。
- 密钥：走环境变量注入，别写进会提交的代码、截图或共享文档。
- 模型名：写目标平台实际认的写法，别照抄别处的名字，先拿一条最小请求打一下。
- 协议兼容档位：确认对方按哪套口径接收请求，选错通常表现为跑出别的模型或直接报错。
本地代理、证书、超时这几项也要一起对。多个同类变量同时存在时容易互相盖掉，具体口径和写法差异到 Base URL 与兼容层（/base-url） 核对，那边按站点列了对照。
鉴权方式：把请求头对上一次就好
第三方接入基本走 API Key 换请求头这一套，差别只在头的名字和前缀。先问清对方要哪一套，再决定 Key 怎么放进配置，而不是先配好再去试。有些站点按协议分开鉴权，同一个地址下两套头不通用；用错了未必报「没权限」，可能直接 401 甚至 400，很容易被当成 Key 失效。
| 现象 | 先怀疑哪层 | 一步验证 |
|---|---|---|
| 一直 401 | 头名或前缀不对 / Key 状态异常 | 用同一条 Key 打官方或已知能用的通道 |
| 400 带鉴权字样 | 协议口径与头不匹配 | 换成对方文档指定的那套头重试 |
| 部分时段可用 | Key 是共享或临时的 | 确认调用方身份识别口径再排查 |
| 换机器就失效 | Key 只配在本地环境 | 按只含键名的模板重新注入 |
Key 只放环境变量或本地配置文件。填进第三方客户端前先过一遍 把 Key 填进第三方工具前，先确认这 6 件事（/before-you-paste-key）。用共享 Key 或临时 Key 的场景，要额外确认调用方身份识别口径，否则出现「昨天能用今天不能用」时无从查起，可参考 临时 Key 检测怎么做（/temp-key-detection-runbook）。
常见报错：按这个顺序排，别乱试
排错的效率取决于顺序，不取决于你换了多少把 Key。先切回官方或已知能用的一条通道，同一份配置只换地址：能通，问题在第三方侧；不通，问题在本机配置。这一步能砍掉一半瞎试。
- 定位层看报错落在哪一层：连接层（地址、端口、证书、代理）、鉴权层（头名、前缀、Key 状态）、模型层（名字不存在、无权限）、额度层（限流或余额）。
- 做最小复现一次请求、不带上下文、不并发、关掉流式，把变量降到只剩一个；这条在排查任何接口问题时都成立。
- 单变量替换每次只改一个配置项并立刻重测，改两处以上等于没改，结果无法归因。
- 交叉验证确认不是单次抖动，用站内接口测速和状态页再打两次，看结果是否稳定。
多来源混用时，按 接口报错先怀疑谁（/api-error-triage-order） 的顺序走一遍，比逐个换 Key 省时间。
兼容层差异：换源后表现不一样怎么办
同一个模型名在不同站点可能对应不同版本或不同上下文长度，换源后先跑一条固定小任务做对照，别拿长任务试。这条小任务要固定输入、固定长度、固定输出要求，否则每次结果不同你也说不清是源的问题还是任务本身波动。
- 流式输出
- 最容易在兼容层上出差异，某功能突然不灵先怀疑兼容层，不是代码写错。
- 工具调用
- 字段名与嵌套结构各站写法可能不同，报错信息往往指向参数而非网络。
- 结构化输出
- 格式约束被忽略时，通常表现为返回内容对但结构不合规。
- 多模型路由
- 出错自动换源会把问题藏起来，排查阶段先关掉降级。
多模型路由或降级配置会让请求实际落到哪变得不可见，落地做法见 多模型路由与降级（/multi-model-routing-fallback）。确认对方状态是否已经变化，用 Codex 雷达（/codex-radar） 和站内接口测速做交叉验证，别只看单次结果就下结论。
跑通之后：把接入这步固定成清单
能跑通不代表能长期跑通。把可用配置写成一份只含键名的模板，值走本地环境，换机器或换人时按模板填，不靠记忆。模板里不要出现真实 Key，也不要在群里传截图。
- 固定一条验证请求，改动配置后先跑它，通过再跑正式任务。
- 记录每次改动的地址、模型名和对应结果，出问题能回溯到是哪次改动引入的。
- 接口日志字段按需精简，参考 日志该记哪几个字段（/api-log-fields-replay） 避免漏掉关键归因信息。
- 团队多人使用按最小权限发 Key，交接与轮换参考 多把 Key 的轮换与最小权限（/key-rotation-least-privilege）。
判断标准很简单：换一台干净机器，只按模板填值，能不能在五分钟内跑通那条验证请求。能，说明接入这步已经固定下来了；不能，说明还有配置藏在你的本机环境里。
下一步把配置核一遍不如先把测速和状态看一眼，确认当前这条通道是不是还在正常水位。→常见问题
Codex 接第三方一定要改 Base URL 吗？
多数情况下要，但改哪一层取决于你用的是 CLI 配置、环境变量还是别的客户端设置。先确认改的那处真正生效（新开终端、打印一次生效配置），再判断对方是否兼容。有的站点只兼容部分能力，地址对了功能也未必全有。
一上来就 401，是不是 Key 错了？
不一定。401 可能是头名或前缀不对、Key 带了多余空格、环境变量被别的值覆盖，也可能确实是 Key 失效或被限。排查顺序是先确认实际发出的请求头，再换一条已知可用的通道对比，最后才怀疑 Key 本身。
同一个 Key 昨天能用今天不通，先动哪里？
先别改配置，先做对照：同 Key 换官方通道、同通道换另一把 Key，两次结果能很快区分是站点侧还是本机侧。然后查额度、限流、站点公告和状态页；具体口径到站内报错与状态相关页面核对当时的记录。
