常见问题与故障排查
排查认证失败、模型不存在、限流、服务异常和 Base URL 路径问题。
返回 401 或提示认证失败
可能原因：
- API Key 填写错误、已过期或已被撤销。
- API Key 前后包含多余空格。
- 当前工具没有正确读取环境变量或配置文件。
- 服务端要求特定认证方式，而当前工具未正确传递密钥。
处理建议：
- 重新复制 API Key，并确认没有多余空格。
- 检查 Key 是否对当前模型具有访问权限。
- 重新打开终端或客户端，使环境变量生效。
- 不要手动添加引号、
Bearer前缀或其他字符，除非平台明确要求。
返回 404 或模型不存在
可能原因：
- 模型 ID 与服务端提供的 ID 不一致。
- API Base URL 路径错误，例如缺少或重复添加
/v1。 - 客户端自动拼接了接口路径，而填写的地址已经包含完整接口路径。
- Claude Code 桌面版使用的 Model ID 不在客户端允许识别的模型名称范围内。
处理建议：
- 在模型服务平台复制真实模型 ID。
- 确认大小写、连字符、斜杠和组织前缀完全一致。
- Base URL 通常填写到版本层级，例如：
https://api.do.top/v1不要填写完整请求地址，例如：
https://api.do.top/v1/chat/completions或：
https://api.do.top/v1/messages返回 429
表示请求频率或 Token 用量超过限制。
处理建议：
- 降低请求频率。
- 缩短上下文长度。
- 检查账号额度、套餐限制和平台限流规则。
- 稍后重试。
返回 500、连接被拒绝或响应为空
这类问题通常与模型服务端、网关或网络连接有关。
建议依次检查：
- API 地址和端口是否可访问。
- 服务端是否正在运行。
- 当前模型是否支持对应工具需要的接口协议。
- 请求上下文是否过长。
- 是否只有特定模型失败。
- 重试后是否仍稳定复现。
如果需要联系服务提供方，请一并提供发生时间、模型 ID、HTTP 状态码、请求 ID 和 Trace ID；不要提供完整 API Key。
公网 HTTP 地址无法使用
部分桌面软件只允许公网 API 使用 HTTPS。若 HTTP 地址被客户端拦截，请让服务提供方配置 HTTPS，不建议通过关闭安全检查长期绕过。
Base URL 被重复拼接路径
部分客户端会在 Base URL 后自动追加 /chat/completions、/messages 或其他接口路径。
处理建议：
- Base URL 只填写基础地址。
- 不要把完整请求路径填进 Base URL。
- 如果中转服务本身需要特殊路径，请确认客户端最终请求地址是否与服务端路由匹配。