故障排查

先看有没有用量记录

排查接口问题时，先打开 API Hub 的 用量明细。

现象	判断
没有任何记录	请求没有到达优芯，优先检查 Base URL、代理、DNS、请求路径和 Header
有失败记录	请求已到达优芯，根据错误状态、模型、端点继续排查
有成功记录但客户端报错	客户端可能没有正确解析响应，检查流式设置或客户端协议

401 / 认证失败

常见原因：

1. API Key 写错或复制了多余空格。
2. Header 没有写 Bearer。
3. Key 已被禁用或删除。
4. 客户端把 Key 写到了错误字段。

推荐 Header：

Authorization: Bearer sk-your-api-key

Anthropic 兼容客户端也可以使用：

x-api-key: sk-your-api-key

404 / 路径不存在

优先检查 Base URL 是否被重复拼接。

正确示例：

Base URL: https://api.yucpu.com
Path: /v1/messages

错误示例：

https://api.yucpu.com/v1/messages/v1/messages

如果客户端会自动拼接路径，Base URL 不要填完整接口地址。

模型不可用

先到 API Hub 的 渠道状态 页面确认模型名称和分组支持情况。

常见原因：

1. API Key 所在分组不支持该模型。
2. 模型名称写错。
3. 当前渠道临时不可用。
4. 使用了客户端默认模型，但该模型不在当前分组里。

分组限制

部分分组可能限制调用入口。例如 Claude Code 专用分组只允许 /v1/messages。

如果你看到：

This group is restricted to Claude Code clients (/v1/messages only)

请改用 Claude / Anthropic 兼容入口，或切换到支持 OpenAI 兼容接口的分组。

余额或额度不足

如果请求提示余额不足、额度不足或订阅不可用：

1. 检查钱包余额。
2. 检查订阅是否过期。
3. 检查 Key 是否设置了独立额度。
4. 检查日限额、周限额、月限额是否已达到。

Cloudflare 部署后页面不是最新

文档站部署到 Cloudflare 后，如果页面仍是旧内容：

1. 确认代码已推送到 Cloudflare 绑定的分支。
2. 确认 yudao-ui/yucpu-docs/docs 没有被 .gitignore 忽略。
3. 在 Cloudflare 里使用 Clear build cache and deploy。
4. 确认构建输出目录是 docs/.vitepress/dist。