> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xrouter.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# 常见问题

> 排查 XRouter 接入中的认证、服务地址、模型名、工具配置和日志定位问题。

遇到接入问题时，先用同一把 Key 请求 `/v1/models`。如果模型列表能返回，说明服务地址和认证大概率可用，再继续排查模型名、请求格式或工具配置。

## 最小排查命令

```bash Terminal theme={null}
curl "https://api.xrouter.dev/v1/models" \
  -H "Authorization: Bearer sk-your-api-key"
```

如果控制台显示了不同 `server_address`，请替换命令中的域名。

## 常见问题

<AccordionGroup>
  <Accordion title="401 或 token invalid">
    确认 API Key 完整保留 `sk-` 前缀，OpenAI 兼容接口使用 `Authorization: Bearer sk-...`。如果你复制的是隐藏后的 Key，请重新查看或创建新 Key。
  </Accordion>

  <Accordion title="403 或 access_denied">
    检查账户状态、Key 状态、Key 额度、模型限制、IP 限制和分组权限。如果配置了 IP 限制，请确认请求出口 IP 在允许列表中。
  </Accordion>

  <Accordion title="模型不存在或无权限">
    从控制台模型页复制模型 ID，再用同一把 Key 请求 `/v1/models`。如果 `/v1/models` 中没有目标模型，说明这把 Key 当前不可用该模型。
  </Accordion>

  <Accordion title="OpenAI SDK 连接失败">
    SDK 的 base URL 应为 `https://api.xrouter.dev/v1`。如果只写到根地址，SDK 可能无法拼接正确路径。
  </Accordion>

  <Accordion title="Claude Code 报认证错误">
    Claude Code 的 `ANTHROPIC_BASE_URL` 应为服务根地址，例如 `https://api.xrouter.dev`，不要追加 `/v1/messages`。
  </Accordion>

  <Accordion title="Codex CLI 弹出 ChatGPT 登录">
    通常说明自定义 provider 没有生效。检查 `~/.codex/config.toml` 中的 `model_provider` 是否指向 XRouter provider，并确认 `XROUTER_API_KEY` 环境变量已设置。
  </Accordion>

  <Accordion title="CC-Switch 切换后没有生效">
    切换 Provider 后重启目标 CLI。Claude Code 通常需要开启新会话；Codex CLI 建议重新打开终端后再启动。
  </Accordion>

  <Accordion title="如何定位失败请求">
    到控制台用量日志按时间、模型或 Key 查找失败请求。日志页可以帮助确认请求是否到达 XRouter、使用了哪个模型、返回了什么错误。
  </Accordion>
</AccordionGroup>

<Note>
  待补图片：用量日志筛选和请求详情界面。截图中需要隐藏真实 prompt、response、Key、用户信息和消费细节。
</Note>