常见问题

401 或 token invalid

确认 API Key 完整保留 sk- 前缀，OpenAI 兼容接口使用 Authorization: Bearer sk-...。如果你复制的是隐藏后的 Key，请重新查看或创建新 Key。

403 或 access_denied

检查账户状态、Key 状态、Key 额度、模型限制、IP 限制和分组权限。如果配置了 IP 限制，请确认请求出口 IP 在允许列表中。

模型不存在或无权限

从控制台模型页复制模型 ID，再用同一把 Key 请求 /v1/models。如果 /v1/models 中没有目标模型，说明这把 Key 当前不可用该模型。

OpenAI SDK 连接失败

SDK 的 base URL 应为 https://api.xrouter.dev/v1。如果只写到根地址，SDK 可能无法拼接正确路径。

Claude Code 报认证错误

Claude Code 的 ANTHROPIC_BASE_URL 应为服务根地址，例如 https://api.xrouter.dev，不要追加 /v1/messages。

Codex CLI 弹出 ChatGPT 登录

通常说明自定义 provider 没有生效。检查 ~/.codex/config.toml 中的 model_provider 是否指向 XRouter provider，并确认 XROUTER_API_KEY 环境变量已设置。

CC-Switch 切换后没有生效

切换 Provider 后重启目标 CLI。Claude Code 通常需要开启新会话；Codex CLI 建议重新打开终端后再启动。

如何定位失败请求

到控制台用量日志按时间、模型或 Key 查找失败请求。日志页可以帮助确认请求是否到达 XRouter、使用了哪个模型、返回了什么错误。

​最小排查命令