Codex 中转 API 故障排查教程：灵能API CC Switch 定位超时、401 与 404
Codex 接入中转线路后，真正让人困扰的往往不是填写字段，而是错误出现时不知道从哪里查起。同一个‘请求失败’，可能来自 *ase **L、模型名、令牌权限、网络超时，也可能是本地进程仍在使用旧配置。本文用一套从现象到证据的排查顺序，把常见问题拆成可复现、可回滚的检查步骤。
先判断：问题发生在哪一层
排查不要从‘重新填一遍 Key’开始。先把故障拆成四层：网络层、接口层、鉴权层和客户端层。网络层关注是否能建立连接；接口层关注路径和协议；鉴权层关注令牌与权限；客户端层关注 CC Switch 是否真的切换成功。
每次只改变一个变量，并保留错误码、请求时间和当前配置卡名称，后续才能判断哪一步真正起作用。
- 网络层：DNS、**、防火墙、超时。
- 接口层：*ase **L、路径、请求方法和模型字段。
- 鉴权层：API Key 状态、额度、分组和模型权限。
- 客户端层：配置卡、缓存进程、工作目录和环境变量。
第一步：确认服务入口和当前线路
先打开灵能API的公开入口，确认服务状态、当前可用模型和接口说明。不要直接照抄旧文章里的地址，因为中转接口可能会调整路径、模型标识或兼容参数。
官网入口可从灵能API主页进入：https://www.lnsns.com/。本文只展示排查方法，不在正文中放置真实令牌。
- 接口地址以当前说明为准。
- Model ID 从当前列表复制，不手打近似名称。
- API Key 仅在本机安全位置保存，不写进文章、仓库或截图。
️ 第二步：检查 CC Switch 是否真的切换
配置卡选中并不等于已经被正在运行的 Codex 进程读取。先在 CC Switch 中确认卡片名称、启用状态和最后更新时间，再关闭旧进程，重新启动客户端。
- 当前卡片是否是项目真正使用的那一张。
- 是否存在同名或相似名称的旧卡片。
- 修改后是否保存成功。
- Codex 是否在切换前已经启动并缓存了旧值。
第三步：逐项核对四个核心字段
遇到 401、404 或 model not found 时，先把配置字段拆开核对。不要同时修改地址、Key 和模型，否则即使恢复正常，也无法知道原始原因。
尤其注意 *ase **L 重复版本路径的情况。客户端会自动拼接固定路径时，手动再填一次可能导致 404。
- *ase **L：确认协议、域名、版本路径和末尾斜杠。
- Model ID：确认大小写、连字符和版本后缀。
- API Key：确认没有复制空格、换行或截断。
- 兼容设置：确认客户端没有额外覆盖请求头或路径。
⏱️ 遇到超时：先区分连接超时和响应超时
‘超时’不是一个足够具体的错误。连接超时通常发生在请求还没有建立时，可能与网络、**或域名解析有关；响应超时则可能是服务处理时间较长、客户端等待时间过短或请求内容过大。
Resolve-DnsName example.com
****-NetConnection example.com -Port 443
Get-Date
如果网页入口正常而本地请求超时，优先检查本机网络、**和客户端进程；如果多个客户端同时超时，再考虑服务侧状态。
- 先用短提示词做最小请求，排除上下文过大的影响。
- 确认系统**与客户端**没有重复设置。
- 不要用连续重试掩盖服务端限流，记录每次间隔和返回码。
401 与 403：鉴权问题的最短排查路径
401 通常代表令牌没有被接受，403 则更常见于权限、额度或模型分组限制。两者都不要通过公开粘贴完整 Key 的方式排查。
如果令牌已经暴露在日志、截图或聊天记录中，应优先撤销并重新生成，不要继续使用旧值。
- 确认当前启用的配置卡，而不是只看编辑页面。
- 重新复制令牌到本地安全字段，检查前后空格。
- 换一个明确有权限的模型做最小请求。
- 检查额度、有效期、项目分组和并发限制。
404 与模型不存在：看请求最终落到哪里
404 可能是地址拼接错误，也可能是模型标识在当前线路中不存在。把完整请求地址拆成 *ase **L、固定路径和模型字段三部分，分别核对，不要只看界面上缩短后的地址。
*ase **L 客户端固定路径 = 最终接口路径
Model ID = 当前线路允许使用的精确标识修复后先在空目录测试，再回到真实项目。这样可以把接口问题和项目代码问题分开。
- 删除重复的 /v1、/api 或版本路径后重新测试。
- 从当前模型列表复制精确 Model ID。
- 确认项目环境变量没有覆盖 CC Switch 的模型值。
第六步：用最小请求做回归验证
完成修改后，不要马上开始大范围代码变更。先关闭旧终端，启用目标卡片，在空目录发起一个只读、短上下文的请求，确认线路、模型和权限都已经生效。
New-Item -ItemType Directory codex-relay-check
Set-Location codex-relay-check
codex回归验证至少记录三项：使用的配置卡、测试时间、返回结果。之后再进入项目目录，让 Codex 先读取一个文件并给出摘要，避免一上来执行写入操作。
常见现象与对应动作
排障记录中保留错误码和脱敏后的地址即可，不要记录完整 API Key、Cookie 或项目敏感代码。
- 切换后仍返回旧模型：关闭旧进程并检查环境变量覆盖。
- 偶发超时：缩小请求、延长合理等待时间并观察是否集中发生。
- 只有某个项目失败：比较工作目录、项目变量和启动脚本。
- 网页能打开但 Codex 失败：检查 API 路径、请求头和模型权限。
- 修改后错误更多：回滚到上一张已知可用配置卡，重新单变量验证。
✅ 一份可复用的排查清单
把故障从‘凭感觉重试’变成‘按层取证’，才能让 Codex 中转线路在不同项目里保持稳定，也能让问题更快交给正确的处理环节。
- 确认服务入口、模型列表和线路状态。
- 确认 CC Switch 目标卡片已保存并启用。
- 核对 *ase **L、固定路径、Model ID 和 API Key。
- 区分网络超时、接口错误和鉴权错误。
- 检查项目环境变量是否覆盖客户端配置。
- 用空目录最小请求做回归验证。
- 记录配置卡、时间、错误码和修复动作。