错误、限制与重试
集中处理客户端安装、配置、状态码和重试问题。
安装
- 安装后提示命令不存在：关闭并重新打开终端，再确认 npm 全局可执行目录已加入
PATH。 - 使用图形界面：OpenCode 可安装桌面版或运行
opencode web；Kimi Code 可运行kimi web。 - VS Code 插件未读取配置：确认安装的是官方插件，保存配置后完全退出并重新打开 VS Code。
配置与协议
配置中的 Base URL、API Key 和模型名以对应客户端指南为准。
- Codex 使用 OpenAI Responses，Base URL 以
/v1结尾，wire_api为responses。 - Claude 使用 Anthropic Messages，Base URL 不带
/v1；客户端会请求/v1/messages。 - 其他客户端按对应指南填写地址：有的需要
/v1，有的需要完整接口路径或仅域名。 - 按客户端指南填写 API Key。出现认证错误时，检查配置文件、设置界面和环境变量中的 Key 是否冲突。
客户端限制
- Cursor 请明确选择配置的模型进行测试，不要选择
Auto。自定义 Key 用于聊天模型，Tab 补全仍使用内置模型；可用模型及账户限制见 Cursor 官方说明。 - 在 CCSwitch 中启用 Provider 后，打开 Codex 或 Claude Code 发送消息。
- 在客户端的模型、Provider 或 API Key 设置页填写连接信息。菜单位置随版本可能有所变化。
HTTP 状态
| 状态 | 常见原因 | 处理 |
|---|---|---|
400 | 请求正文错误、字段冲突或协议不匹配 | 修正配置或请求，不原样重放 |
401 | API Key 缺失、格式错误或未被客户端读取 | 重新保存 Key 并重启客户端 |
402 | 可用余额不足 | 检查余额并充值 |
403 | Key 无效、账户限制、CIDR、消费或 API 地址限制 | 核对 Key、账户策略和地址 |
404 | Base URL 后缀错误、操作路径错误或模型不存在 | 按协议修正地址并核对公开模型名 |
405 | 当前协议或操作不受支持 | 选择客户端支持的协议与操作 |
413 | 请求正文或文件超过限制 | 缩小输入或文件 |
429 | RPM、并发或账户容量限制 | 逐步延长重试间隔，并限制次数 |
502 / 503 / 504 | 服务暂时不可用或响应超时 | 稍后重试 |
请求失败后重试
超时或断开连接后，原调用仍可能已经完成。重试前：
- 查看请求结果和用量记录，确认请求是否已完成。
400、401等配置错误先按上表修正，再重新发送。429或服务暂时不可用时，逐步延长重试间隔，并设置最大重试次数。
每次重试都是一次新调用，可能产生额外费用。