接入文档
常见问题排查
集中排查鉴权失败、余额不足、模型不可用、Base URL 路径、CC Switch、Claude Code、Codex 与调用记录问题。
先按顺序定位：密钥是否有效、钱包是否有余额、模型 ID 是否正确、Base URL 是否符合客户端规则、客户端是否读到了最新配置。
401 鉴权失败
- 确认请求头是
Authorization: Bearer sk-...，Bearer后有空格。 - 确认密钥未被禁用、删除或重新生成。
- 确认客户端没有读到旧的环境变量。
- 参考 鉴权与密钥 检查密钥生命周期。
余额不足或 402
模型不可用或模型不存在
- 从模型广场重新复制模型 ID，注意大小写和版本后缀。
- 检查密钥是否设置了模型白名单。
- 检查密钥所选 API 分组是否允许该模型。
- 参考模型广场和API 分组与价格倍率。
Base URL 是否带 /v1
| 场景 | 正确写法 |
|---|---|
| Claude Code / Anthropic 环境变量 | 不带 /v1 |
| Codex / OpenAI 兼容客户端 | 带 /v1 |
| curl OpenAI Chat Completions | 请求到 {Base URL}/v1/chat/completions |
| Anthropic Messages curl | 请求到 {Base URL}/v1/messages |
路径错误常见表现是 404、连接失败或客户端提示 provider 不可用。
CC Switch 没有拉起或导入后不生效
- 确认本机已安装 CC Switch，并且浏览器允许打开本地应用。
- 重新打开密钥详情页，再执行一次导入。
- 导入后重启终端或客户端。
- 运行 CLI 环境检查，确认当前 shell 能读到配置。
Claude Code 配置不生效
- 检查
~/.claude/settings.json和项目内.claude/settings.json是否同时存在；项目级配置可能覆盖全局配置。 - 确认
ANTHROPIC_BASE_URL不带/v1。 - 确认
ANTHROPIC_AUTH_TOKEN是当前密钥。 - 参见 Claude Code 接入指南。
Codex 配置不生效
- 检查
~/.codex/config.toml是否被当前 Codex 读取。 - 确认
base_url带/v1。 - 确认
OPENAI_API_KEY在当前 shell 中存在。 - 参见 Codex 接入指南。
调用记录看不到
- 确认你查看的是发起调用时的同一个团队。
- 确认请求确实发到了熊猫算力网关，而不是客户端默认服务地址。
- 如果客户端失败在本地配置阶段，可能还没有请求进入网关，因此不会生成调用记录。
- curl 能成功但客户端无记录时，优先检查客户端 Base URL 和环境变量。
仍然无法解决
保留以下信息再联系支持：请求时间、模型 ID、客户端名称、HTTP 状态码、错误码、调用记录中的 request id（如有）。不要发送完整 API 密钥。