近期不少用户反馈，在将 Claude Code 或 Codex 接入 CCSub 时遇到 upstream_unavailable 错误。根据平台近7天数据，该错误出现19次，是最常见的报错。本文将从报错原因、排查步骤、配置示例和预防措施四个方面，帮助你快速解决问题。
什么是 upstream_unavailable 错误？
upstream_unavailable 表示上游模型服务暂时不可用。CCSub 作为一个聚合 API 平台，其底层依赖多个上游模型服务，当这些服务出现故障、过载或配置错误时，就会返回该错误。
常见原因分析
- 上游模型不可用：例如某个模型（如 Claude Opus 4.7）临时维护或下线。
- 余额不足：账户余额不足以支付请求费用，导致上游拒绝服务。
- API Key 无效或权限不足：密钥未创建、被禁用或没有访问指定模型的权限。
- 模型选择错误：请求的模型 ID 不存在或拼写错误。
- 网络问题：本地网络无法访问 CCSub 或上游服务，但这类问题通常表现为
connect_error。
通用排查步骤
1. 检查 API Key 和基础配置
确保你的 API Key 有效且已正确配置。在终端中运行以下命令，查看模型列表：
curl https://ccsub.xyz/v1/models \
-H "Authorization: Bearer sk-你的CCSub密钥"如果返回 401 或 403，说明 Key 无效。请到 CCSub 官网重新生成密钥。
2. 确认余额是否充足
登录 CCSub 控制台，检查账户余额。若余额为 0 或低于所需费用，请充值。你也可以通过以下命令测试余额：
curl https://ccsub.xyz/v1/chat/completions \
-H "Authorization: Bearer sk-你的CCSub密钥" \
-H "Content-Type: application/json" \
-d '{"model":"claude-sonnet-4-6","messages":[{"role":"user","content":"ping"}]}'若返回余额不足相关的错误，请前往官网充值。
3. 验证模型 ID 是否正确
使用第一步的模型列表接口，检查你请求的模型是否存在。常用的模型如 claude-sonnet-4-6、gpt-5.6-sol 等，确保拼写无误。
4. 查看详细日志
在 Claude Code 或 Codex 中开启调试模式，查看完整错误响应。通常，响应体中会包含更具体的错误信息，例如 upstream_insufficient_balance 或 model_unavailable。
5. 更换模型或稍后重试
如果某个模型暂时不可用（如 Claude Opus 4.7），可以尝试切换到其他模型，如 claude-sonnet-4-6 或 gpt-5.5。稍等几分钟后重试也可能解决问题。
Claude Code 接入 CCSub 的配置示例
Claude Code 使用 Anthropic 兼容接口。在环境变量中设置以下信息：
export ANTHROPIC_BASE_URL=https://ccsub.xyz
# Messages 端点固定为 /v1/messages，无需额外设置
export ANTHROPIC_AUTH_TOKEN=sk-你的CCSub密钥然后在项目中启动 Claude Code，即可正常使用。
Codex 接入 CCSub 的配置示例
Codex 支持 OpenAI 兼容接口，设置如下：
export OPENAI_BASE_URL=https://ccsub.xyz/v1
# 聊天端点固定为 /v1/chat/completions
export OPENAI_API_KEY=sk-你的CCSub密钥启动 Codex 后，即可调用平台上的 GPT 系列模型。
使用注意事项
- CCSub 的定价规则为 1 元 = 1 美元，具体模型价格可在官网查询。流量消耗较大时，请留意余额。
- 平台支持图片识别等能力，但部分模型可能不支持，请确认所选模型的 multimodal 特性。
- 如遇持续无法解决的错误，请参考官方故障排查文档或联系客服。
常见问题
Q1：为什么我设置正确还是报错？
检查本地网络是否能够访问 ccsub.xyz，部分环境需要代理。确认代理设置无误后，再重试。
Q2：如何获取最新可用的模型列表？
调用 GET /v1/models 接口，返回的列表即为当前可用模型。
Q3：CCSub 安全吗？会封号吗？
CCSub 不提供官方授权，但平台通过技术手段保障稳定性。请遵守平台规定，避免滥用，正常使用不会封号。
结语
upstream_unavailable 虽然常见，但通过上述步骤，绝大多数情况可以解决。建议用户定期关注官网公告，了解模型变动和服务状态。如果问题依旧，请及时联系客服获取支持。
提示：充值前可先使用小金额测试，确保配置无误后再投入正式使用。