故障排查
按错误码定位。三类客户端都用这份；客户端特有问题在各自文档的「常见错误」节里单列。
鉴权错误
| 现象 |
处理 |
401 invalid_api_key |
Key 填错；或填了 sk-...**** 这种脱敏预览值；或 Key 已被禁用。回 前置准备 第 2 步重新创建 / 重置 Key。 |
401 + 没改过 Key |
客户端可能缓存了旧值。关掉客户端重开，或检查环境变量（OPENAI_API_KEY / ANTHROPIC_AUTH_TOKEN）是否被 shell rc 覆盖。 |
权限 / 余额错误
| 现象 |
处理 |
403 no_active_balance |
当前用户没有有效余额块（可能没充值、或所有充值块都已用完 / 过期）。让管理员发放余额。 |
403 model not allowed |
当前用户等级没有开启这个模型。去控制台首页「可用模型与价格」核对，或让管理员调整等级 / 模型矩阵。 |
端点错误
| 现象 |
处理 |
404 |
base_url 写错。复查 接入地址速查 —— 关键差异是要不要 /v1。 |
503 no upstream endpoint configured |
该模型没有可用上游端点。常见原因：(a) 客户端识别不对（Claude 模型只允许真实 Claude Code CLI 调用；详见 Claude Code 接入）；(b) 通道整体不可用，全部账号已限流；(c) 后台没给这个模型配端点。 |
429 / rate_limit_error |
用户级 RPM 上限触发，或当前 endpoint 在冷却。先减并发，或等几秒重试。后台「上游路由」tab 可看冷却倒计时。 |
502 Bad Gateway / 偶发 5xx |
上游端点临时不稳，网关会自动 fallback 到下一个候选端点并标失败计数。短暂出现属正常；持续 5xx 联系管理员看后台「端点健康」面板。 |
配置生效
| 现象 |
处理 |
| 改完配置仍走旧值 |
大多数 CLI 启动时一次性读配置文件。关闭当前终端 / CLI 进程，重新打开后再试。 |
| 模型列表里看不到刚开的模型 |
后台模型缓存 3 分钟自动刷一次；要立刻生效让管理员在「模型价格」tab 操作或重启实例。 |
计费 / 用量
| 现象 |
处理 |
| 同一 Key 同模型扣费比预期高 |
检查是不是触发了 200K 分档（sonnet-4-6 / opus-4-6 / opus-4-7 整段 prompt ≥ 200K token 后单价翻倍）。后台「请求日志」点行查 detail。 |
| Prompt cache 命中率低 |
(a) Claude Code 切到 GPT/Gemini 时没加 CLAUDE_CODE_ATTRIBUTION_HEADER=0，header 变了导致 cache key 不稳；(b) 客户端版本变了 system prompt 变了。 |
| 余额扣得对不上账 |
找客服 / 管理员，附上请求 ID（在「请求日志」tab 能搜）。每笔请求都有审计 trail，可逐条复算。 |
排查工具
- 请求日志搜索：
/admin/tab/logs 按 request_id / 用户 / 模型 / 错误关键字搜
- 运营概览：
/admin/tab/overview 顶部「需要立即处理」会列出失败端点 / 错误率异常 / 余额告急用户
- 端点冷却 / 测试：
/admin/tab/routing 行级「测试」「冷却 5min」按钮，临时摘除 flaky 端点
