连接故障排查
先做四项检查
- 在 API 密钥 确认密钥未禁用、未过期，并已分配分组。
- 在控制台确认余额和账户状态正常。
- 重新打开“使用配置”，与本机当前配置逐项对照。
- 完全退出客户端，从已设置环境变量的终端重新启动。
按状态码处理
| 状态或现象 | 常见原因 | 处理方式 |
|---|---|---|
401 Unauthorized | 密钥错误、缺失或未被进程读取 | 重新复制密钥并重启客户端 |
403 Forbidden | 权限、分组或 IP 限制不匹配 | 检查分组和密钥安全限制 |
404 Not Found | Base URL 或接口路径错误 | 使用“使用配置”生成的完整地址 |
429 Too Many Requests | 速率、并发或额度限制 | 降低并发，等待后重试并检查额度 |
5xx | 临时上游或网关错误 | 短暂等待后有限重试，记录发生时间 |
| 请求超时 | 网络不通、流式读取超时或任务过长 | 先用短请求验证，再检查客户端超时设置 |
截图待补充：客户端错误示例
建议文件：docs/public/images/support/client-error.webp。放置一张已脱敏的典型认证或连接错误截图，并保留状态码与请求 ID。
配置未生效
在同一个终端中确认环境变量已经设置，再从该终端启动客户端。IDE、桌面应用和系统服务不会自动继承另一个终端窗口中的变量。
如果同时存在系统级、用户级和项目级配置，客户端可能优先读取更具体的配置文件。临时移走旧配置前先做好备份。
收集可安全分享的信息
- 问题发生的准确时间和时区。
- 客户端名称、版本和操作系统。
- 使用的分组和模型名称。
- HTTP 状态码、请求 ID 和脱敏后的错误文本。
- 是否使用代理、容器或远程开发环境。
必须脱敏
分享日志前删除 API 密钥、Authorization 请求头、Cookie、兑换码以及任何个人信息。