排错与安全

排查时只改一项配置，并保留时间、状态码与请求 ID。原则：先用最小 cURL 证明网关可用，再回头查客户端。

推荐顺序

记录：UTC 时间、客户端版本、模型、协议、完整错误、已脱敏 URL。
最小请求：非流式、仅模型 + 一句文字，去掉推理强度 / 工具 / Schema。
对比：cURL 失败按状态码处理；cURL 成功而客户端失败，查路径拼接、环境变量与代理。
恢复：文字稳定后再逐项打开流式、工具与结构化输出。

现象	优先排查
最小 cURL 也失败	密钥、额度、模型、协议、Base URL、网络
cURL 成功，客户端失败	provider、自动拼路径、配置作用域、缓存、代理
非流式成功，流式失败	SSE 解析、代理缓冲、空闲超时
文字成功，工具失败	工具字段、序列化、结果回传、模型能力

最小诊断请求

Responses

curl -i --max-time 60 https://app.helpday.work/v1/responses \
  -H "Authorization: Bearer sk-请替换为你的密钥" \
  -H "Content-Type: application/json" \
  -H "X-Client-Request-ID: diag-yoriday-001" \
  -d '{
    "model": "你的模型名称",
    "input": "请只回复：连接成功"
  }'

Chat Completions

curl -i --max-time 60 https://app.helpday.work/v1/chat/completions \
  -H "Authorization: Bearer sk-请替换为你的密钥" \
  -H "Content-Type: application/json" \
  -H "X-Client-Request-ID: diag-yoriday-002" \
  -d '{
    "model": "你的模型名称",
    "messages": [
      {"role": "user", "content": "请只回复：连接成功"}
    ]
  }'

HTTP 200、响应有文字，且控制台能查到记录，说明该协议链路正常。模型列表也可对照控制台实时数据。

HTTP 状态码速查

400 / 422：字段不对。Responses 用 input，Chat 用 messages；先去掉额外参数。
401：密钥残缺、空格或未带 Authorization: Bearer；确认 Base URL 真的生效，而不是仍打到官方域名。
403：密钥有效但分组 / 模型无权限。
404：路径错误，常见 /v1/v1 或把完整 endpoint 填进 Base URL。
429：额度或限流；带抖动退避，并核对控制台余额。
5xx：链路异常；多客户端同时失败时带请求 ID 联系支持。

流式与超时

curl -N --max-time 180 https://app.helpday.work/v1/responses \
  -H "Authorization: Bearer sk-请替换为你的密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "你的模型名称",
    "input": "分五点说明 API 重试要注意什么",
    "stream": true
  }'

cURL 正常、客户端断流：查 SSE 解析与读取超时。
仅经代理断流：查缓冲、空闲超时、出口切换。
固定时长断开：多半是客户端、网关或企业代理超时。

断流不等于工具没执行。有副作用的操作要确认幂等，并避免无脑重放。

联系支持时请附上

时间（UTC + 本地时区，精确到分钟）
请求 ID / 控制台记录标识
客户端或 SDK 名称与版本、OS、是否 WSL / 容器
模型、协议、是否流式、已脱敏 URL
完整错误消息；以及最小 cURL 是否成功

邮件：me@helpwork.day。发送前请去掉完整 API Key、Prompt 与敏感正文。

安全注意

按应用 / 环境拆分密钥；怀疑泄露立即撤销轮换。
密钥放环境变量或 Secret 管理，不进仓库与前端包。
Agent 的写文件、执行命令、联网权限默认逐项确认。
本地协议转换器只监听 127.0.0.1，排错结束清理临时代理与详细日志。