接入 TOPAPI Connect to TOPAPI

三个必填项Three required fields

不同软件按钮文案不同，但本质上都在要这三样。 Labels differ by app, but they always ask for the same three values.

选择你的工具Choose your tool

点进对应章节，复制命令即可。 Open the matching section and copy the commands.

CC Switch

CC Switch 是跨平台桌面工具，可统一管理 Claude Code、Codex、Grok Build、OpenClaw、Hermes 等配置。推荐先安装 CC Switch，再从 TOPAPI 控制台一键导入密钥。 CC Switch is a cross-platform desktop app for managing Claude Code, Codex, Grok Build, OpenClaw, Hermes, and more. Install it first, then import your TOPAPI key from the console in one click.

下载与安装Download & install

brew install --cask cc-switch

方式一：控制台一键导入（推荐）Option 1: One-click import from console (recommended)

方式二：在 CC Switch 中手动添加Option 2: Add manually in CC Switch

在 CC Switch 中为对应应用添加 Provider，填写 TOPAPI 的 API Key 与 Base URL： In CC Switch, add a provider for the target app and fill in your TOPAPI API key and Base URL:

Grok Build

Grok Build 是 xAI 官方终端编码 Agent（命令 grok）。安装后把推理地址指到 TOPAPI，即可用 TOPAPI Key 调用 Grok 系列模型。 Grok Build is xAI’s official terminal coding agent (command grok). Point its inference base URL at TOPAPI and use your TOPAPI key with Grok models.

下载与安装Download & install

curl -fsSL https://x.ai/cli/install.sh | bash

irm https://x.ai/cli/install.ps1 | iex

npm install -g @xai-official/grok

接入 TOPAPIConnect to TOPAPI

export GROK_MODELS_BASE_URL="https://api.topopenai.com/v1"
export XAI_API_KEY="YOUR_API_KEY"

$env:GROK_MODELS_BASE_URL = "https://api.topopenai.com/v1"
$env:XAI_API_KEY = "YOUR_API_KEY"

[endpoints]
models_base_url = "https://api.topopenai.com/v1"

[auth]
preferred_method = "api_key"

[model."grok-4.6"]
model = "grok-4.6"
name = "Grok 4.6"
env_key = "XAI_API_KEY"
api_backend = "responses"
context_window = 500000

[model."grok-build-0.1"]
model = "grok-build-0.1"
name = "Grok Build"
env_key = "XAI_API_KEY"
api_backend = "responses"
context_window = 256000

[models]
default = "grok-4.6"
web_search = "grok-4.6"

grok inspect
grok -p "用一句话介绍 TOPAPI" -m grok-4.6

Pi

Pi 是轻量可扩展的终端编码 Agent（pi.dev）。通过 ~/.pi/agent/models.json 添加 OpenAI 兼容 Provider，即可接入 TOPAPI。 Pi is a minimal, extensible terminal coding agent (pi.dev). Add an OpenAI-compatible provider in ~/.pi/agent/models.json to route through TOPAPI.

下载与安装Download & install

curl -fsSL https://pi.dev/install.sh | sh

irm https://pi.dev/install.ps1 | iex

接入 TOPAPIConnect to TOPAPI

编辑配置文件（Linux / macOS：~/.pi/agent/models.json；Windows：%USERPROFILE%\.pi\agent\models.json），添加 TOPAPI Provider： Edit the config file (Linux/macOS: ~/.pi/agent/models.json; Windows: %USERPROFILE%\.pi\agent\models.json) and add a TOPAPI provider:

{
  "providers": {
    "topapi": {
      "baseUrl": "https://api.topopenai.com/v1",
      "api": "openai-completions",
      "apiKey": "YOUR_API_KEY",
      "models": [
        {
          "id": "gpt-5.6",
          "name": "GPT-5.6 via TOPAPI"
        },
        {
          "id": "claude-opus-5",
          "name": "Claude Opus via TOPAPI"
        },
        {
          "id": "grok-4.6",
          "name": "Grok 4.6 via TOPAPI"
        },
        {
          "id": "gpt-image-2",
          "name": "GPT Image 2 via TOPAPI"
        }
      ]
    }
  }
}

# 若 models.json 里用了环境变量引用，可先导出：
# export TOPAPI_API_KEY="YOUR_API_KEY"
pi --provider topapi -p "用一句话介绍 TOPAPI"

# If models.json references an env var, export it first:
# $env:TOPAPI_API_KEY = "YOUR_API_KEY"
pi --provider topapi -p "用一句话介绍 TOPAPI"

Codex

优先使用一键脚本。脚本会安装或配置 Codex，并写入 TOPAPI 地址。 Prefer the installer. It installs or configures Codex and writes the TOPAPI endpoint.

curl -fsSL https://api.topopenai.com/install/codex.sh | sudo bash

irm https://api.topopenai.com/install/codex.ps1 | iex

运行后按提示填入 TOPAPI Key。能正常对话即表示接入成功。 Paste your TOPAPI key when prompted. A normal reply means setup succeeded.

脚本失败时的手动配置Manual config if the script fails

mkdir -p ~/.codex
cat > ~/.codex/config.toml <<'EOF'
model = "gpt-5.6"
model_provider = "openai"
openai_base_url = "https://api.topopenai.com/v1"
cli_auth_credentials_store = "file"
forced_login_method = "api"
EOF

cat > ~/.codex/auth.json <<'EOF'
{"OPENAI_API_KEY":"YOUR_API_KEY"}
EOF

Claude Code

使用 Anthropic 协议。Base URL 填 https://api.topopenai.com，不要加 /v1。 Uses the Anthropic protocol. Set Base URL to https://api.topopenai.com without /v1.

export ANTHROPIC_BASE_URL="https://api.topopenai.com"
export ANTHROPIC_AUTH_TOKEN="YOUR_API_KEY"
export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1
claude

$env:ANTHROPIC_BASE_URL = "https://api.topopenai.com"
$env:ANTHROPIC_AUTH_TOKEN = "YOUR_API_KEY"
$env:CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC = "1"
claude

Cursor

在 Cursor 中通过「覆盖 OpenAI Base URL」接入 TOPAPI。Cursor 侧需要用模型映射：在设置里添加短名称，例如 g-5.6、cc-5、g-4.6，分别对应 gpt-5.6、claude-opus-5、grok-4.6。 Point Cursor at TOPAPI with Override OpenAI Base URL. Cursor requires model mapping: add short names such as g-5.6, cc-5, and g-4.6 for gpt-5.6, claude-opus-5, and grok-4.6.

配置步骤Setup steps

模型映射（必做）Model mapping (required)

Cursor 通过自定义模型名发请求。请在 Cursor 中添加右侧短名称；网关侧按 短名称 → 真实模型 映射（写法：真实模型 = 短名称）。 Cursor sends the custom model name you add. Register the short name in Cursor; on the gateway map short name → real model (notation: real model = short name).

TRAE / OpenClaw / Hermes

在「添加模型 / 自定义 Provider / API Provider」中填写 Key、地址与模型。按协议类型选对 Base URL。 In add model / custom provider / API provider, fill key, endpoint, and model. Match the Base URL to the protocol.

OpenClaw

export OPENAI_API_KEY="YOUR_API_KEY"
openclaw onboard --auth-choice custom-api-key \
  --custom-base-url https://api.topopenai.com/v1 \
  --custom-api-key-env OPENAI_API_KEY \
  --custom-compatibility openai \
  --custom-model gpt-5.6

export ANTHROPIC_API_KEY="YOUR_API_KEY"
openclaw onboard --auth-choice custom-api-key \
  --custom-base-url https://api.topopenai.com \
  --custom-api-key-env ANTHROPIC_API_KEY \
  --custom-compatibility anthropic \
  --custom-model claude-opus-5

速查表Quick reference

只给你几个输入框时，对照这张表。 Use this table when an app only exposes a few fields.

API 示例API examples

面向直接写代码的调用方。只配置 CLI / 桌面工具时可跳过。 For direct HTTP/SDK calls. Skip if you only configure CLI or desktop tools.

curl https://api.topopenai.com/v1/responses \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6",
    "input": "用中文简单介绍一下 TOPAPI。"
  }'

curl https://api.topopenai.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6",
    "messages": [
      {"role": "user", "content": "用一句话介绍 TOPAPI。"}
    ]
  }'

curl https://api.topopenai.com/v1/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-opus-5",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "用中文简单介绍一下 TOPAPI。"}
    ]
  }'

const response = await fetch("https://api.topopenai.com/v1/chat/completions", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    model: "gpt-5.6",
    messages: [{ role: "user", content: "用一句话介绍 TOPAPI。" }]
  })
});

console.log(await response.json());

curl https://api.topopenai.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "生成一张极简风格的 TOPAPI 产品图",
    "size": "1024x1024"
  }'

排错Troubleshooting

一次只改一项：Key → 地址 → 模型名。 Change one thing at a time: key → endpoint → model name.