常见排障
从客户端看到的症状开始，再检查最窄的有用层级。每张卡片都给出可能原因、第一批检查项、有用的 capture phase，以及深入解释所在文档。
请求形态与路由
Section titled “请求形态与路由”客户端看到 404 或 unsupported path
层级: Ingress有用 capture:
inbound_request可能原因
- 客户端没有使用支持的 endpoint。
- 客户端 base URL 多了 `/v1` 或缺少预期 route suffix。
下一步检查
- 使用 `/v1/responses`、`/v1/chat/completions` 或 `/v1/messages`。
- 检查客户端需要的 base URL 是否包含 `/v1`。
- 确认本地代理监听在配置端口。
相关文档
客户端看到 400 invalid_request_error
层级: Ingress validation有用 capture:
inbound_request可能原因
- 入站请求 body 不符合检测出的协议。
- 客户端给当前 endpoint 发送了不支持的 shape。
下一步检查
- 检查请求 path。
- Capture 一次脱敏 inbound request。
- 对照协议指南检查 payload shape。
相关文档
选错了 provider
层级: Routing有用 capture:
provider_request可能原因
- route 顺序或模型 pattern 命中了非预期 route。
- `request_protocol` guard 省略或和预期不一致。
- 请求落到了 default provider fallback。
下一步检查
- 检查 `[[routing.routes]]`。
- 检查 `routing.default_provider_names`。
- 对比实际入站协议和显式 `request_protocol` guard。
相关文档
协议不匹配配置错误
层级: Routing / conversion有用 capture:
provider_request可能原因
- Route 模型命中，但显式 `request_protocol` 与检测出的入站协议不同。
- 选中的 provider protocol 需要未支持的转换 pair。
下一步检查
- 只有 endpoint-specific routing 才设置 `request_protocol`。
- 检查支持的转换 pairs。
- 检查选中 provider 的 protocol。
相关文档
Provider 与上游
Section titled “Provider 与上游”客户端看到 401 / 403 upstream
层级: Provider authentication有用 capture:
provider_request可能原因
- Provider `api_key` 缺失、错误、过期或 scope 不对。
- 上游拒绝了 ProxAI 发出的 provider auth header。
下一步检查
- 检查本地 `[providers.<name>].api_key`。
- 确认 provider protocol 决定 auth header 形态。
- 不要依赖客户端 UI 传真实 key，provider config 应该拥有认证。
相关文档
客户端看到 429 upstream
层级: Upstream status有用 capture:
upstream_response可能原因
- 上游限流或配额耗尽。
- 并发量超过 provider 能力。
下一步检查
- 检查保留的 `Retry-After` 和 rate-limit headers。
- 检查 provider quota。
- 如有必要调低 `[server].max_concurrent_requests`。
相关文档
客户端看到 502 / 503 / 504 upstream_error
层级: Upstream transport / status有用 capture:
upstream_response可能原因
- Provider 返回非 2xx status。
- 上游错误 body 为空、非 JSON 或 shape 未知。
- 网络或 idle-read timeout。
下一步检查
- 检查 provider `base_url`。
- Capture 一次 upstream response。
- 确认上游 endpoint 可达且协议兼容。
相关文档
流开始但一直不完成
层级: Streaming semantics有用 capture:
upstream_response可能原因
- Provider 没有发送协议 terminal event。
- 上游连接仍打开，但语义上已经卡住。
下一步检查
- 对照预期 terminal events。
- 查看 stream outcome logs。
- Capture upstream SSE tail。
相关文档
Tool-call arguments 卡住
层级: Streaming tool-call semantics有用 capture:
upstream_response可能原因
- 上游开始发送 tool arguments，但没有发送匹配的 done event。
- 语义 tool-call timeout 对当前客户端体验来说过高。
下一步检查
- 调整 `[tool_calls].timeout_secs`。
- 检查 provider event sequence。
- Capture upstream SSE tail。
相关文档
客户端收到 malformed streaming event
层级: Translation / response reconstruction有用 capture:
outbound_response可能原因
- Provider stream shape 与选中的 provider protocol 不一致。
- Streaming translation 遇到了未支持的语义事件。
下一步检查
- 检查入站协议与 provider protocol。
- 对照支持的 conversion pairs。
- Capture 一次脱敏 outbound response bytes。
相关文档
配置、文件与错误渲染
Section titled “配置、文件与错误渲染”ProxAI 启动失败
层级: Configuration loading有用 capture:
none可能原因
- `config.toml` 缺少必需 section。
- Provider 条目缺少必填字段。
- Route 引用了未知 provider。
下一步检查
- 对照生成的 `config.example.toml`。
- 检查本地 app 目录。
- 检查 route/provider 名称是否拼错。
相关文档
Captures 没有写入
层级: Local filesystem / capture config有用 capture:
none可能原因
- 对应 phase 开关没有打开。
- 打开的 phase 与你检查的 phase 不同。
- app 目录不是你以为的那个。
下一步检查
- 运行 `proxai capture status`。
- 检查 `[capture]` switches。
- 确认 app 目录位置。
相关文档
客户端期望 JSON 但收到 text
层级: Error rendering有用 capture:
outbound_response可能原因
- `[error_responses].format` 设置为 `text`，这是可读性默认值。
- 客户端期望 OpenAI 风格 JSON error payload。
下一步检查
- 如果客户端要求 JSON，设置 `[error_responses].format = "json"`。
- 检查 outbound response content type。
相关文档