一、先定排查原则：一次只改一个变量

API中转站 排查最怕同时改很多东西。入口换了，Key 换了，模型名也换了，提示词还顺手改了一版，最后即使恢复正常，也不知道到底是哪一步起了作用。更稳的做法是一次只改一个变量，每一步都留下现象和结果。

把排查过程拆成层级以后，思路会清楚很多：环境变量是否存在，入口是否正确，Key 是否有效，模型是否可用，额度是否正常，网络是否稳定，任务输入是否过大。每一层都有明确的验证动作，不需要靠感觉来猜。

• 先复现：用最小样本确认问题是否稳定出现。
• 再分层：按环境、鉴权、模型、额度、网络、任务输入逐层排查。
• 后记录：每一步只改一个变量，并写下结果。
• 最后沉淀：把真实问题补进团队排查手册。

二、入口来源先统一：避免从旧配置开始排查

很多故障从一开始就查错方向，是因为团队成员使用的入口来源不一致。有人从旧文档复制地址，有人从聊天记录里找历史配置，还有人把测试环境的入口误放进开发环境。这样的情况下，后面再怎么换模型、换提示词，都可能只是绕圈。

建议排查前先确认统一入口。团队可以通过灵能API 官网入口：https://www.lnsns.com/ 查看当前接入信息，再和本地环境变量、团队文档、自动化脚本里的入口逐项比对。不要先假设入口一定没问题，它是整条链路的第一块地基。

入口核对清单

[ ] 本地 *ase **L 是否来自当前项目说明
[ ] 团队文档里的入口是否仍然有效
[ ] 自动化脚本是否使用同一套变量名
[ ] 开发环境和测试环境是否混用
[ ] 最近是否发生过入口、模型或 Key 变更
[ ] 是否有人从旧截图或旧聊天记录复制配置

如果入口来源无法确认，先不要继续排查模型质量。入口不稳定时，后面的错误会变得非常混乱：同样的 Key 在一个地方可用，在另一个地方失败；同样的模型名在一个环境能跑，在另一个环境不可用。先把入口收拢，排查才有共同起点。

• 入口、模型、Key 三个字段要一起核对。
• 文档、终端、脚本里的配置要使用同一套来源。
• 旧配置要标注废弃，不要静静留在项目里。

三、401 类问题：先看 Key，再看环境变量

401 类问题通常和鉴权有关，但不要只盯着 Key 本身。真实排查中，很多 401 是环境变量没有生效、变量名写错、终端没有重新加载、CI Secret 没注入、请求头被覆盖造成的。Key 正确，不代表运行时真的读到了正确 Key。

本地排查时，先检查变量是否存在，但不要打印完整 Key。可以只看长度、前后掩码或是否为空。CI 排查时，重点看 Secret 名称是否和脚本读取名称一致，以及当前任务是否有权限读取这个 Secret。

if (-not $env:CODEX_RELAY_API_KEY) {
  throw "缺少 CODEX_RELAY_API_KEY"
}

$keyLength = $env:CODEX_RELAY_API_KEY.Length
if ($keyLength -lt 20) {
  throw "CODEX_RELAY_API_KEY 长度异常，请检查是否复制完整"
}

Write-Host "API Key e**sts, length checked, value hidden"

如果确认变量存在，下一步再看 Key 是否过期、是否被撤销、是否属于当前账号和当前用途。通过灵能API 统一接入时，可以把个人 Key、CI Key、临时 Key 分开命名，排查时就能更快判断当前凭据是否用错场景。

• 不要在控制台、日志、截图里打印完整 Key。
• 先确认运行时读到了变量，再判断 Key 是否有效。
• CI 里最常见的是 Secret 名称和脚本变量名不一致。

四、403 类问题：重点看权限边界和模型范围

403 类问题和 401 不一样。401 更像“没有通过身份确认”，403 更像“身份确认了，但当前权限不允许”。在 API中转站 场景里，403 可能来自账号权限、模型权限、额度策略、Key 类型或任务范围限制。

排查 403 时，不要马上重新生成 Key。先看当前 Key 的用途：它是个人调试 Key，还是 CI 专用 Key？它允许访问当前模型吗？它是否被限制在某些任务或额度范围内？如果团队做过权限分层，403 往往是在提醒你“当前凭据不该做这件事”。

403 排查顺序

1. 确认账号状态
- 是否可用
- 是否存在额度或权限限制

2. 确认 Key 类型
- 个人 Key 是否被拿去跑 CI
- CI Key 是否被拿去做本地长任务
- 临时 Key 是否已经到期

3. 确认模型范围
- 当前模型是否在可用列表内
- 模型别名是否对应正确
- 是否需要单独开通或切换策略

这类问题尤其适合写进团队手册。因为它不是单纯技术错误，而是权限规则和使用场景之间的冲突。把规则写清楚，比让每个人遇到 403 时重新问一遍要省心。

• 401 看身份是否有效，403 看权限是否允许。
• 权限限制不一定是坏事，它能阻止错误场景继续消耗。
• 模型权限和 Key 类型要放在同一张表里维护。

五、模型不可用：别只看模型名有没有拼错

模型不可用不一定是拼写问题。它可能是模型别名已经调整、当前账号没有权限、默认路由策略改变、备用模型没有配置，或者任务指定的模型和 API中转站 当前支持的模型不匹配。

最稳的做法是维护一张模型别名表。团队成员不要在脚本里到处**实模型名，而是使用项目统一别名。比如 codex-default 用于日常代码任务，codex-long 用于长文档，codex-fast 用于短问答。别名背后的真实模型可以调整，但上层脚本尽量稳定。

模型别名表

codex-default
- 用途：日常代码解释、配置检查、短文档整理
- 验证样本：短代码片段   小段日志

codex-long
- 用途：长文档、长日志、跨文件摘要
- 验证样本：完整接口说明   较长错误日志

codex-fast
- 用途：轻量问答、命令说明、格式转换
- 验证样本：短问题   简单结构化输出

fall*ack
- 用途：默认模型不可用时临时切换
- 验证样本：基础连通   关键任务样本

灵能API 接入场景下，建议把模型别名、用途和验证样本写在同一处。以后出现“模型不可用”时，先看别名表和当前可用范围，再决定是修配置、换别名，还是临时启用备用策略。

• 脚本里少写硬编码模型名，优先使用团队别名。
• 备用模型不是装饰，必须提前跑过样本。
• 模型不可用要记录发生时间和恢复动作。

六、429 和额度问题：看频率，也看任务大小

429 常被理解成请求太频繁，但在实际项目里，它经常和任务大小、并发策略、失败重试、额度限制一起出现。比如一次自动化任务同时触发多个长日志分析，每个任务失败后又重复重试，很快就会把调用压力推高。

排查这类问题时，不要只看某一秒发了多少请求，还要看每个请求的输入规模和重试次数。短任务密集调用是一种压力，长任务反复失败是另一种压力。两者的处理方式不同。

429 排查清单

[ ] 是否有批量脚本同时运行
[ ] 是否有 CI 任务并发触发
[ ] 是否存在失败后无限重试
[ ] 是否一次传入过多文件或完整日志
[ ] 是否多个成员同时使用同一类任务
[ ] 是否有临时任务忘记关闭
[ ] 是否需要为自动化任务设置执行窗口

优化方式也要分情况。请求频率高，就降低并发或增加排队；输入过大，就先截取关键片段；重试过多，就设置最大重试次数和失败保存；任务无人认领，就先停用再复盘。

• 429 不只是频率问题，也可能是长任务和重试叠加。
• 自动化任务必须设置最大重试次数。
• 额度异常要回到具体任务和具体调用来源。

⏱️ 七、超时问题：网络、上下文和响应长度都要看

超时问题特别容易误判。有人会认为是网络不好，有人会认为是模型太慢，也有人会认为是 API中转站 不稳定。实际上，超时通常需要同时看三件事：网络链路是否稳定，输入上下文是否过长，输出要求是否过宽。

一个实用方法是用阶梯样本测试。先跑短问题，再跑中等代码片段，再跑长文档。如果短问题也超时，优先查网络和入口；如果短问题正常、长文档超时，优先查上下文和输出长度；如果只有自动化任务超时，优先查并发和重试策略。

超时分层验证

短样本
- 目标：验证入口和基础网络
- 现象：如果失败，先查网络和鉴权

中样本
- 目标：验证正常开发任务
- 现象：如果失败，查模型和请求格式

长样本
- 目标：验证上下文承载能力
- 现象：如果失败，拆分输入或限制输出

自动化样本
- 目标：验证并发与重试
- 现象：如果失败，降低并发并设置重试上限

• 短任务失败，先查链路。
• 长任务失败，先查上下文和输出长度。
• 自动化任务失败，先查并发和重试。

八、空返回和低质量输出：先查输入边界

有时候调用没有报错，但返回内容很空、很泛、没有可用信息。这类问题不一定是模型能力不够，常见原因是输入范围过大、提示词目标不清、上下文里噪音太多、要求模型一次完成太多任务。

比如你让 Codex 一次分析整个项目并给出完整重构方案，它很可能只能输出宽泛建议。换成“只分析某个模块的错误处理，并列出三个**证问题”，结果就会具体很多。排查低质量输出，先从输入边界和输出结构入手。

低质量输出优化模板

原始请求：
请分析整个项目哪里有问题。

更可控的请求：
请只分析 src/modules/order 下的错误处理逻辑。
输出结构：
1. 确定存在的问题
2. 证据来自哪个文件或函数
3. 可能影响的场景
4. 建议验证方式
限制：不要分析其他目录，不要推测未提供文件。

如果缩小范围后输出明显改善，说明问题不在中转入口，而在任务设计。如果缩小范围后仍然空泛，再检查模型选择、提示词模板和上下文材料质量。

• 低质量输出先查输入范围，不要急着换配置。
• 让模型引用证据位置，能减少泛泛而谈。
• 一次任务只解决一个明确问题，质量通常更稳。

九、把排查动作写成团队手册

排查一次问题并不难，难的是下次别让别人重新踩同一个坑。团队使用 API中转站 时，应该把常见错误、排查顺序、验证样本和处理动作写成手册。手册不需要很厚，但必须能被新人直接照着执行。

## Codex API中转站 排查手册

### 1. 先复现
- 使用短样本确认问题是否稳定出现
- 记录时间、环境、入口、模型别名

### 2. 按层排查
- 环境变量
- 入口地址
- 鉴权 Key
- 模型权限
- 额度和频率
- 网络和超时
- 任务输入

### 3. 记录结论
- 根因：
- 修复动作：
- 验证样本：
- 是否需要更新模板：

### 4. 复盘沉淀
- 是否补充新排查项
- 是否需要调整提示词
- 是否需要调整自动化重试策略

通过灵能API 统一接入后，团队可以把这份手册和接入说明放在同一位置。入口、变量、模型、Key、样本、故障处理都能在一处找到，排查效率会比临时翻聊天记录高很多。

• 手册要按现象组织，而不是按文件名组织。
• 每条排查建议都要能落到一个动作。
• 复盘后要更新手册，否则经验会重新散掉。

✅ 十、结语：好的排查流程，比临时经验更可靠

Codex API中转站 的故障排查，最重要的是顺序感。先看环境，再看入口；先看鉴权，再看权限；先看模型别名，再看备用路由；先看短样本，再看长任务。顺序对了，排查就会从混乱变成收敛。

实际团队里，不需要一次性建立很复杂的平台。先准备一份统一入口说明，一组固定验证样本，一张常见错误表，一份排查手册，就能解决大部分日常问题。后续遇到新故障，再把真实经验补进去。

当错误不再只停留在聊天记录里，当每次失败都能留下根因和动作，当新人也能按同一套顺序排查，API中转站 就会从“能用的入口”变成“可维护的工程链路”。这也是长期使用 Codex 时最值得投入的基础建设。

• 排查时一次只改一个变量。
• 记录时写清现象、原因、动作和验证。
• 沉淀时把真实问题变成团队手册。