ROVOAPI
开始使用
Back to docs

错误排解

常见问题排查指南

错误排解

特别说明： AI 工具迭代速度极快。遇到报错时，建议先将 Claude Code、Codex CLI、CC-Switch 等工具更新到最新版本，新版通常已修复已知问题，也能避免旧版本特有的奇怪报错。

Base URL 速查

Base URL 加不加 /v1 是最高频的错误来源。

| 工具 | Base URL 格式 | |------|--------------| | Claude（Anthropic Messages 协议） | https://api.rovoapi.com | | Codex / OpenAI（Responses 协议） | https://api.rovoapi.com | | OpenAI SDK（Chat Completions） | https://api.rovoapi.com/v1 |

外接前 5 项检查清单

| 项目 | 确认内容 | |------|---------| | 分组 | API Key 属于 Claude 分组还是 OpenAI 分组 | | 协议 | 客户端走 Anthropic Messages 还是 OpenAI Responses | | Base URL | Claude 不带 /v1，OpenAI 系列带 /v1 | | 请求头 | 外接场景需要补对应 User-Agent | | 模型 | 有些分组允许留空，有些必须填写准确模型 ID |

User-Agent 速查表

外接场景需要设置正确的 User-Agent：

| 场景 | User-Agent | |------|-----------| | Claude 外接 | claude-cli/2.0.76 (external, cli) | | Codex 外接 | codex_cli_rs/0.77.0 (Windows 10.0.26100; x86_64) WindowsTerminal | | 国产模型外接 | Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:149.0) Gecko/20100101 Firefox/149.0 |

常见错误

401 Unauthorized / Invalid API Key

原因： API Key 错误、缺失，或 ANTHROPIC_BASE_URL 未配置导致请求打到官方端点。

排查：

  1. 确认 settings.json 中已正确配置 Base URL 和 API Key
  2. 检查系统环境变量是否残留旧配置（ANTHROPIC_BASE_URL、ANTHROPIC_API_KEY）
  3. 检查 ~/.claude.json 是否有 OAuth 令牌残留（claude auth logout 清除）
  4. 从控制台重新复制 Key，避免复制时混入不可见字符

检测不可见字符：

echo "$ANTHROPIC_API_KEY" | cat -A
# 正常：行尾只有 $
# 异常：出现 ^M$ 或其他多余字符

403 block / 403 Forbidden

排查顺序：

  1. 确认令牌分组是否匹配当前模型类型
  2. 确认 Base URL 是否带错 /v1
  3. 确认 User-Agent 是否缺失或填错
  4. 确认客户端是否真正将 Header 发出去了
  5. 确认 Authorization 仍是 Bearer sk-xxx 格式

429 Too Many Requests

两种子类型：

  • rate_limit_error — 短时间请求过于频繁，等待后自动恢复
  • insufficient_quota — 当月额度已耗尽，需充值

判断方法：前往控制台查看余额。

Connection error.

现象： 请求未到达服务器即失败，重试无效。

排查：

  1. 执行 ping api.rovoapi.com 检查连通性
  2. 有回包 → 排查代理配置；超时 → 切换网络（换 Wi-Fi/关闭代理/切换代理节点/手机热点）
  3. 确认代理软件已开启系统代理或 TUN 模式
  4. 网络恢复后重新执行 claude

Request timed out.

两种情况：

  • 情况 A — 网络延迟： 参考上面 Connection error 的排查步骤
  • 情况 B — 上下文过长： 会话积累 token 过多，执行 /clear 或 /compact

400 Bad Request（非内容原因）

原因： Claude Code 自动附加实验性 Beta 请求头（anthropic-beta），部分上游不支持。

修复： 在 settings.json 的 env 中添加：

"CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1"

413 Request Entity Too Large

现象： API Error: 413 Request Entity Too Large

修复： 执行 /clear 或 /compact。

503 model_not_found

原因： 所选模型当前不可用。

修复： 使用 /model 命令切换到其他可用模型。

Unable to connect to Anthropic services（首次启动）

原因： hasCompletedOnboarding 字段缺失，Onboarding 探测绕过中转直连官方端点。

修复： 在 ~/.claude.json 最外层添加：

"hasCompletedOnboarding": true

WebFetch 联网失效

原因： Claude Code 抓取页面前向 claude.ai 发预检请求，国内网络拦截 claude.ai 导致预检失败。

修复： 在 settings.json 中添加：

"skipWebFetchPreflight": true

Permission denied

三种独立原因：

  • 系统层权限不足： chmod 644（文件）或 chmod 755（目录）
  • Claude Code 权限设置： 按 Cmd+Shift+P（macOS）或 Ctrl+Shift+P（Win/Linux）搜索 Claude: Manage Permissions，将对应规则改为"询问"或"允许"
  • .claudeignore 规则误匹配： 检查 .claudeignore 是否有 glob 规则误匹配

Command timed out after 2m 0.0s

原因： Claude Code 等待 shell 命令返回超时，与 API 请求无关。

修复： 手动在终端执行对应命令查看卡在哪里。

API Error: response exceeded the 32000

修复： 在 settings.json 的 env 中设置：

"CLAUDE_CODE_MAX_OUTPUT_TOKENS": "32000"

400 Invalid model name

原因： Opus 并发配额不足。

修复： 稍等片刻后重试即可。

500 / Overloaded

原因： 服务端过载或临时故障。

修复： 查看 rovoapi.com/status 确认服务状态，稍后重试。

skipAutoPermissionPrompt 导致 Plan 模式失效

原因： 跳过自动权限提示后，Plan 模式执行阶段无法继续推进。

修复： 删除 ~/.claude/settings.json 中的 "skipAutoPermissionPrompt": true 字段。

旧版 Claude Code 清理重装

先备份配置，再清理旧包：

# Mac/Linux
if [ -d ~/.claude ]; then cp -r ~/.claude ~/.claude.backup; fi
npm uninstall -g @anthropic-ai/claude-code

清理后使用原生脚本重新安装：

# Mac/Linux/WSL
curl -fsSL https://claude.ai/install.sh | bash

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

通用排障流程

  1. 确认令牌分组、Base URL、User-Agent 三项是否匹配
  2. 检查系统环境变量是否残留旧配置（Win+R → sysdm.cpl，或查看 ~/.zshrc）
  3. 检查 ~/.claude.json 是否有 OAuth 令牌残留（claude auth logout 清除）
  4. 用 CC-Switch 重新写入一次配置，关闭终端窗口重新打开后再试
  5. 如涉及外接场景，确认 5 项检查清单（分组、协议、Base URL、请求头、模型）
CC-Switch 配置管理