DevRouter

Appearance

常见问题 ​

排查问题时按顺序检查：客户端类型、Base URL、API Key、模型名、分组权限、网络状态。大多数接入错误都来自 Base URL 与协议不匹配，或 API Key 没有关联可用分组。

先按这个顺序检查 ​

1. 客户端类型确认当前工具是 OpenAI 兼容还是 Claude/Anthropic 兼容。
2. Base URLOpenAI 兼容用 https://devrouter.dev/v1；Claude/Anthropic 兼容用 https://devrouter.dev。
3. API Key确认 Key 完整复制、没有空格换行、没有被禁用。
4. 模型名从控制台模型广场完整复制，大小写和后缀都要一致。
5. 分组权限确认这把 Key 已关联可用分组，并且分组允许调用该模型。
6. 网络状态检查代理、DNS、终端环境变量和客户端缓存。

状态码速查 ​

现象优先检查
401API Key 是否填写、是否多复制空格、认证头是否正确
403API Key 是否分配到可用分组
404Base URL 是否写错，Claude/Anthropic 兼容客户端是否误填 /v1
429请求频率、日限额或上游限流
503分组账号可用性、并发占用、客户端限制
模型不存在模型名是否完整复制，协议和模型是否匹配

调用失败时怎么验证 ​

先用最短请求验证，不要一开始就跑长上下文或复杂任务。

OpenAI 兼容客户端：

bash
curl https://devrouter.dev/v1/chat/completions \
  -H "Authorization: Bearer sk-xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "替换为控制台中的模型名",
    "messages": [{"role": "user", "content": "Reply exactly ok"}]
  }'

Claude/Anthropic 兼容客户端：

bash
curl https://devrouter.dev/v1/messages \
  -H "x-api-key: sk-xxxx" \
  -H "Content-Type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "替换为控制台中的模型名",
    "max_tokens": 32,
    "messages": [{"role": "user", "content": "Reply exactly ok"}]
  }'

联系支持前准备什么 ​

请先整理下面信息，方便快速定位：

信息示例
客户端Cherry Studio / Codex / Claude Code
Base URLhttps://devrouter.dev/v1 或 https://devrouter.dev
模型名控制台中复制的完整模型名
错误时间具体日期和时间
错误信息HTTP 状态码、客户端报错、request id
排查结果已确认 Key 分组、模型权限、网络状态

不要发送完整 API Key。需要核对时，只提供 Key 的备注名或掩码后几位。

API Key 为什么只能看一次完整值 ​

完整 Key 通常只在创建成功时展示一次，之后列表或详情页只显示掩码。这是为了避免浏览器、截图或共享屏幕泄露可调用凭证。忘记保存时，请删除旧 Key 并重新创建。

Claude/Anthropic 兼容客户端为什么 Base URL 不加 /v1 ​

这类客户端通常会自动请求 /v1/messages。如果 Base URL 已经写成 https://devrouter.dev/v1，最终路径可能变成重复的 /v1/v1/messages 或其他错误路径。

正确写法是：

bash
export ANTHROPIC_BASE_URL="https://devrouter.dev"

OpenAI 兼容客户端则相反，通常需要填写：

bash
export OPENAI_BASE_URL="https://devrouter.dev/v1"

服务端 & 网络连接类错误 ​

502 Upstream service temporarily unavailable ​

上游模型服务暂时不可用，通常是供应商侧临时故障。

建议：稍等片刻后重试；若持续出现，可在控制台切换到其他可用模型或分组。

Unable to connect API (UND_ERR_SOCKET) 或 (ECONNRESET) ​

客户端与 DevRouter 之间的 TCP 连接被意外中断。

常见原因：

  • 本地网络不稳定或代理中断
  • 请求超时后连接被服务端关闭

建议：检查本地网络和代理设置，或尝试缩短单次请求的上下文长度。

Unable to connect API (EAI_AGAIN) ​

DNS 解析失败，客户端无法找到 DevRouter 服务器地址。

建议：检查网络连接是否正常，或尝试切换 DNS 服务器（如 8.8.8.8）。

账号 & 并发类错误 ​

503 Service Unavailable 或 503 No available accounts ​

当前分组下没有可用账号，通常是该分组账号全部处于并发占用或暂停状态。

建议：稍后重试，或在控制台切换到其他分组。

429 Upstream rate limit exceeded, please retry later ​

请求频率超出上游模型服务的限制。

建议：降低请求频率，或切换到并发容量更高的分组。

认证 & 权限类错误 ​

401 API key is required in Authorization header ​

请求未携带 API Key，或认证头格式错误。

OpenAI 兼容请求应使用：

txt
Authorization: Bearer sk-xxxx

Claude/Anthropic 兼容请求应使用：

txt
x-api-key: sk-xxxx

同时检查 API Key 是否：

  • 完整复制，无多余空格或换行
  • 未被禁用或删除

403 API Key is not assigned to any group and cannot be used ​

该 API Key 尚未分配到任何分组，无法使用。

建议：前往 DevRouter 控制台 的 API密钥 页面，确认该 Key 已关联到可用分组。

429 API Key 日限额已用完 ​

当日请求额度已耗尽。

建议：等待次日额度重置，或在控制台升级套餐 / 切换额度更高的 Key。

客户端 & 特定环境限制 ​

503 No available accounts: this group only allows Claude Code clients ​

所选分组仅限 Claude Code 客户端访问，其他客户端（如 Cherry Studio、curl 等）会被拒绝。

建议：在控制台切换到支持通用客户端的分组，或在 Claude Code 中使用该分组对应的 Key。

其他常见问题 ​

返回 404 ​

通常是 Base URL 或路径拼接错误。

客户端类型推荐填写
OpenAI 兼容客户端https://devrouter.dev/v1
Claude/Anthropic 兼容客户端https://devrouter.dev
手写 curl使用完整接口路径

如果客户端自动拼接 /v1/messages，就不要在配置中重复填写完整路径。

提示模型不存在 ​

模型名必须与 DevRouter 控制台完全一致。常见问题包括：

  • 大小写不一致
  • 少写版本后缀
  • 在 OpenAI 兼容客户端中填写了不可用模型
  • 当前 API Key 没有该模型权限