一、先理解稳定性：不是不报错，而是出错可预期

把 Codex 接到 API中转站 后，最容易出现的误区是：把“能跑通”当成“稳定”。短期看演示都正常，长期看会遇到各种预料之外的情况：网络抖动导致请求超时、高峰期触发频率限制、模型侧临时不可用、自动化脚本在错误场景下疯狂重试。如果没有事先定义行为，这些情况的表现就是随机的，排查起来毫无头绪。

更合理的做法，是把稳定性当成一组明确的行为契约。超时契约定义“等多久算失败”；重试契约定义“失败后怎么办”；限流契约定义“被限流时怎么排队”；降级契约定义“关键任务如何保住”。每一条契约都要能落到配置里，而不是停留在口头约定。这样故障发生时，系统的反应是可预测的，人介入时也有明确的抓手。

• 超时契约：连接超时、读取超时、总超时分别设多少，写清楚。
• 重试契约：哪些错误码可重试、重试几次、间隔多久，写清楚。
• 限流契约：触发 429 后是排队、退避还是降级，写清楚。
• 降级契约：关键任务失败时切备用线路还是暂停，写清楚。

二、从统一入口开始：先确认灵能API可用模型和接入信息

稳定性策略的前提，是先有一个稳定统一的接入入口。进入 灵能API 后，先确认三件事：*ase **L 是否清楚、API Key 是否独立、当前账号可用模型和限流口径是否已经列明。官网入口可以直接记录为 https://www.lnsns.com/，团队文档里建议把它放在“接入信息”部分，而不是散落在聊天记录里。

这里要注意，接入信息和稳定性策略不是一回事。接入信息回答“请求从哪里走、用什么凭证”；稳定性策略回答“请求失败时系统怎么办”。很多团队前期只保存了 Key，却没有保存超时和重试配置，后面一出问题，连“当时的请求等了多久才放弃的”都查不到。

接入信息建议记录：
- *ase **L：以当前控制台说明为准
- API Key：按人员、项目或自动化任务分别创建
- 限流口径：记录账号级、Key 级的频率限制说明
- 负责人：写清楚谁负责更新配置，谁负责处理故障

• 不要只把 Key 写进工具里，至少要有一份团队可读的接入说明。
• 频率限制口径要记录下来，它是设计重试和排队策略的依据。
• 如果项目多人协作，建议把个人调试 Key 和团队任务 Key 分开。

️ 三、错误分类：401、403、404、429、5xx、超时要分开处理

所有失败都走同一条处理路径，是稳定性问题最常见的根源。401 是凭证错了，重试一百次也没用；429 是触发限流，马上重试只会更糟；500 是服务端临时问题，等一会儿重试可能就成功。不分类型统一处理，要么把能恢复的错误误判成致命错误，要么把致命错误拖成无限重试。

建议先建立一张错误分类表，每一类写清楚“是否可重试、重试间隔、是否告警、是否切换备用线路”。这张表是后面所有稳定性配置的基础，任何脚本和工具都应该按这张表实现，而不是各自即兴处理。

错误分类表示例：
 
错误类型 | 含义       | 可重试 | 处理方式
401      | 凭证无效   | 否     | 立即停止，检查 Key
403      | 权限不足   | 否     | 立即停止，检查权限
404      | 模型不存在 | 否     | 停止，检查模型 ID
429      | 触发限流   | 是     | 指数退避，最长等待上限
5xx      | 服务端错误 | 是     | 固定间隔重试，超过次数告警
timeout  | 请求超时   | 是     | 按连接/读取/总时长分层处理

• 不可重试的错误要立即失败并告警，不要默默吞掉。
• 429 的处理核心是“慢下来”，不是“多试几次”。
• 分类表要覆盖团队实际遇到的错误，不要只抄标准定义。

⏱️ 四、超时设置：连接、读取、总时长三层分开设

超时是稳定性里最基础也最容易设错的参数。只设一个总超时，长任务可能被误杀；完全不设超时，挂起的请求会无限占用连接。合理的做法是分三层：连接超时控制“能不能连上”，读取超时控制“两次数据之间最长等多久”，总超时控制“整个请求最长花多久”。

三层超时的取值要有依据。连接超时通常很短，几秒就够了；读取超时要看模型的典型响应时间，留有余量但不无限宽容；总超时要结合任务类型，比如轻任务 30 秒、代码任务 120 秒、长上下文任务 300 秒。所有取值写进配置，不要散落在代码里。

超时配置示例：
 
connect_timeout: 5s     # 建立连接最长等待
read_timeout: 60s       # 两次数据包之间最长等待
total_timeout:          # 按任务类型设定
  light_task: 30s
  code_task: 120s
  long_context_task: 300s

• 读取超时触发频繁时，先检查任务是否本身就需要长响应。
• 总超时要比各层超时之和留有余量，避免逻辑冲突。
• 超时取值变更要记录原因，方便回溯“为什么当时是 60 秒”。

五、重试策略：退避不是目的，防止雪崩才是

重试本身没有错，错的是没有节奏的重试。所有请求在同一秒失败，又在同一秒重试，服务端压力瞬间翻倍，这就是重试风暴。正确的重试策略是指数退避加随机抖动：第一次等 1 秒，第二次等 2 秒，第三次等 4 秒，每次再加一点随机偏移，让重试请求在时间上散开。

重试必须有上限和兜底。上限一般是 3 到 5 次，超过后要么切换备用模型，要么把任务挂起等人处理。对于自动化批量任务，还要限制整体并发，避免单个脚本的失败重试挤占其他任务的配额。

retry_policy:
  **x_attempts: 4
  *ackoff: exponential   # 1s, 2s, 4s, 8s
  jitter: random(0~30%)  # 每次叠加随机抖动
  retry_on: [429, 500, 502, 503, timeout]
  no_retry_on: [401, 403, 404]
  on_exhausted: fall*ack_or_alert

• 429 触发时的实际等待时间要以响应头提示为准，没有提示再按退避计算。
• 重试次数不是越多越好，超过上限说明问题不是抖动而是故障。
• 每次重试都要记录日志，否则排查时无法还原时间线。

六、限流应对：429 之后的排队与降级

频率限制不是异常，而是 API中转站 的正常保护机制。触发 429 说明当前请求速率超过了配额，正确的响应是降低速率，而不是提高尝试频率。团队层面要把 429 当成一个信号：要么是任务调度太激进，要么是配额需要调整，要么是某些脚本在无谓地刷请求。

应对 429 可以分三步：第一步，读取响应中的限流提示，决定等待多久；第二步，把等待中的请求放入队列，按优先级依次发出，关键任务排在前面；第三步，如果队列持续积压，触发降级，比如切到备用模型、改用轻量模型先出结果、或推迟非关键任务。

限流应对流程：
 
1. 识别：收到 429，记录限流口径和触发时间点
2. 退避：按响应提示或指数退避等待
3. 排队：请求进入队列，关键任务优先
4. 降级：队列积压超过阈值时切换备用线路
5. 复盘：统计触发频率，判断是否需要调整配额或调度

• 不要把 429 当失败直接丢弃，排队往往比失败重试更省资源。
• 队列要有长度上限，避免无限积压拖垮整个流程。
• 频繁触发限流时，先查是不是自动化脚本并发过高。

️ 七、熔断与降级：故障扩大之前先断开

当错误率持续升高时，继续放量只会把问题放大。熔断机制的作用是：在一段时间内错误超过阈值时，自动停止向故障线路发请求，给服务端恢复的时间，同时把流量切到备用线路或返回预设的降级结果。熔断器通常有三个状态：闭合（正常放行）、打开（拒绝请求）、半开（试探恢复）。

降级要和熔断配套定义。比如代码**线路熔断后，轻量**任务可以切到默认模型先跑一版；文档整理任务熔断后，可以先返回“稍后重试”并把任务挂起；涉及发布决策的任务，熔断后必须人工介入，不允许自动降级。降级的底线是：宁可不出结果，不能出错误结果。

circuit_*reaker:
  error_threshold: 50%      # 错误率阈值
  window: 60s               # 统计窗口
  open_duration: 30s        # 打开状态持续时间
  half_open_pro*e: 2        # 半开状态试探请求数
  on_open:
    - route_to: *ackup_model
    - notify: oncall_owner
  on_half_open_success: close
  on_half_open_failure: reopen

• 熔断阈值要基于历史错误率设定，不要照搬别人的数字。
• 半开试探失败要重新计时，避免刚恢复又被打垮。
• 降级结果要明确标识，不能把降级输出当成正常输出。

八、故障演练：每类稳定性规则都要经过真实演练

稳定性规则不能只看配置是否正确，要在受控环境里真的制造故障，看系统反应是否符合预期。演练的内容包括：模拟 429 看退避是否生效、模拟 500 看重试是否按间隔执行、模拟超时看分层设置是否生效、模拟连续失败看熔断是否按时打开。没有经过演练的规则，关键时刻大概率不工作。

演练要有记录，每次演练写清楚场景、预期行为、实际行为、差异原因。如果实际行为和预期不一致，先修规则再上线。对于自动化任务，建议每月跑一次常规演练，配置变更后额外加跑一次，确保新配置没有破坏已有的稳定性保障。

故障演练清单：
 
场景       | 注入方式         | 预期行为
429 限流   | 模拟限流响应     | 退避排队，不立即重试
500 错误   | 模拟服务端错误   | 按间隔重试，超限熔断
读取超时   | 延迟响应数据     | 触发 read_timeout，不重试总超时
连续失败   | 持续返回错误     | 熔断打开，切备用线路
恢复探测   | 错误后恢复正常   | 半开试探成功后闭合

• 演练环境要和生产配置一致，否则演练结果没有参考价值。
• 演练要覆盖边界情况，比如重试中再次触发 429。
• 演练记录要归档，作为后续调整阈值的依据。

九、团队规范：告警、值班和故障响应写在一起

稳定性规则最终要落到人。建议给每类告警指定负责人和响应时限：401、403 这类凭证问题通知配置负责人，429 限流通知任务调度负责人，连续 5xx 和熔断通知值班同学。告警发出后没人响应，比没有告警更糟，因为团队会误以为一切正常。

灵能API 的角色是提供统一入口和模型调用基础，团队自己的工作是把入口整理成可执行规范。谁接收告警？多久算响应超时？熔断期间关键任务谁决定降级？故障复盘谁主持？这些问题提前写清楚，比故障发生时临时拉群要稳得多。

告警响应登记表：
 
告警类型       | 负责人       | 响应时限 | 升级路径
401/403       | 配置负责人   | 15 分钟  | 30 分钟未响应升级技术负责人
429 持续触发   | 调度负责人   | 30 分钟  | 涉及关键任务时立即升级
5xx 连续错误   | 值班同学     | 10 分钟  | 触发熔断时通知全体
熔断打开       | 值班同学     | 立即     | 同时通知备用线路负责人

• 告警要分级，不要所有故障都打扰所有人。
• 响应时限要现实，定一个没人能做到的时限等于没定。
• 故障复盘只讨论规则和流程，不追责个人，复盘结论要落回配置。

十、复盘优化：每月看一次错误率、重试率和熔断次数

稳定性策略不是写完就结束。建议每月***小复盘，重点看三类指标：错误率、重试成功率、熔断触发次数。错误率看哪类失败最多；重试成功率看重试是否真的能救回请求；熔断次数看故障是偶发还是持续。三类指标结合看，才能判断当前策略是过松还是过紧。

复盘时不要只看平均值，而要看分布和趋势。比如超时率整体不高，但集中在每天下午三点，说明是高峰期资源紧张；重试成功率整体不错，但某类任务几乎每次都要重试两次才成功，说明初始配置可能有问题。把指标拆到任务类型和时间段上，才能找到真正的优化点。

月度复盘建议：
 
1. 各类错误码的触发次数和占比是否变化
2. 重试成功率是否稳定，哪类任务重试成本最高
3. 熔断触发次数和持续时间是否异常
4. 429 触发是否集中在特定任务或时段
5. 告警响应是否及时，是否有告警无人处理

• 错误率下降不一定是变好，也可能是告警被静默了。
• 重试率上升要警惕，它往往先于故障率上升出现。
• 复盘结论要落到具体配置变更，不要停留在“下个月注意”。

✅ 十一、结语：稳定性让 API中转站 从能用变成可依赖

Codex 接入 API中转站 只是第一步，真正决定团队敢不敢把它放进关键流程的是稳定性。错误分类让失败可理解，超时设置让等待有边界，重试退避让恢复有节奏，熔断降级让故障不扩散。把这些契约按任务拆开，团队才能在故障发生时从容应对，而不是手忙脚乱地改配置。

落地时可以从一个很小的动作开始：先给每类错误定义处理方式，再设三层超时和带退避的重试，最后用故障演练验证规则真的生效。等这套机制跑稳以后，再逐步接入告警值班、熔断降级、月度复盘。这样，Codex 不只是偶尔能用的工具，而会变成项目里可预期、可恢复、可依赖的基础设施。