浏览 AI 使用教程
操作教程

Codex排查API故障怎么做:客户端、网络、网关和上游分层检查

用Codex排查API故障时保存原始状态码和脱敏响应,以最小请求逐层检查客户端、网络、网关与上游,修复后复测真实任务。

Codex项目开发与自动化工作流主视觉

先看重点:快速结论

  1. 提供 PowerShell 7 最小 Responses 请求及状态、耗时、请求 ID 记录。
  2. 命令行请求成功只证明该请求链路,仍需回到 Codex 原任务复测。
本文目录 · 跳到当前步骤

Codex 报 401、404 或超时,先保留原错误,不要同时换 Key、模型、地址和网络。一次只改一个变量,才能判断哪一项有效。本页示范第三方 Responses 兼容 API 的排查;官方账号登录失败应走对应登录教程,不能套用第三方 Key。

先确认这条请求真的对应客户端

从服务当前文档取得最终 Responses URL、准确模型 ID 和认证方式。下面请求只适用于使用 Bearer Key 的 Responses 服务,可能产生一次调用费用。URL 必须是完整请求地址,例如服务确认的 /v1/responses;它不是浏览器登录页,也不是可以再自动拼后缀的 Base URL。

在本地终端按服务提供的真实值设置 TROUBLESHOOT_URL、TROUBLESHOOT_MODEL、TROUBLESHOOT_KEY。凭证只留在本地环境,不贴入文章、截图或给 Codex 的日志。确认客户端实际使用的地址、协议和模型与这次请求一致;CC Switch 路由模式还应记录本机代理是否参与。

没有可用账号时,先用本地订单 API 教学服务学习状态码和重复请求;它不验证任何真实供应商。

PowerShell 7 的最小请求

在 PowerShell 7 执行以下脚本。Windows PowerShell 5.1 没有这里使用的 SkipHttpErrorCheck 参数。

powershell
if ($PSVersionTable.PSVersion.Major -lt 7) { throw "请使用 PowerShell 7" }
foreach ($name in @("TROUBLESHOOT_URL", "TROUBLESHOOT_MODEL", "TROUBLESHOOT_KEY")) {
  if ([string]::IsNullOrWhiteSpace([Environment]::GetEnvironmentVariable($name))) {
    throw "缺少本地环境变量:$name"
  }
}
$target = [uri]$env:TROUBLESHOOT_URL
if ($target.Scheme -ne "https" -or $target.UserInfo -or $target.Query) {
  throw "请提供不含凭证和查询参数的完整 HTTPS API URL"
}
$started = [DateTimeOffset]::UtcNow.ToString("o")
$timer = [Diagnostics.Stopwatch]::StartNew()
$body = @{
  model = $env:TROUBLESHOOT_MODEL
  input = "Reply with OK."
  stream = $false
} | ConvertTo-Json -Compress
try {
  $response = Invoke-WebRequest -Uri $target -Method Post -TimeoutSec 60 -SkipHttpErrorCheck -ContentType "application/json" -Headers @{Authorization = "Bearer " + $env:TROUBLESHOOT_KEY} -Body $body
  $timer.Stop()
  [pscustomobject]@{
    startedUtc = $started
    host = $target.Host
    path = $target.AbsolutePath
    status = [int]$response.StatusCode
    elapsedMs = $timer.ElapsedMilliseconds
    requestId = [string]($response.Headers["x-request-id"] -join ",")
    retryAfter = [string]($response.Headers["Retry-After"] -join ",")
  } | ConvertTo-Json | Set-Content -LiteralPath incident-summary.json -Encoding utf8
  $response.Content | Set-Content -LiteralPath incident-response.txt -Encoding utf8
  Get-Content -LiteralPath incident-summary.json
} catch {
  $timer.Stop()
  [pscustomobject]@{
    startedUtc = $started
    host = $target.Host
    path = $target.AbsolutePath
    httpResponseRecorded = $false
    elapsedMs = $timer.ElapsedMilliseconds
    exceptionType = $_.Exception.GetType().FullName
  } | ConvertTo-Json | Set-Content -LiteralPath incident-summary.json -Encoding utf8
  Get-Content -LiteralPath incident-summary.json
  throw
}

脚本不输出认证头。响应正文仍可能包含服务端诊断或回显,先在本地查看并脱敏,再交给 Codex。不要把 catch 分支写成状态码 500:它表示脚本没记录到 HTTP 响应,可能是 DNS、TLS、代理、连接或请求超时;应保留本地异常原文进一步定位。若本地写入文件也失败,应先处理文件权限,不能误归因于网络。

四层证据怎么对应

层 本轮证据 下一项检查
客户端 实际 URL、模型、协议、配置来源和时间 与最小请求是否相同;是否仍读旧配置
网络与 TLS HTTP 响应有无、异常类型与本地错误 域名解析、证书、代理和目标端口,保留具体错误
网关 状态、响应体、网关请求 ID 查同一 ID 是否收到请求及转发到哪个上游
上游 网关关联到的上游 ID、错误、耗时 判定限流、认证、模型权限或处理故障

请求 ID 的头名因服务不同而异。x-request-id 为空不能证明没经过网关;按该服务文档找关联字段。如果没有后台日志访问权,报告应停在“客户端已收到某响应,上游原因待服务方核查”。

例如网关对 req-42 记录 504,上游应用在 35 秒后才完成,支持“客户端超时早于应用完成”;只看到网页显示 Nginx 或应用没搜到 ID,则不够证明具体失败层。完整日志见日志分析案例。

修复后复测同一任务

401 优先核对认证方式、Key 归属与状态;404 要结合错误体区分最终路径、模型或资源;429 需区分频率和额度,不盲目持续重试。最小请求返回 200 后,仍要回到原 Codex 客户端做同一个小任务,比较流式、工具调用和上下文差异。

给 Codex 的最终任务应明确:只读脱敏证据,先说明确认到哪一层、缺什么材料、建议改哪一个变量。未经证据确认,不应重装、重启整套服务或推荐购买额度。

资料来源

下一步

继续阅读与你当前问题相关的教程: