你在 Claude Code 里想让模型走 Codex 那条接口，结果一填就报鉴权失败、或者干脆没反应，改来改去不知道卡在哪一层。这篇按「先能通、再稳、再可控」的顺序给一条可执行的路径：从改哪个配置、验证到哪一步算通，到超时、并发、降级、日志这些上线前必须补齐的工程动作，最后给一套排错顺序。不保证一次就对，但每一步都能定位。
你在 Claude Code 里想让模型走 Codex 那条接口，配了半天不是鉴权失败就是干脆没反应，改来改去也不知道自己卡在哪一层。这篇不承诺一次就通，但给你一条能逐层定位的路径：先分清楚改的是哪一层配置，再按四步把第一次请求跑通，然后把超时、并发、降级、日志这些上线前必须补齐的动作做掉，最后给一套报错分类之后的排错顺序。每一步都写清楚怎么验证算过关。
整体原则是「先能通、再稳、再可控」。能通的意思是同一条密钥在命令行裸请求里返回正常结构；稳的意思是长任务不莫名其妙断；可控的意思是出问题你能从日志里追出是哪一层。下面按这个顺序展开。
先搞清楚你要改的是哪一层
Claude Code 侧能读到的配置入口就两类：环境变量和本地配置文件。改之前先确认当前进程实际读到的是哪一份，常见情况是你改了配置文件但当前 shell 已经导出过旧的环境变量，旧值优先级更高。改完要重启终端，只重开一个对话窗口是不够的，因为环境变量在进程启动时就固定了。
另一件必须先分清的事：你要连的是官方 Codex 地址，还是自己或第三方搭的兼容层。前者鉴权头字段是固定的，后者很可能要求你换一套字段名或换一个路径前缀。两边字段名不一致，表现就是一直卡在 401，你怎么换密钥都没用。
| 现象 | 大概率在哪一层 | 先做什么 |
|---|---|---|
| 同一条密钥命令行能通、客户端不通 | 客户端配置层 | 对比两边的地址、头部字段名、模型名是否完全一致 |
| 一直 401 且换密钥无效 | 头部字段名不匹配 | 确认是不是兼容层，看它要求的鉴权字段叫什么 |
| 404 且地址看着没错 | 路径或版本段写错 | 检查 Base URL 结尾斜杠和版本段 |
| 请求发出后长时间无响应 | 网络层或超时设置 | 先用非流式最小请求对照定位 |
第一次调通：按顺序做四件事
这一步的目标不是跑通一个真实任务，而是让一条最小请求返回正常结构。别一上来就上代理工具、别一上来就开流式，变量越多越难定位。顺序按下面的步骤走，每一步都有明确的验证动作。
- 确认环境变量真的生效在准备跑 Claude Code 的同一个 shell 里把相关变量打印出来看一眼。很多人是写进了 shell 配置文件但当前窗口没重新加载，或者写错了文件名导致根本没被读到。
- 检查地址结尾和版本段Base URL 结尾多一个斜杠、少一个版本段，都会直接给 404。这一条是 404 最常见的来源，改完就用裸请求打一次确认。
- 发一条最小请求只发一个很短的提示词，并且关掉流式。先看返回结构对不对、字段全不全，不要在这个阶段测长任务。
- 再开流式观察首字确认非流式没问题后再打开流式，重点看是不是首字正常、中途断流。断了就切回非流式定位，一次只改一个变量。
如果卡在这一步始终不通，先别急着怀疑自己的配置，到站内的在线实测页面确认服务本身是不是活的，避免把对方的临时故障当成自己的配置错误，白白调半天。
超时与并发：把默认值改掉
默认超时对代码类长任务普遍偏短。建议把连接超时和读取超时分开放：连接阶段可以给短一点，快速失败；读取阶段要给足，因为生成长内容本来就慢；最后再设一个整体超时兜底，防止某个请求永远挂着占住连接。
并发不要凭感觉往上加。先按任务类型分档：交互式补全这类对延迟敏感的，并发要压低；批量重构这类可以容忍排队的，串行或小并发排队跑更稳。具体每个服务的并发上限和限流口径，到站内服务目录里核对当时的说明，别照搬别人的数字。
- 连接超时短、读取超时长、整体超时兜底，三段分开设
- 交互式任务低并发，批量任务排队跑，别混在一起抢额度
- 遇到限流用指数退避加随机抖动，重试次数和退避上限都要设死
- 退避上限别超过用户能接受的等待时间，超了就干脆失败让用户重来
- 超时和限流同时上涨时，先降并发，再回头看超时，反过来调通常无效
降级与日志：出问题能复盘
降级要有明确顺序，别做成随机切换。建议的顺序是：主接口失败切备用地址；备用也失败，切到更小更快的模型先把交互撑住；两条都不行就明确报错返回，不要静默返回半截结果，那种结果比直接失败更难查。
日志至少要记四样东西，缺一样慢请求就追不下去：请求发起时间、这次用的哪个模型、整段耗时、结束原因（正常结束、超时、限流还是直接报错）。密钥和完整提示词不要原样落盘，脱敏之后再记，团队协作尤其要注意这一条。
| 日志字段 | 作用 | 注意 |
|---|---|---|
| 请求时间 | 对齐监控和其他服务日志 | 统一时区 |
| 模型标识 | 定位是不是切到了降级模型 | 记实际调用的那个，不是期望的 |
| 耗时 | 区分是慢还是卡死 | 超时和正常慢要能分开看 |
| 结束原因 | 一眼看出是限流还是超时 | 枚举值固定，别写自由文本 |
不通的时候按这个顺序查
排错最忌讳同时改多个东西。下面这个顺序的核心逻辑是：先按报错码分类，再确认你最近改过什么，然后用裸请求做对照，最后看服务端状态。每一步都在缩小范围，而不是碰运气。
- 先看报错码：401 是鉴权、403 是权限或地区、404 是路径或模型名、429 是限流、超时或连接被拒是网络层
- 再确认「换过什么」：今天只改了密钥就别去翻网络，每次只改一个变量是排错最快的办法
- 用一条脱离 Claude Code 的裸请求做对照，两个环境结果不一致，问题就在客户端配置
- 看服务端状态，区分「是我错了」还是「它挂了」
- 常见坑：不同厂商的密钥和地址混搭、配置文件里留着旧的历史字段、代理开着但没配白名单
把这套顺序固化成一张自查清单，贴在你的排错笔记里，下次不通用五分钟走一遍，比重新猜一遍快得多。
下一步配置连通之后，建议顺手把在用的服务可信度和价格口径核一遍，避免上线后才发现额度或稳定性不符合预期。→常见问题
Claude Code 里配好了，但发出去一直没反应、也不报错，先查什么？
先看是不是卡在网络层：关掉代理试一次，或把超时设短一点让它快速失败而不是一直挂着。没报错通常意味着请求发出去了但没等到响应，九成是超时或 DNS 解析问题，而不是鉴权问题。用一条裸请求做对照，如果裸请求秒回，那就是客户端这边还在读旧配置。
能不能在一次对话里同时用官方模型和 Codex 接口？
取决于客户端支不支持按会话切换模型来源。多数情况下你需要开两个终端窗口、或者配置两套环境变量分不同目录跑，混在一起容易互相覆盖。稳妥做法是把两套配置写进不同的启动脚本，而不是塞进同一个全局变量里，不然你永远不知道当前跑的是哪个。
接进去之后老是限流，是不是该换服务？
先别急着换。限流多半是并发数和请求节奏的问题，不是服务不行。把批量任务改成排队跑、加上退避重试，通常就能压下去。只有在你已经把并发降到很低、退避也做了还是频繁被限时，才值得去 /sites 目录里比一比别家的额度和限制口径再决定。
