678APIdocs
排查
故障排查
当客户端无法调用、返回异常或消耗异常时，可以按以下顺序排查。
检查 Base URL
OpenAI Compatible 客户端应填写 https://www.678api.com/v1，不要重复添加 /v1/v1 或 /chat/completions。
检查 API Key
确认密钥没有被禁用，复制时没有空格或换行。
检查余额
确认账户有余额或有效订阅额度。
检查模型名
模型名必须是控制台可用模型列表中的名称。
常见问题与解决方案
| 异常现象 | 可能原因 | 解决方案 |
|---|---|---|
| 401 / unauthorized | API Key 错误、被禁用、复制了隐藏空格 | 重新复制 Key；确认 Key 未禁用；新建一个测试 Key；注意不要把 Bearer 前缀重复写入。 |
| 403 / no permission | 账户分组或渠道没有该模型权限 | 到模型列表确认可用模型；切换到账户可用模型；联系管理员确认分组权限。 |
| 404 / model not found | 模型名称填写错误或当前分组不可用 | 从控制台复制完整模型名；检查大小写、短横线、版本号；不要使用客户端默认不存在的模型名。 |
| 429 / rate limited | 并发、频率或渠道限流 | 降低并发；缩短上下文；稍后重试；为不同工具使用不同 API Key 方便定位。 |
| 余额充足但请求失败 | 预扣额度、订阅额度、单次请求上限或模型权限不满足 | 查看钱包余额、订阅状态和用量日志；减少上下文和输出长度后重试。 |
| 请求超时 | 网络不稳定、模型响应慢、上下文过长或本地代理异常 | 先用短问题测试；检查本地代理；换网络；降低 max tokens；关闭不必要的工具调用。 |
| 流式输出中断 | 客户端流式兼容性、网络中断或上游连接被断开 | 关闭 stream 测试；升级客户端；减少输出长度；重试同一模型或切换备用模型。 |
| 一直显示旧配置 | 客户端缓存、环境变量未刷新或 CC Switch 未真正切换 | 重启客户端和终端；检查环境变量；删除旧 provider 后重新添加；确认当前选择的是 678API 配置。 |
| 消耗比预期高 | 上下文太长、重复发送历史消息、开启了 Agent/工具调用 | 清理对话历史；降低上下文长度；关闭自动索引或大范围代码库读取；查看用量日志定位模型和请求。 |
| 模型列表无法刷新 | 客户端没有调用模型列表接口或 Base URL 格式不兼容 | 手动填写模型名；确认 Base URL 是 https://www.678api.com/v1；如客户端要求根地址则填写 https://www.678api.com。 |
快速自检
curl https://www.678api.com/v1/models -H "Authorization: Bearer YOUR_API_KEY"如果模型列表能返回，说明网络和密钥基本正常。若客户端仍失败，优先检查客户端的 Base URL、模型名和本地缓存。