CC-Switch 优先 默认 Host：https://re.94xy.cn 文档路径：`/docs/api.html`

# 大模型 API 接入文档

推荐流程：先进入 `/keys` 创建或复制 API Key，再优先点击 `导入到 CCS` 一键导入到 CC-Switch。其余客户端按对应协议接入： OpenAI SDK / HTTP 使用 `/v1`，Claude Code 使用根 Host，Gemini / OpenClaw / Hermes 按各自配置格式接入。

进入 API 密钥 下载 CC-Switch 查看 Host 列表
默认主 Host
https://re.94xy.cn
站内取 Key 路径
`/keys` -> 创建密钥 / 使用密钥 / 导入到 CCS
文档放置方式
静态页，适合挂到文档链接或自定义菜单
兼容协议
OpenAI / Claude / Gemini / Responses / OpenClaw / Hermes

## 快速开始

默认推荐走 CC-Switch。它和站内 `API 密钥` 页面已经对齐，拿到 Key 后可以直接一键导入。

01

### 获取 API Key

登录站点后进入 `/keys`。创建密钥后，列表行内可以直接看到 `使用密钥` 和 `导入到 CCS` 两个动作。

02

### 优先一键导入

点击 `导入到 CCS`。OpenAI 分组会导入为 Codex，Anthropic 分组导入为 Claude Code，Gemini 分组导入为 Gemini CLI，Antigravity 会先让你选 Claude 或 Gemini。

03

### 按客户端使用

如果不使用 CC-Switch，按下方目录选择对应格式：HTTP、OpenAI SDK、Claude Code、Gemini CLI、Codex CLI、OpenClaw、Hermes。

后台管理员如果隐藏了 `导入到 CCS` 按钮，用户仍然可以在本页使用“手动导入 CC-Switch”工具，或按下方 CLI / SDK 示例手动配置。

## CC-Switch

站内默认推荐使用 CC-Switch。先在站内 `/keys` 获取 API Key，再导入到对应客户端配置。

### 下载安装索引

- 官方 Releases：GitHub Releases
- Windows：推荐 `CC-Switch-*-Windows.msi`；便携版可用 `Windows-Portable.zip`
- macOS：推荐 `macOS.zip`；Homebrew 可用 `brew tap farion1231/ccswitch` + `brew install --cask cc-switch`
- Linux：Debian/Ubuntu 用 `.deb`，Fedora/RHEL 用 `.rpm`，通用可用 `.AppImage`

打开下载页 去 API 密钥

### 站内一键导入位置

- 路径：`/keys`
- 拿到 Key 后，点击同一行的 `导入到 CCS`
- Antigravity 分组会先选择导入到 `Claude Code` 或 `Gemini CLI`
- 导入完成后，在 CC-Switch 对应应用的 Provider 列表里查看

如果点击导入后没有拉起客户端，通常是 CC-Switch 未安装，或系统还没有注册 `ccswitch://` 协议。

### 导入映射

站内分组 | 导入应用 | CC-Switch Endpoint
--- | --- | ---
OpenAI | Codex | `HOST`
Anthropic / Claude | Claude Code | `HOST`
Gemini | Gemini CLI | `HOST`
Antigravity | Claude Code / Gemini CLI | `HOST/antigravity`

### 手动导入 CC-Switch

Host
默认优先使用 https://re.94xy.cn。
导入类型
Provider 名称
API Key

## 支持平台概览

不同客户端读取 Host 的方式不一样。HTTP / OpenAI SDK 通常需要显式写 `/v1`；站内 CLI 配置模板大多使用根 Host。

平台 / 客户端 | 协议 | 推荐写法 | 说明
--- | --- | --- | ---
HTTP / OpenAI SDK | OpenAI Chat / Responses | `https://re.94xy.cn/v1` | 标准服务端与脚本最稳妥
Claude Code | Anthropic 兼容 | `https://re.94xy.cn` | 使用 `ANTHROPIC_BASE_URL`
Gemini CLI | Gemini CLI 兼容 | `https://re.94xy.cn` | 使用 `GOOGLE_GEMINI_BASE_URL`
Codex CLI | OpenAI Responses | `https://re.94xy.cn` | 按站内生成模板写入 `~/.codex`
OpenCode | OpenAI / Anthropic / Google Provider | `https://re.94xy.cn/v1` | OpenAI 分组按 `baseURL` 配置
OpenClaw | Custom Provider | `https://re.94xy.cn/v1` | 按 `~/.openclaw/openclaw.json` 写 `models.providers`
Hermes | Custom Endpoint | `https://re.94xy.cn/v1` | 当前版本使用 `~/.hermes/config.yaml`

## API 接口地址 Host 列表

默认主 Host 为 `re.94xy.cn`。如果后台配置了公开的 `API Base URL` 或自定义端点，下方会自动带出来。

HTTP / OpenAI SDK 通常写 `HOST/v1`；Gemini / OpenClaw / Hermes 的详细格式看各自章节。站内 `API 密钥` 页面也会展示管理员配置的可用 Host。

## HTTP 示例

直接脚本、后端服务、第三方网关优先用 OpenAI 兼容格式。下方示例默认使用 `https://re.94xy.cn/v1`。

cURL /v1/chat/completions

    curl https://re.94xy.cn/v1/chat/completions \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "gpt-5.4",
        "messages": [
          {"role": "system", "content": "You are a helpful assistant."},
          {"role": "user", "content": "请给我一份三点接入建议"}
        ]
      }'

cURL /v1/models

    curl https://re.94xy.cn/v1/models \
      -H "Authorization: Bearer YOUR_API_KEY"

## JavaScript SDK

只要 SDK 支持自定义 `baseURL`，大多数都能直接接入。

openai npm

    import OpenAI from "openai";

    const client = new OpenAI({
      apiKey: process.env.API_KEY,
      baseURL: "https://re.94xy.cn/v1",
    });

    const response = await client.chat.completions.create({
      model: "gpt-5.4",
      messages: [{ role: "user", content: "Hello" }],
    });

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

## Python SDK

Python 接入方式和 JavaScript 一样，关键是把 `base_url` 指向网关的 `/v1`。

openai python

    from openai import OpenAI

    client = OpenAI(
        api_key="YOUR_API_KEY",
        base_url="https://re.94xy.cn/v1",
    )

    response = client.chat.completions.create(
        model="gpt-5.4",
        messages=[{"role": "user", "content": "Hello"}],
    )

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

## Claude Code

Claude Code 按站内现有模板使用根 Host，不额外拼 `/v1`。

macOS / Linux

    export ANTHROPIC_BASE_URL="https://re.94xy.cn"
    export ANTHROPIC_AUTH_TOKEN="YOUR_API_KEY"
    export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1

## Gemini CLI

Gemini CLI 也使用根 Host。模型名按你当前可用权限调整。

macOS / Linux

    export GOOGLE_GEMINI_BASE_URL="https://re.94xy.cn"
    export GEMINI_API_KEY="YOUR_API_KEY"
    export GEMINI_MODEL="gemini-2.0-flash"

## Codex CLI

站内 `使用密钥` 页面给 Codex CLI 生成的是 `~/.codex/config.toml` 与 `auth.json` 两个文件。以下格式与站内模板一致。

~/.codex/config.toml

    model_provider = "OpenAI"
    model = "gpt-5.4"
    review_model = "gpt-5.4"
    model_reasoning_effort = "xhigh"
    disable_response_storage = true
    network_access = "enabled"
    windows_wsl_setup_acknowledged = true
    model_context_window = 1000000
    model_auto_compact_token_limit = 900000

    [model_providers.OpenAI]
    name = "OpenAI"
    base_url = "https://re.94xy.cn"
    wire_api = "responses"
    requires_openai_auth = true

~/.codex/auth.json

    {
      "OPENAI_API_KEY": "YOUR_API_KEY"
    }

## OpenCode

OpenCode 建议写入 `opencode.json`。OpenAI 分组的核心是 `provider.openai.options.baseURL` 与 `apiKey`。

opencode.json

    {
      "provider": {
        "openai": {
          "options": {
            "baseURL": "https://re.94xy.cn/v1",
            "apiKey": "YOUR_API_KEY"
          }
        }
      },
      "agent": {
        "build": {
          "options": {
            "store": false
          }
        },
        "plan": {
          "options": {
            "store": false
          }
        }
      },
      "$schema": "https://opencode.ai/config.json"
    }

## OpenClaw

OpenClaw 当前推荐按 `~/.openclaw/openclaw.json` 的 `models.providers` 写自定义 Provider。这里采用站内实际生成格式：OpenAI 分组使用 `api: "openai-responses"`。

~/.openclaw/openclaw.json

    {
      "env": {
        "SUB2API_API_KEY": "YOUR_API_KEY"
      },
      "agents": {
        "defaults": {
          "model": {
            "primary": "sub2api-openai/gpt-5.4"
          }
        }
      },
      "models": {
        "mode": "merge",
        "providers": {
          "sub2api-openai": {
            "baseUrl": "https://re.94xy.cn/v1",
            "apiKey": "${SUB2API_API_KEY}",
            "api": "openai-responses",
            "models": [
              { "id": "gpt-5.4", "name": "GPT-5.4" },
              { "id": "gpt-5.4-mini", "name": "GPT-5.4 Mini" },
              { "id": "gpt-5.3-codex", "name": "GPT-5.3 Codex" }
            ]
          }
        }
      }
    }

参考 OpenClaw 官方模型提供者文档：自定义 Provider 建议放在 `models.providers` 下，并按实际后端选择 `openai-responses` 或其他 API 类型。

## Hermes

Hermes 当前版本以 `~/.hermes/config.yaml` 为准。官方文档已经明确：旧的 `OPENAI_BASE_URL` / `LLM_MODEL` 环境变量不再作为主配置来源。

~/.hermes/config.yaml

    model:
      default: gpt-5.4
      provider: custom
      base_url: https://re.94xy.cn/v1
      api_key: YOUR_API_KEY

交互式配置

    hermes model
    # 选择 "Custom endpoint (self-hosted / VLLM / etc.)"
    # API base URL: https://re.94xy.cn/v1
    # API key: YOUR_API_KEY
    # Model name: gpt-5.4

当前 Hermes 的自定义端点以 `config.yaml` 为单一事实来源。不要再依赖旧版 `.env` 里的 `OPENAI_BASE_URL`。

## 常见问题

问题 | 排查方向
--- | ---
CC-Switch 一键导入没有拉起 | 确认已安装 CC-Switch，且系统已注册 `ccswitch://` 协议；否则先走安装。
`401` / `invalid_api_key` | 检查 Key 是否从 `/keys` 复制完整，确认没有多空格、换行或旧 Key。
`403` | 密钥可能被禁用、触发 IP 限制，或当前分组不可用。
`404` | 大多数是 Host 或路径写错。HTTP / SDK 常用 `/v1`；Claude / Gemini / Codex CLI 多数写根 Host。
Hermes / OpenClaw 不工作 | 先确认配置文件路径正确，再确认 Host 是否按当前客户端格式填写。OpenClaw 看 `openclaw.json`，Hermes 看 `~/.hermes/config.yaml`。