API 故障排查
先收集四项信息
- 使用的工具、客户端或代码示例；如果知道，再补充接口类型：Chat、Responses 或 Anthropic；
- 本说明站模型清单中的精确模型 ID；
- HTTP 状态码和脱敏后的错误正文；
- 控制台左侧“使用日志”、发生时间和扣费结果。
不要在截图或日志中保留完整密钥、Authorization 请求头、Cookie 或用户数据。
按现象快速定位
| 现象 | 优先查看 |
|---|---|
| Key 填了仍返回 401 | 401 与 403：认证和权限 |
| 有余额但返回 403 | 401 与 403：认证和权限 |
| model not found、模型不存在或返回 404 | 400 与 404：请求、路径和模型 |
| Claude Code 连不上 | 客户端与本地环境 和 Claude Code 接入 |
| Codex 配置后没有响应 | Codex 安装与使用，再看“使用日志” |
| VS Code、Cline 或 Continue 连接失败 | 客户端与本地环境 和 IDE 集成 |
| 其他第三方客户端连接失败 | 第三方客户端接入 和 API 快速开始 |
| 扣费、余额或订单异常 | 注册、计费与充值 |
如果不确定从哪里开始，先收集上面的四项信息，再检查 Base URL、API 密钥、模型 ID 和客户端接口类型。
401 与 403：认证和权限
| 状态码 | 常见原因 | 处理 |
|---|---|---|
| 401 | 密钥缺失、错误、过期或已撤销 | 检查环境变量和密钥状态；不要把密钥发给他人 |
| 403 | 密钥分组或权限不含目标模型 | 核对密钥权限、分组和模型；必要时创建新的独立低额度密钥 |
不要用账号登录密码替代 API 密钥，也不要为排除 403 而把现有密钥直接扩大到无限额、全模型权限。
400 与 404：请求、路径和模型
| 状态码 | 常见原因 | 处理 |
|---|---|---|
| 400 | 请求格式、参数或接口类型错误 | 核对 Chat、Responses 或 Anthropic 类型、JSON 和必填字段 |
| 404 | 路径或模型不存在 | 从本说明站模型清单重新复制精确模型 ID，不猜接口路径 |
Chat 模型不能自动替代 Responses 模型，Anthropic Messages 也不能直接照抄 Chat Completions 的请求格式。Base URL 是否包含 /v1 取决于客户端输入规则；不要在服务地址和客户端自动拼接中重复添加。
413、429、500 与 529：大小、额度和上游
| 状态码 | 含义 | 处理 |
|---|---|---|
| 413 | 请求过大 | 减少文件和上下文，Claude Code 可考虑 /compact |
| 429 | 速率或额度限制 | 停止重试，查看余额、限速和恢复时间 |
| 500 | 服务内部错误 | 保存请求时间和请求 ID，稍后重试 |
| 529 | 上游过载 | 降低并发、等待后再逐步恢复 |
多个模型同时出现 500 或 529 时先查看公告。连续快速重试会放大限速或上游压力，应降低并发并间隔测试。
客户端与本地环境
找不到 claude
- 确认 Node.js 为当前 LTS；
- 重新运行官方包安装命令；
- 打开新终端，执行
claude --version； - 检查 npm 全局可执行目录是否在
PATH。
Windows 还需要按 Claude Code 当前官方要求安装 Git for Windows，并确认 Git Bash 路径可访问。不要为了运行一个工具永久放宽整个系统的脚本策略。
Windows 安装故障
提示"无法运行脚本"
以管理员身份打开 PowerShell 执行：
powershell
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser -Force然后重新运行安装命令。
提示"不支持的国家"
关机重启电脑。仍不行请参考：
https://blog.csdn.net/qq_35376047/article/details/150064785
提示需要安装 Git
下载安装 https://git-scm.com/downloads/win 后重启电脑，再重新运行安装命令。
模型更新后不可用
先更新客户端，再从本说明站模型清单复制当前 ID。Chat 模型不能自动替代 Responses 模型；接口类型不匹配时，换模型名称也不能解决。
第三方客户端连接失败
确认客户端实际使用 Chat Completions、Responses 还是 Anthropic Messages；分别核对 Base URL、是否由客户端自动补 /v1、模型 ID 和该客户端的独立密钥。可先参考代码调用示例确认请求格式，再排查客户端特有设置。
提示：API test failed
历史问题说明
这是旧版一键安装脚本的测试提示，当前版本已优化。如果仍看到此提示，直接输入 y 继续即可。
问题上报
提供脱敏请求、状态码、请求 ID、时间、模型 ID、接口类型和客户端版本。
遇到无法自行解决的问题，可加入 QQ 群 727366519（点击链接加入群聊）反馈，按上面的清单提供脱敏信息即可。