登录
文档导航
客户端接入

客户端接入矩阵

对照 Codex、Claude、Gemini、OpenCode 和桌面客户端的配置要求。

本页目录
  1. 接入矩阵
  2. 所有客户端共用的准备步骤
  3. Codex CLI 与 Desktop
  4. Claude Code
  5. Cursor 与 Cherry Studio
  6. CC Switch
  7. OpenCode
  8. Gemini CLI 与 Gemini native SDK
  9. 其他 OpenAI-compatible 客户端
  10. 按能力选协议
  11. 客户端验证清单
  12. 常见问题

不同客户端对 Base URL、协议和模型能力的要求不同。先从矩阵确定接入方式，再进入已验证的详细教程；不要把一个客户端的配置原样套到另一个客户端。

接入矩阵

客户端 协议与地址 继续阅读
ZCloud Setup 自动配置 Codex / Claude，并读取模型 一键安装
Codex CLI / Desktop Responses，填写 https://api.zcloudapi.com/v1 配置 Codex
Claude Code Messages，填写 https://api.zcloudapi.com 配置 Claude Code
Cursor OpenAI compatible，填写 https://api.zcloudapi.com/v1 Cursor / Cherry Studio
Cherry Studio OpenAI compatible，填写 https://api.zcloudapi.com/v1 Cursor / Cherry Studio
CC Switch 地址取决于被管理的目标客户端 本页检查清单
OpenCode OpenAI compatible，填写 https://api.zcloudapi.com/v1 本页快速配置
Gemini CLI / native SDK Gemini native，填写 https://api.zcloudapi.com 接入地址选择
其他兼容客户端 OpenAI compatible，通常使用 https://api.zcloudapi.com/v1 本页通用模板

客户端能显示一个模型名，不代表请求一定通过 ZCloudAPI。最终验证标准是客户端返回成功，并且 https://console.zcloudapi.com 的使用日志出现同一时间、同一模型的请求。

所有客户端共用的准备步骤

  1. 在 https://console.zcloudapi.com 创建一条客户端专用 API Key。
  2. 为测试 Key 设置合理的模型范围、低额度和有效期。
  3. 把 Key 放入当前终端的环境变量，不写进源码。
  4. 请求 https://api.zcloudapi.com/v1/models，复制目标模型的完整名称。
  5. 使用对应协议完成一次最小非流式 curl。
  6. curl 成功后，再把完全相同的地址、Key 和模型填进客户端。

这一步能把账号、权限和网关问题与客户端配置问题分开。

Codex CLI 与 Desktop

Codex 使用 Responses API，自定义 Provider 的关键项是：

model_provider = "zhicloud"
model = "从 /v1/models 复制的 GPT 模型"

[model_providers.zhicloud]
name = "ZCloudAPI"
base_url = "https://api.zcloudapi.com/v1"
env_key = "ZHICLOUD_API_KEY"
wire_api = "responses"

不要在 base_url 后追加 /responses，也不要启用只适用于官方 OpenAI 登录的配置。安装、备份、环境变量和验证命令见「配置 Codex」。

Claude Code

Claude Code 会在 Base URL 后自行拼 /v1/messages：

export ANTHROPIC_BASE_URL="https://api.zcloudapi.com"
export ANTHROPIC_AUTH_TOKEN="$ZHICLOUD_API_KEY"
export ANTHROPIC_MODEL="从 /v1/models 复制的 Claude 模型"

这里必须使用 https://api.zcloudapi.com，不能使用已包含 /v1 的 https://api.zcloudapi.com/v1。如果配置后仍打开官方登录页，检查 ANTHROPIC_AUTH_TOKEN 是否生效，以及是否残留 Bedrock、Vertex 或其他 Provider 环境变量。

Cursor 与 Cherry Studio

在 Provider 设置中寻找 OpenAI Compatible、Custom OpenAI、API Endpoint 或 Base URL，然后填写：

Base URL: https://api.zcloudapi.com/v1
API Key: sk-你的-ZCloudAPI-Key
Model: 从 /v1/models 复制

只填到 /v1，不要填完整的 /chat/completions，除非该客户端明确要求完整接口地址。详细菜单和验证步骤见「Cursor / Cherry Studio」。

CC Switch

CC Switch 用于集中管理多个 AI Coding 客户端的 Provider 配置。新增 ZCloudAPI Provider 时，需要按目标客户端分别保存地址：

目标客户端 Provider 地址
Codex https://api.zcloudapi.com/v1
Claude Code https://api.zcloudapi.com
OpenCode / OpenAI compatible https://api.zcloudapi.com/v1

使用前先备份现有客户端配置。切换 Provider 后完全退出并重启目标客户端，再查看它实际使用的环境变量或配置文件。不要把 Codex 的 /v1 地址直接复用为 Claude Code 的根地址。

验证 CC Switch 是否真正生效：

  1. 记录切换前客户端的 Provider 和模型。
  2. 在 CC Switch 中选择 ZCloudAPI 配置。
  3. 完全退出并重启客户端。
  4. 发起内容为“只回复 OK”的最小请求。
  5. 在 ZCloudAPI 使用日志核对模型和时间。
  6. 切回原 Provider 时再次重启并确认回退成功。

OpenCode

OpenCode 应选择支持自定义 OpenAI-compatible Base URL 的 Provider。关键值是：

Provider type: OpenAI Compatible
Base URL: https://api.zcloudapi.com/v1
API Key: 从环境变量或 Secret 读取
Model: 从 /v1/models 复制

OpenCode 的配置文件结构会随版本和 Provider 插件变化。配置后检查实际请求不能出现重复 /v1，并用新会话完成最小请求。若使用 CC Switch 管理 OpenCode，先确认它写入的是 OpenCode 当前版本实际读取的用户级配置文件。

Gemini CLI 与 Gemini native SDK

只有客户端版本提供自定义 Gemini API 根地址时，才可以直接使用 Gemini native 接入。地址使用 https://api.zcloudapi.com，最终路径应类似：

https://api.zcloudapi.com/v1beta/models/{model}:generateContent

需要同时满足：

  • 当前 Key 的 /v1/models 包含目标 Gemini 模型。
  • 模型详情标注支持 Gemini 原生协议。
  • 客户端支持自定义 endpoint，而不是强制连接 Google 官方账号和域名。
  • Key 通过客户端支持的环境变量、Header 或 Secret 方式注入。

如果客户端版本没有自定义 endpoint 功能，不要通过修改 Hosts 或替换服务器 IP 强行接入。可以改用该客户端明确支持的 OpenAI-compatible Provider，或换用支持 ZCloudAPI 的其他客户端。

其他 OpenAI-compatible 客户端

通用填写模板：

Provider: OpenAI Compatible / Custom OpenAI
Base URL: https://api.zcloudapi.com/v1
API Key: sk-你的-ZCloudAPI-Key
Model: 从 /v1/models 复制

保存后如果客户端支持“获取模型”或“测试连接”，先执行一次。自动获取失败时，使用 curl 确认 /v1/models 正常，再手工添加精确模型名。

以下客户端通常不能直接接入：

  • 只允许官方账号 OAuth 登录，没有自定义 API Key 的版本。
  • 没有 Base URL、Endpoint 或自定义 Provider 设置的版本。
  • 把 API Key 直接发送到浏览器网页或第三方云同步服务，且没有本地 Secret 保护的版本。

按能力选协议

需求 首选协议 注意事项
普通对话 Chat Completions 兼容性最广，先用非流式验证
Codex / Agent Responses 客户端需支持 Responses wire API
Claude 工具调用 Anthropic Messages 使用 Claude 模型和 Messages 请求结构
Gemini 原生内容生成 Gemini native 客户端必须支持自定义 Gemini endpoint
图片生成 Images API 或模型指定协议 结果可能是临时 URL 或 Base64

不要因为客户端支持 Chat Completions 就假设它完整支持 Responses、Messages、图片或 Gemini native。

客户端验证清单

  • 客户端实际使用的 API Key 是新建的受限 Key。
  • Base URL 没有遗漏或重复 /v1。
  • 模型名来自同一条 Key 的 /v1/models。
  • curl 使用同一协议、地址、Key 和模型能够成功。
  • 客户端最小请求返回正文，不依赖复杂工具或历史会话。
  • 使用日志出现同一时间、同一模型和预期 group 的记录。
  • 日志中的 HTTP 状态、耗时和扣费合理。
  • 完全重启客户端后配置仍然生效。

常见问题

现象 处理
客户端要求官方登录 切换到 Custom / Compatible Provider，确认版本支持自定义地址
404 查看实际 URL 是否遗漏或重复 /v1，并确认协议
401 检查 Key 是否完整、环境变量是否进入客户端进程
模型列表为空 检查用户分组、Key 模型限制和 /v1/models
模型可见但调用失败 用对应协议做最小 curl，检查模型能力和余额
curl 成功但客户端失败 检查客户端版本、Provider、代理、流式解析和配置文件位置
客户端成功但 ZCloudAPI 无日志 当前会话可能仍使用其他 Provider 或官方地址
非流式成功但流式中断 检查代理对 SSE 的缓冲、空闲超时和连接关闭行为

持续失败时，按「错误码与重试」保留 request ID、模型、group、状态码和用时，不要发送完整 Key。