先选协议，再接入客户端

5 分钟快速开始

先走控制台里的快捷路径：登录、创建 API Key、点“使用密钥”查看现成配置，或点“导入到 CCS”一键导入 CC Switch。快捷路径满足不了时，再往下看具体客户端章节。

1. 登录控制台：打开 https://ai.zh-zh.top。
2. 确认入口：左侧菜单里常用的是 API 密钥、AI 对话、AI 生图、充值/订阅、邀请返利。
3. 创建 API Key：进入 /keys，创建密钥时选择对应分组，例如 Codex / OpenAI 兼容分组或 Claude 分组。
4. 优先用快捷教程：创建后先点 使用密钥 查看现成配置；如果你用 CC Switch，就点 导入到 CCS 一键导入。
5. 再看具体客户端：如果快捷配置不够，再按下方 Cursor、Claude Code、Codex CLI、OpenCode 等客户端章节补充设置。

Quick 1

先认准控制台左侧入口

新手不要先找客户端文档。先在控制台左侧找到 API 密钥 创建 Key；网页内置能力则从 AI 对话、AI 生图 进入；额度相关从 充值/订阅、我的订单、邀请返利 查看。

API 密钥创建 Key、使用密钥、导入到 CCS

AI 对话 / AI 生图网页直接体验聊天和图片生成

充值/订阅余额、套餐、订单和订阅状态

邀请返利复制邀请链接，查看返利额度

Quick 2

点“使用密钥”直接看配置教程

如果你不想手动猜配置，创建 Key 后先点 使用密钥。弹窗里会按 Codex CLI、Codex CLI WebSocket、Claude Code、OpenCode 等平台给出配置片段；复制到对应配置文件即可。

注意：教程截图里的密钥已经脱敏。你自己配置时复制后台弹窗里的真实 Key，不要把真实 Key 截图发给别人。

Quick 3

用 CC Switch 就点“导入到 CCS”

如果你用 CC Switch / CCS，不需要手动复制配置。确认密钥分组选对后，在操作区点 导入到 CCS，再回到 CC Switch 里切换配置并测试。

分组规则仍然一样：Codex / Cursor / OpenCode 这类 OpenAI 兼容客户端选 Codex / OpenAI 兼容分组；Claude Code / Anthropic 选 Claude 分组。

地址与协议规则

客户端里让你填的通常是 Base URL，不是完整请求 URL。先按协议选地址，再让客户端自动拼后面的路径。

鉴权怎么填

查询模型

curl https://ai.zh-zh.top/v1/models \
  -H "Authorization: Bearer $ZH_AI_API_KEY"

curl https://ai.zh-zh.top/v1beta/models \
  -H "x-goog-api-key: $ZH_AI_API_KEY"

常用页面入口

选择你的客户端

不要从一长串名字里硬找。先看自己要在哪个环境里用，再进入对应教程。

Claude / Anthropic 协议

终端 CLI · AnthropicClaude Code

推荐先在终端跑通；Base URL 不要带 /v1。

重点教程新手优先 配置管理 · CCSCC Switch

从 API 密钥操作区一键导入 Claude / Codex 配置。

一键导入推荐 桌面客户端 · AnthropicClaude Desktop

配置第三方推理网关，适合桌面聊天场景。

图文步骤桌面端

编程 IDE / Agent

IDE · OpenAI 兼容Cursor

在 Models 设置里填 Key、Base URL 和模型名。

图文步骤常用 VS Code 插件 · OpenAI 兼容Cline

打开插件设置，选择 OpenAI Compatible。

参数速填 Agentic IDE · OpenAI 兼容Qoder

在第三方模型服务里新增供应商。

参数速填 编码助手 · OpenAI 兼容Lingma

找到模型服务或 API Endpoint 设置。

参数速填

终端 CLI / Agent

CLI · OpenAI 兼容Codex CLI

安装 CLI 后在配置文件里指定 zz AI provider。

重点教程 终端工具 · OpenAI 兼容OpenCode

用 /connect 添加自定义模型服务。

命令流 消息渠道 AgentOpenClaw

把模型、Agent 和渠道配置合并到本地配置文件。

高级配置 CLI · OpenAI 兼容Qwen Code

优先通过 /auth 交互配置，再写固定配置。

图文步骤 CLI Agent · OpenAI 兼容Kilo CLI

选择 Provider、填写模型、保存并切换。

示意步骤 JetBrains CLIJunie CLI

若支持自定义 OpenAI 兼容供应商，可按同一套参数填。

参数速填 终端 AgentHermes Agent

在配置文件里写 provider、base_url 和环境变量名。

配置文件

桌面聊天客户端

桌面聊天 · OpenAI 兼容Cherry Studio

模型服务里添加自定义 OpenAI 兼容供应商。

参数速填 桌面聊天 · OpenAI 兼容Chatbox

模型提供方选择 OpenAI API 兼容。

参数速填

平台 / 调试 / SDK

应用平台 · OpenAI 兼容Dify

在 Workspace 的模型供应商里添加 OpenAI-compatible。

示意步骤 API 调试 · 完整 URLPostman / cURL

先用标准请求验证 Key、模型和余额是否正常。

重点教程排错必看 开发接入 · OpenAI SDKOpenAI SDK

代码里只填 base_url/baseURL，不手动拼接口路径。

开发者

Cursor 接入

Cursor 使用 OpenAI Compatible。你要做的是进入 Models 设置，添加或启用模型，再填写 Key 和 Base URL。

Step 1

进入 Models 设置

打开 Cursor Settings → Models，先确认模型设置入口。

Step 2

填写 Key 和 Base URL

开启 OpenAI API Key，并把 Override OpenAI Base URL 填成 https://ai.zh-zh.top/v1。

复制 Cursor Base URL

Step 3

添加自定义模型并测试

如果下拉里没有模型，就手动 Add Custom Model。保存后在聊天窗口发一句测试消息。

Claude Code 接入

1. 先用当前终端窗口临时设置变量，确认能跑通。
2. 成功后再写入用户级配置或系统环境变量。
3. 需要多供应商切换时再用 cc-switch；VS Code 面板只作为使用入口。

Step 1

先在终端里验证

Windows 用户可以用 PowerShell，也可以用 Git Bash。先临时设置环境变量，当前窗口成功后再考虑持久化。

PowerShell 临时验证

$env:ZH_AI_API_KEY="sk-你的密钥"
$env:ANTHROPIC_BASE_URL="https://ai.zh-zh.top"
$env:ANTHROPIC_AUTH_TOKEN=$env:ZH_AI_API_KEY
Remove-Item Env:ANTHROPIC_API_KEY -ErrorAction SilentlyContinue
claude -p "只回复 OK"

Git Bash 临时验证

export ZH_AI_API_KEY="sk-你的密钥"
export ANTHROPIC_BASE_URL="https://ai.zh-zh.top"
export ANTHROPIC_AUTH_TOKEN="$ZH_AI_API_KEY"
unset ANTHROPIC_API_KEY
claude -p "只回复 OK"

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://ai.zh-zh.top",
    "ANTHROPIC_AUTH_TOKEN": "sk-你的密钥"
  }
}

Optional

多供应商再用 cc-switch

cc-switch 适合管理多套 Claude Code 配置。建议先按上面的终端方式跑通，再用它切换供应商；不要把临时环境变量、系统环境变量、settings.json 和 cc-switch 四处混用。

Optional

VS Code 面板只是使用入口

如果你在 VS Code 里使用 Claude Code，先确保普通终端已经能跑通。IDE 面板通常继承已有配置，不应该作为第一步排查入口。

CC Switch / CCS 导入教程

如果你已经安装 CC Switch，可以直接在控制台的 API 密钥列表里把密钥导入到 CCS，省掉手动复制 Base URL、Token 和模型分组的步骤。

Step 2

创建后选择操作

密钥创建完成后，在这一行右侧操作区可以看到 使用密钥、导入到 CCS、禁用、编辑、删除等操作。需要查看手动配置参数时点“使用密钥”；需要一键导入 CC Switch 时点“导入到 CCS”。

Claude Desktop 接入

Claude Desktop 走 Anthropic-compatible 网关，适合桌面聊天场景。它和 Claude Code 一样，不按 OpenAI 兼容地址填写。

Step 1

打开开发者模式

在 Help → Troubleshooting 中启用 Developer Mode。

Step 2

配置第三方推理

进入 Configure Third-Party Inference，按左侧参数填写 Gateway URL 和 Authorization。

Codex CLI 接入

Codex CLI 优先以控制台 使用密钥 弹窗给出的配置为准。当前弹窗推荐 Responses 模式：Base URL 使用 https://ai.zh-zh.top，由 Codex CLI 按 wire_api = "responses" 处理路径。

1. 确认 Node.js 和 npm 可用。
2. 安装并启动 Codex CLI。
3. 优先复制后台“使用密钥”弹窗里的 Codex CLI 配置，再发送测试问题。

Step 1

确认 Node.js 和 npm

先确认本机已经能运行 node 和 npm，再安装 CLI。

node -v
npm -v

Step 2

安装并启动 CLI

安装后第一次启动，先不要急着改多处配置，保持一个 provider 跑通。

npm install -g @openai/codex
codex

Step 3

复制“使用密钥”里的配置并验证

在控制台 API 密钥列表点 使用密钥，切到 Codex CLI 和你的系统标签，把弹窗里的 config.toml 与 auth.json 片段复制到对应文件。下面示例保持和后台弹窗同一口径。

~/.codex/config.toml 示例

model_provider = "OpenAI"
model = "gpt-5.5"
review_model = "gpt-5.5"
model_reasoning_effort = "xhigh"
disable_response_storage = true
network_access = "enabled"
windows_wsl_setup_acknowledged = true

[model_providers.OpenAI]
name = "OpenAI"
base_url = "https://ai.zh-zh.top"
wire_api = "responses"
requires_openai_auth = true

[features]
goals = true

~/.codex/auth.json 示例

{
  "OPENAI_API_KEY": "sk-你的密钥"
}

保存后执行一次简单提问。如果你后台弹窗里的模型名、字段或路径有变化，以弹窗为准。

Cline 接入

Cline 选择 OpenAI Compatible 后，按下面参数填写即可。它属于 VS Code 插件场景，不要套用 Claude / Anthropic 地址。

Cherry Studio 接入

打开设置 → 模型服务 → 添加供应商，选择 OpenAI / OpenAI Compatible 类型。

Chatbox 接入

在左下角设置里新增模型提供方，API 模式选择 OpenAI API 兼容。

Dify 接入

Dify 属于平台后台配置流：先进入 Workspace 设置，再添加 OpenAI-API-compatible 模型供应商。

Step 1

进入模型供应商

在 Dify 后台找到模型供应商入口，添加 OpenAI 兼容服务。

Kilo CLI 接入

Kilo CLI 选择 OpenAI Compatible Provider 后填写 Base URL、Key 和模型名。

Step 1

进入 Provider 配置

打开配置入口，选择 OpenAI Compatible。

OpenCode 接入

OpenCode 走 OpenAI Compatible。先安装并启动，再用 /connect 添加自定义供应商。

curl -fsSL https://opencode.ai/install | bash
opencode
/connect
/models

OpenClaw 接入

OpenClaw 更像高级配置文件教程。核心是把 models、agents、channels 合并到 ~/.openclaw/openclaw.json，不要整段覆盖已有配置。

Qwen Code 接入

推荐先用 /auth 交互配置，确认能用后再写入固定配置。

Qoder 接入

若当前版本支持自定义 OpenAI Compatible 服务端点，在模型、Provider、API Endpoint 或第三方模型服务中新增供应商。

Lingma 接入

不同版本 Lingma 配置入口可能不同，优先找“模型服务 / 第三方模型 / API Endpoint / Provider”。

Junie CLI 接入

如果 Junie 当前版本支持自定义 OpenAI Compatible Provider，就按同一套参数填；如果界面没有入口，优先改用 Cursor、Cline、Codex CLI、OpenCode 或 Qwen Code。

Hermes Agent 接入

Hermes 主要是配置文件接入。字段名随版本可能不同，但 API 类型、Base URL、API Key 环境变量和模型 ID 要保持一致。

model:
  provider: custom
  default: 从模型列表复制的模型名

providers:
  custom:
    api: openai
    base_url: https://ai.zh-zh.top/v1
    api_key_env: ZH_AI_API_KEY

Postman / cURL 调试

Postman 适合先验证 Key、Base URL、模型名和余额是否正常。这里要填的是完整请求 URL，而不是 Base URL。

1. 新建 POST 请求，填写完整聊天接口 URL。
2. 添加 Authorization 和 Content-Type 两个请求头。
3. Body 选择 raw JSON，填入模型名和 messages 后发送。

Step 1

新建 POST 请求并填写 URL

URL 必须是完整聊天接口：https://ai.zh-zh.top/v1/chat/completions。

复制请求 URL

Step 2

填写 Headers

添加 Authorization: Bearer sk-你的密钥 和 Content-Type: application/json。

复制 Authorization

Step 3

填写 Body 并发送

Body 选择 raw JSON。模型名必须是当前 Key 可用的模型。

请求体示例

{
  "model": "从模型列表复制的模型名",
  "messages": [
    { "role": "user", "content": "你好，简单介绍一下你自己。" }
  ]
}

curl https://ai.zh-zh.top/v1/chat/completions \
  -H "Authorization: Bearer $ZH_AI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"从模型列表复制的模型名","messages":[{"role":"user","content":"你好"}]}'

OpenAI SDK 示例

SDK 里填 base_url/baseURL = https://ai.zh-zh.top/v1，SDK 会自动拼接聊天、模型列表等具体路径。

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ["ZH_AI_API_KEY"],
    base_url="https://ai.zh-zh.top/v1",
)

response = client.chat.completions.create(
    model="从模型列表复制的模型名",
    messages=[{"role": "user", "content": "你好"}],
)

print(response.choices[0].message.content)

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.ZH_AI_API_KEY,
  baseURL: "https://ai.zh-zh.top/v1",
});

const response = await client.chat.completions.create({
  model: "从模型列表复制的模型名",
  messages: [{ role: "user", content: "你好" }],
});

console.info(response.choices[0]?.message?.content);

邀请返利教程

入口：https://ai.zh-zh.top/affiliate

1. 打开 邀请返利 页面。
2. 复制 我的邀请码 或完整邀请链接。
3. 把邀请链接发给新用户。
4. 新用户通过链接注册并充值后，你获得返利额度。
5. 可用返利额度大于 0 时，点击 转入余额。

排错中心