登录
文档导航
帮助与支持

排障手册

从网络、地址、鉴权、模型、余额到客户端逐层定位问题。

本页目录
  1. 排查前先记录这些信息
  2. 第一步：确认官网和 API 都能访问
  3. 第二步：确认 Key 已正确传入
  4. 第三步：只测试模型列表
  5. 第四步：发送最小非流式请求
  6. 第五步：在使用日志中定位
  7. 按状态码处理
  8. model not found 的完整排查
  9. 余额或额度不足
  10. Codex 排查顺序
  11. Claude Code 排查顺序
  12. 图片生成排查顺序
  13. 代理问题
  14. 联系支持模板

请求失败时，不要同时修改 Key、模型、地址和客户端设置。最有效的方法是先把问题缩小到最小 curl，再按“网络 -> 地址 -> Key -> 模型 -> 余额 -> 上游 -> 客户端”的顺序逐项检查。

排查前先记录这些信息

请先记录，但不要记录完整 Key：

  • 请求发生的时间和时区。
  • 使用的客户端及版本。
  • Base URL 和接口路径。
  • 模型名。
  • HTTP 状态码和完整错误文字。
  • 控制台「使用日志」中是否出现记录。

可以把 Key 脱敏成 sk-abcd...wxyz，不要把完整值放进截图、群聊或工单。

第一步：确认官网和 API 都能访问

打开浏览器分别访问：

https://console.zcloudapi.com
https://api.zcloudapi.com

模型 API 根地址不一定显示网页，但不应出现 DNS 或 TLS 证书错误。

macOS / Linux 检查：

curl -I --connect-timeout 10 "https://api.zcloudapi.com"

Windows PowerShell 检查 443 端口：

Test-NetConnection api.zcloudapi.com -Port 443

如果这里超时：

  1. 暂时关闭 VPN 或代理后重试。
  2. 换一个网络，例如手机热点。
  3. 检查企业防火墙是否允许 api.zcloudapi.com:443。
  4. 不要改用服务器 IP，API 应始终通过 HTTPS 域名访问。

第二步：确认 Key 已正确传入

macOS / Linux：

export ZHICLOUD_API_KEY="sk-你的-ZCloudAPI-Key"
test -n "$ZHICLOUD_API_KEY" && echo "Key 已设置"

Windows PowerShell：

$env:ZHICLOUD_API_KEY="sk-你的-ZCloudAPI-Key"
if ($env:ZHICLOUD_API_KEY) { "Key 已设置" } else { "Key 未设置" }

注意检查：

  • 是否误粘贴了整段连接 JSON，而不是 api_key 值。
  • Key 前后是否有空格或换行。
  • Key 是否已经停用、删除、过期或达到自身额度上限。
  • 当前终端是不是设置变量之后的同一个窗口。

第三步：只测试模型列表

macOS / Linux：

curl -i "https://api.zcloudapi.com/v1/models" \
  -H "Authorization: Bearer $ZHICLOUD_API_KEY"

Windows PowerShell：

curl.exe -i "https://api.zcloudapi.com/v1/models" `
  -H "Authorization: Bearer $env:ZHICLOUD_API_KEY"

结果判断：

结果 说明 下一步
200 且模型不为空 网络、地址和 Key 基本正常 复制一个模型继续最小请求
200 但列表为空 Key 或用户分组没有可见模型 检查分组和模型限制
401 Key 无效或认证 Header 不正确 重新创建测试 Key 并再次复制
403 用户、分组或 Key 权限不足 检查账号权限和 Key 设置
超时 / TLS 错误 网络、代理、DNS 或证书链问题 回到第一步

第四步：发送最小非流式请求

从本人 Key 的 /v1/models 返回结果复制一个支持 Chat Completions 的完整文本模型 ID，替换下面的 YOUR_TEXT_MODEL_ID 占位符，不要手工猜名称。

curl -i "https://api.zcloudapi.com/v1/chat/completions" \
  -H "Authorization: Bearer $ZHICLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_TEXT_MODEL_ID",
    "messages": [{"role": "user", "content": "只回复 OK"}],
    "max_tokens": 16,
    "stream": false
  }'

第一次排障不要使用流式输出、工具调用、图片输入或复杂参数。如果最小请求成功，再逐项加回原请求字段，找到具体是哪一个字段触发问题。

第五步：在使用日志中定位

  1. 登录 https://console.zcloudapi.com。
  2. 打开「控制台 -> 使用日志」。
  3. 按模型和大概时间查找刚才请求。
  4. 打开记录，查看状态、Token、渠道错误和扣费。

判断方式：

  • 日志里完全没有请求：通常是客户端没有连接到 https://api.zcloudapi.com/v1，或请求在到达平台前就被网络阻断。
  • 有请求但 401 / 403：检查 Key 和分组权限。
  • 有请求且上游错误：记录模型和时间，有限重试后联系支持。
  • 有成功请求但客户端报错：客户端可能无法解析返回格式或流式事件。

按状态码处理

状态码 常见原因 处理步骤
400 参数、协议或模型能力不匹配 退回最小请求，删除可选参数，再按对应协议逐项加回
401 Key 错误、停用或未正确传入 重新复制 Key，检查 Header 和当前终端环境变量
403 分组或模型权限不足 查看 /v1/models，检查 Key 的模型限制和用户分组
404 URL 拼错或接口不存在 检查 /v1 是否缺少或重复，确认接口类型
408 请求或上游超时 缩短输入、降低输出上限、增加客户端超时后重试
429 频率、并发或上游限流 降低并发，使用指数退避，不要立即无限重试
5xx 网关或上游临时异常 记录时间和模型，有限重试；持续失败时联系支持

model not found 的完整排查

  1. 重新调用 /v1/models。
  2. 在返回 JSON 中查找目标模型。
  3. 如果不存在，检查 Key 的模型限制和用户分组。
  4. 如果存在，直接复制 data[].id，不要手工输入。
  5. 检查大小写、短横线、版本号和前后空格。
  6. 确认请求发往正确协议，例如 Claude Messages、Responses 或 Chat Completions。
  7. 用最小非流式请求重新测试。

模型广场有该模型，不等于当前 Key 一定有权限。最终以当前 Key 的 /v1/models 为准。

余额或额度不足

按顺序检查：

  1. 打开「钱包」，确认账号总余额。
  2. 查看兑换码是否已经成功到账。
  3. 打开 API 密钥详情，检查这条 Key 是否有单独额度上限。
  4. 打开 模型定价页面，确认模型是按 Token 还是按次计费。
  5. 在「使用日志」核对最近请求的输入、输出和扣费。
  6. 如果余额刚刚充值，刷新页面并重新发起一次小请求。

Codex 排查顺序

  1. 用 curl 测试 /v1/models。
  2. 用 curl 测试 /v1/responses。
  3. 打开 ~/.codex/config.toml，检查 base_url = "https://api.zcloudapi.com/v1"。
  4. 检查 wire_api = "responses"。
  5. 检查 env_key 和当前终端变量名一致。
  6. 删除 requires_openai_auth = true。
  7. 完全退出 Codex，再运行 codex exec --skip-git-repo-check "只回复 OK"。

如果 curl 成功但 Codex 失败，问题才属于 Codex 配置。完整步骤见「配置 Codex」。

Claude Code 排查顺序

  1. 用 curl 测试 /v1/models。
  2. 用 curl 测试 /v1/messages。
  3. 检查 ANTHROPIC_BASE_URL=https://api.zcloudapi.com，不能附加 /v1。
  4. 检查 Key 是否放在 ANTHROPIC_AUTH_TOKEN。
  5. 检查目标 Claude 模型存在于 /v1/models。
  6. 清除 Bedrock、Vertex 或其他冲突 Provider 环境变量。
  7. 关闭所有终端，重新打开后运行 claude -p "只回复 OK"。

图片生成排查顺序

  1. 确认图片模型出现在 /v1/models。
  2. GPT、Gemini 和 Grok 生图统一使用 /v1/images/generations。
  3. 图片编辑统一使用 /v1/images/edits，并通过 multipart 的 image 字段上传原图。
  4. 检查钱包是否足够支付单次图片费用。
  5. 把尺寸降到 1K，数量设为 1，增加客户端超时。
  6. URL 返回后立即下载；Base64 Data URL 很长属于正常现象。

代理问题

macOS / Linux 查看代理变量：

env | grep -i proxy

临时关闭当前终端代理后测试：

env -u HTTP_PROXY -u HTTPS_PROXY -u ALL_PROXY \
  curl -I "https://api.zcloudapi.com"

Windows PowerShell 查看代理：

Get-ChildItem Env: | Where-Object { $_.Name -match 'PROXY' }
netsh winhttp show proxy

如果关闭代理后恢复，检查代理规则是否错误拦截 api.zcloudapi.com，而不是直接在生产代码里永久禁用所有代理。

联系支持模板

仍然无法解决时，发送邮件到 support@zcloudapi.com，可以使用下面模板：

客户端及版本：
操作系统：
请求时间和时区：
Base URL：
接口路径：
模型名：
HTTP 状态码：
完整错误文字：
使用日志是否有记录：
已经完成的排查步骤：

不要发送完整 API Key、密码、私钥、Authorization Header 或包含敏感数据的完整请求正文。