先选协议，再接入客户端

5 分钟快速开始

先走控制台里的快捷路径：登录、创建 API Key、点“使用密钥”查看现成配置，或点“导入到 CCS”一键导入 CC Switch。这里先解决“密钥和客户端怎么接入”；如果你的命令行工具还没装，再单独去看 CLI 安装。

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、Gemini CLI、Droid CLI、OpenCode 等客户端章节补充设置。
6. 未安装 CLI 再去安装栏：如果本机还没有 Claude Code、Codex、Gemini 或 Droid，单独看 CLI 安装，不要把安装命令和中转站配置混在一起排错。

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"

常用页面入口

CLI 安装

这一栏只解决“工具怎么装到电脑上”。装好以后，回到 选择客户端 里的对应章节，再完成 zz AI 中转站接入设置。

node -v
npm -v

npm config set registry https://registry.npmmirror.com
npm config get registry

npm install -g 包名 --registry=https://registry.npmmirror.com

npm install -g @anthropic-ai/claude-code --registry=https://registry.npmmirror.com
claude --version

npm install -g @openai/codex --registry=https://registry.npmmirror.com
codex --version

npm install -g @google/gemini-cli --registry=https://registry.npmmirror.com
gemini --version

npm install -g droid --registry=https://registry.npmmirror.com
droid --version

选择你的客户端

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

Claude / Anthropic 协议

终端 CLI · AnthropicClaude Code

进入 Anthropic 接入配置；未安装先看 CLI 安装。

重点教程配置接入 配置管理 · 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

进入 Codex provider 配置；未安装先看 CLI 安装。

重点教程配置接入 CLI · Gemini 原生Gemini CLI

进入 Gemini Base URL / Key 配置；未安装先看 CLI 安装。

配置接入 FCLI Agent · FactoryDroid CLI

进入 customModels 配置；未安装先看 CLI 安装。

配置文件 终端工具 · 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. 本节默认你已经装好 claude 命令；未安装先看 Claude Code 安装。
2. 用当前终端窗口临时设置 zz AI 的 Base URL 和 Token 并验证。
3. 成功后再写入用户级配置或系统环境变量；需要多供应商切换时再用 cc-switch。

$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"

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-你的密钥"
  }
}

claude -p "只回复 OK"

Optional

多供应商再用 cc-switch

cc-switch 适合管理多套 Claude Code 配置。建议先按上面的终端方式跑通，再用它切换供应商；添加供应商时仍然遵守同一条规则：Claude / Anthropic Base URL 不带 /v1。

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" 处理路径。不要把这个示例强行改成普通 OpenAI Compatible 的 /v1/chat/completions。

1. 本节默认你已经装好 codex 命令；未安装先看 Codex CLI 安装。
2. 复制后台“使用密钥”弹窗里的 Codex CLI 配置；如果已有配置，先备份再合并。
3. 模型名从后台模型列表或弹窗复制，不要长期依赖页面示例。

mkdir -p ~/.codex
cp ~/.codex/config.toml ~/.codex/config.toml.bak 2>/dev/null || true
cp ~/.codex/auth.json ~/.codex/auth.json.bak 2>/dev/null || true

New-Item -ItemType Directory -Force $HOME\.codex | Out-Null
Copy-Item $HOME\.codex\config.toml $HOME\.codex\config.toml.bak -ErrorAction SilentlyContinue
Copy-Item $HOME\.codex\auth.json $HOME\.codex\auth.json.bak -ErrorAction SilentlyContinue

Step 2

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

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

~/.codex/config.toml 示例

model_provider = "OpenAI"
model = "从后台模型列表复制的模型 ID"
review_model = "从后台模型列表复制的模型 ID"
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-你的密钥"
}

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

Gemini CLI 接入

1. 本节默认你已经装好 gemini 命令；未安装先看 Gemini CLI 安装。
2. 在当前终端设置 Key 和 Gemini Base URL，先做一次简单验证。
3. 模型名以后台模型列表为准；如果 CLI 版本支持 -m，可以启动时指定模型。

$env:GEMINI_API_KEY="sk-你的密钥"
$env:GOOGLE_GEMINI_BASE_URL="https://ai.zh-zh.top/v1beta"
$env:GEMINI_BASE_URL=$env:GOOGLE_GEMINI_BASE_URL
gemini -p "只回复 OK"

export GEMINI_API_KEY="sk-你的密钥"
export GOOGLE_GEMINI_BASE_URL="https://ai.zh-zh.top/v1beta"
export GEMINI_BASE_URL="$GOOGLE_GEMINI_BASE_URL"
gemini -p "只回复 OK"

gemini -m "从后台模型列表复制的模型 ID" -p "只回复 OK"

Droid CLI 接入

1. 本节默认你已经装好 droid 命令；未安装先看 Droid CLI 安装。
2. 启动前备份 settings.json；已有配置时只合并 customModels 数组。
3. 优先按 OpenAI Compatible 写入 generic-chat-completion-api 自定义模型。
4. 如果官方文档或当前版本提供 Anthropic provider，再按它的 provider 名称填写，并把 Claude / Anthropic Base URL 写成 https://ai.zh-zh.top。

# macOS / Linux / WSL
~/.factory/settings.json

# Windows PowerShell
$HOME\.factory\settings.json

{
  "customModels": [
    {
      "model": "从后台模型列表复制的模型 ID",
      "displayName": "zz AI OpenAI Compatible",
      "provider": "generic-chat-completion-api",
      "baseUrl": "https://ai.zh-zh.top/v1",
      "apiKey": "${ZH_AI_API_KEY}",
      "maxOutputTokens": 16384
    }
  ]
}

# macOS / Linux / WSL
export ZH_AI_API_KEY="sk-你的密钥"

# Windows PowerShell
$env:ZH_AI_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 添加自定义供应商。

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 时，点击 转入余额。

排错中心