API 排错与安全

先 cURL，后客户端

先保留现有客户端和密钥，用最小请求建立一组可比较的结果。这样可以判断问题出在 API、协议、客户端还是本地网络。

1. 记录：保存 UTC 时间、客户端版本、模型、协议、完整错误消息和已脱敏 URL。
2. 最小请求：发送非流式 cURL，只保留模型和一条文字输入，去掉推理强度、工具和结构化输出。
3. 对比：cURL 失败时按 API 状态码处理；cURL 成功而客户端失败时，检查 provider、路径拼接、环境变量和代理。
4. 恢复参数：文字请求成功后，再逐项加入流式、结构化输出和工具调用。

最小请求

-i 会同时输出响应头和响应体，状态码与 X-Request-ID 都能保留下来。请把客户端请求 ID 改成本次排错使用的唯一值。

curl -i --max-time 60 https://api.khaix.net/v1/responses \
  -H "Authorization: Bearer sk-请替换为你的密钥" \
  -H "Content-Type: application/json" \
  -H "X-Client-Request-ID: diag-20260717-001" \
  -d '{
    "model": "gpt-5.6-sol",
    "input": "请只回复：连接成功"
  }'

客户端使用 Chat Completions 时，用同一密钥和模型测试对应协议：

curl -i --max-time 60 https://api.khaix.net/v1/chat/completions \
  -H "Authorization: Bearer sk-请替换为你的密钥" \
  -H "Content-Type: application/json" \
  -H "X-Client-Request-ID: diag-20260717-002" \
  -d '{
    "model": "gpt-5.6-sol",
    "messages": [
      {"role": "user", "content": "请只回复：连接成功"}
    ]
  }'

返回 HTTP 200、响应体有文字结果，并且控制台能查到对应记录，说明这条协议链路正常。模型 ID 可通过 GET https://api.khaix.net/v1/models 或控制台实时列表确认。

HTTP 状态码

400 或 422：请求格式错误

• Responses 的请求体使用 input，Chat Completions 使用 messages。
• 暂时移除推理强度、工具和结构化输出，只保留模型与一条文字输入。
• 检查 JSON 引号、逗号、字段类型，以及客户端自动加入的专有参数。
• 错误中出现未知字段时，核对 provider 协议与最终 endpoint。

401：认证失败

• 检查 API Key 是否完整，尤其是前后空格、换行和日志工具截断。
• OpenAI 兼容请求的认证头应为 Authorization: Bearer YOUR_API_KEY。
• 配置文件和环境变量应放在客户端实际运行的用户、容器、WSL 或远程主机中。
• 请求仍发往 api.openai.com，说明自定义 Base URL 没有生效。

403：权限不足

这通常表示密钥有效，但账户、分组或模型没有调用权限。检查密钥作用域、模型实时状态和控制台记录；重复创建同类密钥不会改变权限。

404：请求路径不存在

先查看客户端实际请求的 URL，常见错误是 /v1/v1、/responses/responses，或把完整 endpoint 填进 Base URL。Responses 的最终路径是 /v1/responses，Chat Completions 是 /v1/chat/completions。

413：请求体过大

当前网关请求体上限为 25 MB。缩短对话历史，减少内嵌文本和附件数据后重试；增加客户端超时时间对此无效。

429：额度或限流

检查账户余额、密钥额度、分组限流和控制台记录。额度正常时，用带随机抖动的指数退避重试，避免并发重放相同请求。问题持续时请保留请求 ID 和 UTC 时间。

500、502 或 503：服务链路异常

用同一模型发送最小非流式请求。多个客户端同时失败时，带上请求时间、模型和请求 ID 联系支持；只有一个客户端失败时，先检查它的协议、附加字段和本地代理。

流式与超时

非流式请求成功后，用 -N 关闭 cURL 输出缓冲，观察 SSE 能否持续到正常结束：

curl -N --max-time 180 https://api.khaix.net/v1/responses \
  -H "Authorization: Bearer sk-请替换为你的密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-sol",
    "input": "分五点说明如何设计 API 重试策略",
    "stream": true
  }'

• cURL 正常，客户端断流：检查客户端的 SSE 解析、读取超时，以及是否按普通 JSON 等待完整响应。
• 经过代理才断流：检查反向代理缓冲、空闲超时、连接复用和出口 IP 切换。
• 固定时长后断开：通常是客户端、网关或企业代理触发了超时。
• 流内返回错误：初始 HTTP 200 不能代表整段流成功，请记录最后一个完整事件及其错误字段。

两个请求 ID

请求 ID 只用于追踪，不放 API Key、Prompt、完整响应或个人信息。可以使用 UUID，也可以使用“环境 + 日期 + 随机串”。同一逻辑请求重试时是否复用客户端 ID，由业务的幂等和日志策略决定。

cURL 使用 -i 查看响应头；SDK 可读取原始响应或异常对象中的 headers。客户端不显示响应头时，再记录控制台调用记录中的对应标识。

联系支持时请附上

• 时间：请求发生的 UTC 时间和本地时区，精确到分钟。
• 追踪：X-Request-ID、X-Client-Request-ID 和控制台记录标识。
• 环境：客户端或 SDK 名称、精确版本、操作系统以及是否经过 WSL、容器或远程主机。
• 请求：模型 ID、协议、是否流式，以及已脱敏的实际请求 URL。
• 错误：HTTP 状态码、完整错误消息和最后一个流式事件。
• 对照：最小 cURL 是否成功，问题是否只出现在某个客户端、流式或工具调用。

安全注意事项

密钥安全

• 应用、环境和团队分别使用独立密钥；怀疑泄露时立即撤销并轮换。
• 密钥放在环境变量、系统钥匙串或部署平台 Secret 中，不提交到仓库。
• 浏览器前端、公开脚本和可分发客户端不应包含长期密钥。
• 日志应默认隐藏 Authorization header 和认证配置。

执行安全

• 编码 Agent 的文件修改、命令执行、联网和外部工具权限建议保留逐项确认。
• 不可信项目中应保持 --yolo、YOLO Mode 和全量 Auto-Approve 关闭。
• 高风险任务使用低权限账户、容器或虚拟机，并限制工作目录和凭据可见范围。
• 流式断开或客户端重试前，先确认工具是否已经执行。

代理安全

• 本地协议转换器、调试代理和未认证端口只在受控网络中开放。
• 企业代理和自建反向代理需要验证 TLS、限制管理端口，并关闭 Authorization 与正文记录。
• 明确设置代理缓冲、最大请求体、连接和空闲超时；证书问题应修复信任链，而非关闭 TLS 校验。
• 排错结束后，移除临时抓包证书、全局代理和包含敏感数据的详细日志。

数据安全

• Prompt 和模型响应会在请求期间经 KHaiXAPI 与对应上游处理，请移除与业务无关的凭据和个人信息。
• KHaiXAPI 不将 Prompt 与模型响应写入业务存储；调用、计费元数据和上游处理边界以隐私政策为准。
• 第三方客户端可能自行保存会话、遥测或日志，使用前请检查其数据设置和存储位置。
• 生产系统需要对输入和输出做权限控制、内容校验、审计和保留期限管理。