OpenAI / Claude 兼容中转网关
技术文档 · 按任务接入

1A1API 接入
实战手册

不用从头背文档。先选你正在用的工具,再按“复制哪段、填在哪里、成功标志”一步步完成 Claude Code、Codex CLI、CC Switch、OpenCode、OpenClaw、Hermes 等工具接入。

推荐路线

先跑通,再接项目

  1. 创建或复制 API Key
  2. 按工具选择 Base URL
  3. 用最小请求测试 ok
  4. 看调用日志定位慢和贵
看快速开始
先选任务

你现在要把 1A1API 接到哪里?

不用先读完整篇文档。先点你正在使用的工具,每张卡片都标明该复制哪段、填到哪里、怎么判断成功。

Claude Code / Anthropic SDK

我要接 Claude 模型

适合 Claude Code、Claude SDK、CC Switch 的 Claude provider。关键是 Base URL 走 root:https://api.1a1api.top

复制
Claude Code 环境变量
填到
终端或 CC Switch Claude provider
成功
回复 ok,不再 401 / 404
去配置 Claude →
Codex CLI / Responses

我要接 Codex

适合 Codex CLI、Responses API 和长任务工程执行。关键是 Base URL 通常不带 /v1,由客户端拼接接口。

复制
~/.codex/config.toml
填到
Codex 本机配置和 auth.json
成功
新开 Codex 后能正常回复
去看 Codex 配置 →
OpenCode Desktop

我要接 OpenCode

适合用图形界面添加自定义提供商。基础 URL 填 https://1a1api.top/v1,模型填当前订阅可用名称。

复制
API Key 与测试提示词
填到
OpenCode 设置 → 提供商
成功
模型选择器出现 1a1api 分组
去看图文教程 →
CC Switch

我要一键导入 CCS

适合不想手填配置的用户。在 1A1API API 密钥列表点击“导入到 CCS”,让浏览器唤起 CC Switch。

复制
不用复制,按钮自动生成
填到
CC Switch provider
成功
健康检查 / Stream Check 通过
去看导入流程 →
OpenAI SDK / curl

我要先跑通一次 API

适合排除是不是 Key、分组、模型权限的问题。先用最小 curl 测试,再接入项目。

复制
Chat / Responses curl
填到
本机终端
成功
返回一句正常文本
去快速开始 →
401 / 404 / 429 / 524

我现在正在报错

适合已经复制配置但跑不通的情况。先按错误码定位:鉴权、模型、额度、超时是四类完全不同的问题。

先看
错误码和 Base URL
再看
调用日志与分组权限
最后
切最小请求复测
去排错速查 →
主要路径

四条接入路径,按工具选

不同工具走不同的接口形态。先按下面四条路径找到你的入口,再跳转到具体章节。

报错速查

先按错误码分流,不要反复乱改配置

遇到报错时先看类型。很多问题不是模型坏了,而是 Key、Base URL、模型名、额度或超时策略选错了。

客户端下载

先装工具,再接入 1A1API

这里放官方入口和项目 Releases。小白优先点“官方下载 / 官方文档”,需要指定系统安装包时再去 GitHub Releases。

OC
Desktop / Terminal

OpenCode

开源 AI 编程 Agent,有终端版、桌面 Beta 和编辑器扩展。本页 OpenCode 订阅教程就基于 Desktop 自定义提供商配置。

curl -fsSL https://opencode.ai/install | bash
  • 桌面版支持 macOS / Windows / Linux Beta。
  • 终端版也可用 npm、bun、brew 安装。
CS
Multi-App Manager

CC Switch

统一管理 Claude Code、Codex、OpenCode、OpenClaw、Gemini CLI 和 Hermes Agent 的供应商、模型和切换流程。

安装后可在 1A1API API 密钥页点击“导入到 CCS”
  • 优先从官网进入,避免下载到仿站。
  • 需要旧版或具体安装包时看 Releases。
CC
Desktop / CLI

Claude Code

Claude 官方代码助手。桌面版适合可视化使用,CLI 适合终端用户和自动化脚本。

irm https://claude.ai/install.ps1 | iex
  • Windows 可用 WinGet:winget install Anthropic.ClaudeCode
  • macOS / Linux / WSL 可用官方安装脚本。
CX
App / CLI

Codex

OpenAI 的本地编码 Agent。CLI 适合长任务和工程执行,桌面 / ChatGPT 入口适合可视化使用。

npm install -g @openai/codex
  • macOS 可用 Homebrew:brew install --cask codex
  • Windows / WSL 用户先看官方 Windows 指南。
主要接口 /v1/chat/completions

传统 OpenAI 兼容聊天接口。

Agent 接口 /v1/responses

适合 Codex、Claude Code、OpenCode。

推荐模式 stream: true

长任务更稳,也更不容易超时。

快速接入

快速开始

三步跑通:创建 API Key、选对 Base URL、发起一次测试请求。

01

创建 API Key

打开 1A1API 控制台,进入“API 密钥”页面,点击新建并复制 sk- 开头的 Key 自行保管。

不要把 API Key 写进前端代码、公开仓库、截图或聊天记录,更不要发到任何公开教程或群里。
02

选择 Base URL

OpenAI SDK 用 https://1a1api.top/v1;Codex / Responses 客户端用 root https://1a1api.top;Claude Code / Anthropic SDK 用 https://api.1a1api.top

03

开启流式输出

长文本、代码生成、Agent 任务建议启用 stream: true

如大型项目、长时间 Agent 任务或大图生成遇到 Cloudflare 报错,可尝试使用备用接口 https://api.1a1api.top/v1 连接;部分地区访问该接口可能需要代理或翻墙。
curl 测试 Chat Completions
curl https://1a1api.top/v1/chat/completions \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "messages": [
      {
        "role": "user",
        "content": "用一句话介绍 1A1API。"
      }
    ],
    "stream": true
  }'
curl 测试 Responses API
curl https://1a1api.top/v1/responses \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "input": "Reply with exactly: ok",
    "stream": true
  }'
模型与接口

模型与接口

实际可用模型以你的 API Key 所属分组权限为准。

gpt-5.5 gpt-5.4 gpt-5.4-mini gpt-5.3-codex claude-opus-4-7 claude-sonnet-4-6 claude-haiku-4-5 gpt-image-1 gpt-image-1.5 gpt-image-2

Chat Completions

适合传统 OpenAI 兼容客户端,也可以调用被分组授权的 Claude 模型映射。

POST /v1/chat/completions

Responses API

适合 Agent、Coding、长上下文和工具调用类客户端。

POST /v1/responses

Claude Messages

适合 Claude SDK、Claude Code、CC Switch 的 Claude provider。

POST /v1/messages

Images

适合图像生成和 Agent 工作流中的图片任务。

POST /v1/images/generations
Claude 模型接入

Claude 模型怎么接入 1A1API

Claude 模型有两条接入路线:普通程序优先走 OpenAI 兼容接口;Claude Code、CC Switch、Anthropic SDK 这类工具优先走 Claude Messages 接口。

适合谁 Claude Code、Anthropic SDK、CC Switch Claude provider

你想用 Claude 系列模型写代码、做长文分析或接入已有 Claude 工具。

复制哪段 Claude Code 环境变量 / Messages curl

不会写配置时,先复制环境变量到终端临时测试,确认通了再固化到工具。

填在哪里 ANTHROPIC_BASE_URL 或 provider Base URL

Claude Code / Anthropic SDK 用 https://api.1a1api.top;不要手动补 /v1/messages

成功标志 最小请求返回 ok

如果 401 看 Key,403 看分组权限,404 看 Base URL 和模型名。

01

确认 Key 所在分组

先确认当前 API Key 的分组已经开通 Claude 模型。没有权限时通常会返回 403 或模型不存在。

02

选择接入方式

OpenAI SDK 用 https://1a1api.top/v1;Claude Code / Anthropic SDK 用 https://api.1a1api.top

03

用最小请求测试

先发一句 Reply with exactly: ok,确认能返回,再放进项目或 Agent 工作流里。

claude-opus-4-7复杂推理、架构设计、长任务复核,成本更高。
claude-sonnet-4-6日常编码、文案、客服、知识库问答的主力选择。
claude-haiku-4-5分类、摘要、批量轻任务、低成本自动化。
Base URL 容易写错:OpenAI 兼容接口一般写到 /v1;Claude Messages / Claude Code 通常写 root,不要手动追加 /v1/messages,客户端会自己拼端点。
Anthropic Messages curl 测试
export ANTHROPIC_API_KEY="sk-your-api-key"

curl https://api.1a1api.top/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 256,
    "messages": [
      {
        "role": "user",
        "content": "Reply with exactly: ok"
      }
    ]
  }'
OpenAI 兼容方式调用 Claude 模型
export OPENAI_API_KEY="sk-your-api-key"

curl https://1a1api.top/v1/chat/completions \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "messages": [
      {
        "role": "user",
        "content": "Reply with exactly: ok"
      }
    ],
    "stream": true
  }'
Claude Code 临时环境变量接入
export ANTHROPIC_BASE_URL="https://api.1a1api.top"
export ANTHROPIC_AUTH_TOKEN="sk-your-api-key"
export ANTHROPIC_MODEL="claude-sonnet-4-6"
export ANTHROPIC_DEFAULT_OPUS_MODEL="claude-opus-4-7"
export ANTHROPIC_DEFAULT_SONNET_MODEL="claude-sonnet-4-6"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="claude-haiku-4-5"
export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1

claude
Claude 模型能不能用 OpenAI SDK 调?

可以,但前提是当前分组给这个模型做了 OpenAI 兼容映射。最稳的是先用上面的 curl 测试,成功后再放进 SDK。

api.1a1api.top1a1api.top 怎么选?

OpenAI SDK、Chat Completions、Images 优先用 https://1a1api.top/v1;Claude Code、Anthropic SDK、Claude Messages 优先用 https://api.1a1api.top

报 404 或重复 /v1/v1 怎么办?

把 Base URL 改回 root 或 /v1 中正确的那个。Claude Code 这类客户端通常不要在 Base URL 里写 /v1/messages

终端与客户端配置

使用 API 密钥里的配置方式

下面按你在 Sub2API“使用 API 密钥”弹窗里实际添加的终端类型整理,普通用户可以直接按对应工具复制。

Codex CLI

写入 ~/.codex/config.toml~/.codex/auth.json,走 OpenAI Responses。

Codex WebSocket

在 Codex CLI 基础上启用 supports_websocketsresponses_websockets_v2

Claude Code(环境变量)

官方推荐用 ANTHROPIC_BASE_URL + ANTHROPIC_AUTH_TOKEN 接入第三方网关,不需要写 ~/.claude/config.toml

CC Switch

把 1A1API 添加为 Claude / Codex provider,一键切换当前终端工具使用的模型。

OpenCode

写入 opencode.json,模型定义和 provider 一起配置。

OpenClaw

合并到 ~/.openclaw/openclaw.json,不要覆盖已有配置。

Hermes Agent

写入 ~/.hermes/config.yaml~/.hermes/.env

~/.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_context_window = 1000000
model_auto_compact_token_limit = 900000

[model_providers.OpenAI]
name = "OpenAI"
base_url = "https://1a1api.top"
wire_api = "responses"
requires_openai_auth = true
~/.codex/auth.json
{
  "OPENAI_API_KEY": "sk-your-api-key"
}
model_reasoning_effort = "xhigh" 是 1A1API / Codex CLI 这类客户端识别的扩展配置项,并非所有官方 OpenAI SDK 的通用参数。直接拿到 OpenAI 官方 SDK 里调用普通模型时,标准取值通常只有 lowmediumhighxhigh 仅在 1A1API 中转 + 兼容客户端的组合下生效。
~/.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_context_window = 1000000
model_auto_compact_token_limit = 900000

[model_providers.OpenAI]
name = "OpenAI"
base_url = "https://1a1api.top"
wire_api = "responses"
supports_websockets = true
requires_openai_auth = true

[features]
responses_websockets_v2 = true
只有客户端版本支持 Responses WebSocket 时再使用这个模板;不确定时优先用普通 Codex CLI 模板。

Claude Code 官方对第三方网关的推荐做法是注入环境变量,而不是手写 ~/.claude/config.toml。下面给出 macOS / Linux 与 Windows 两种写法,任选一种放进 shell 配置即可。

macOS / Linux:~/.zshrc 或 ~/.bashrc
export ANTHROPIC_BASE_URL="https://api.1a1api.top"
export ANTHROPIC_AUTH_TOKEN="sk-your-api-key"
export ANTHROPIC_MODEL="claude-sonnet-4-6"
export ANTHROPIC_DEFAULT_OPUS_MODEL="claude-opus-4-7"
export ANTHROPIC_DEFAULT_SONNET_MODEL="claude-sonnet-4-6"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="claude-haiku-4-5"
export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1

# 改完后 source ~/.zshrc 或重开终端,再运行
claude
Windows PowerShell(当前会话)
$env:ANTHROPIC_BASE_URL="https://api.1a1api.top"
$env:ANTHROPIC_AUTH_TOKEN="sk-your-api-key"
$env:ANTHROPIC_MODEL="claude-sonnet-4-6"
$env:ANTHROPIC_DEFAULT_OPUS_MODEL="claude-opus-4-7"
$env:ANTHROPIC_DEFAULT_SONNET_MODEL="claude-sonnet-4-6"
$env:ANTHROPIC_DEFAULT_HAIKU_MODEL="claude-haiku-4-5"
$env:CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC="1"

claude
Base URL 用 root,不要追加 /v1/messagesClaude Code 会自己拼端点,所以 ANTHROPIC_BASE_URL 写到 https://api.1a1api.top 即可;写成 https://api.1a1api.top/v1 会出现 /v1/v1/messages 这类 404。
不要再去手写 ~/.claude/config.toml那是第三方代理或 Codex 风格客户端的写法,官方 Claude Code CLI 并不读取这个文件,照抄会导致看似配置完成但实际还在调官方 Anthropic。如果你用的是 CC Switch 或 Claude Code Router 这类工具,它们会自己生成对应配置,请按它们的文档操作。
OpenCode 示例
{
  "provider": {
    "openai": {
      "options": {
        "baseURL": "https://1a1api.top/v1",
        "apiKey": "sk-your-api-key"
      },
      "models": {
        "gpt-5.5": {
          "name": "GPT-5.5",
          "limit": {
            "context": 1050000,
            "output": 128000
          },
          "options": {
            "store": false
          },
          "variants": {
            "low": {},
            "medium": {},
            "high": {},
            "xhigh": {}
          }
        },
        "gpt-5.4": {
          "name": "GPT-5.4",
          "limit": {
            "context": 1050000,
            "output": 128000
          },
          "options": {
            "store": false
          },
          "variants": {
            "low": {},
            "medium": {},
            "high": {},
            "xhigh": {}
          }
        },
        "gpt-5.4-mini": {
          "name": "GPT-5.4 Mini",
          "limit": {
            "context": 400000,
            "output": 128000
          },
          "options": {
            "store": false
          },
          "variants": {
            "low": {},
            "medium": {},
            "high": {},
            "xhigh": {}
          }
        },
        "gpt-5.3-codex": {
          "name": "GPT-5.3 Codex",
          "limit": {
            "context": 400000,
            "output": 128000
          },
          "options": {
            "store": false
          },
          "variants": {
            "low": {},
            "medium": {},
            "high": {},
            "xhigh": {}
          }
        }
      }
    }
  },
  "agent": {
    "build": {
      "options": {
        "store": false
      }
    },
    "plan": {
      "options": {
        "store": false
      }
    }
  },
  "$schema": "https://opencode.ai/config.json"
}
~/.openclaw/openclaw.json
{
  "models": {
    "mode": "merge",
    "providers": {
      "sub2api-openai": {
        "baseUrl": "https://1a1api.top/v1",
        "apiKey": "sk-your-api-key",
        "api": "openai-completions",
        "authHeader": true,
        "models": [
          {
            "id": "gpt-5.5",
            "name": "GPT-5.5",
            "api": "openai-completions",
            "reasoning": true,
            "input": ["text", "image"],
            "cost": {
              "input": 0,
              "output": 0,
              "cacheRead": 0,
              "cacheWrite": 0
            },
            "contextWindow": 272000,
            "maxTokens": 128000
          },
          {
            "id": "gpt-5.4",
            "name": "GPT-5.4",
            "api": "openai-completions",
            "reasoning": true,
            "input": ["text", "image"],
            "cost": {
              "input": 0,
              "output": 0,
              "cacheRead": 0,
              "cacheWrite": 0
            },
            "contextWindow": 272000,
            "maxTokens": 128000
          },
          {
            "id": "gpt-5.3-codex",
            "name": "GPT-5.3 Codex",
            "api": "openai-completions",
            "reasoning": true,
            "input": ["text", "image"],
            "cost": {
              "input": 0,
              "output": 0,
              "cacheRead": 0,
              "cacheWrite": 0
            },
            "contextWindow": 272000,
            "maxTokens": 128000
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "sub2api-openai/gpt-5.5"
      }
    }
  }
}
如果 openclaw.json 已存在,只合并 models.providersagents.defaults.models 相关片段,不要整文件覆盖。
~/.hermes/config.yaml
model:
  default: "gpt-5.5"
  provider: "custom"
  base_url: "https://1a1api.top/v1"
~/.hermes/.env
OPENAI_API_KEY="sk-your-api-key"
Hermes 官方目前不支持原生 Windows,建议在 macOS、Linux 或 WSL2 中使用。
OpenAI JavaScript SDK
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
  baseURL: "https://1a1api.top/v1",
});

const response = await client.chat.completions.create({
  model: "gpt-5.5",
  messages: [
    { role: "user", content: "Reply with exactly: ok" },
  ],
});

console.log(response.choices[0]?.message?.content);
OpenAI Python SDK
from openai import OpenAI

client = OpenAI(
    api_key="sk-your-api-key",
    base_url="https://1a1api.top/v1",
)

response = client.chat.completions.create(
    model="gpt-5.5",
    messages=[
        {"role": "user", "content": "Reply with exactly: ok"}
    ],
)

print(response.choices[0].message.content)
OpenCode 图文订阅

OpenCode 订阅 1A1API 模型教程

这份教程适合已经开通 1A1API 订阅或已有可用额度的用户,把 1A1API 模型接入 OpenCode Desktop 使用。照着做完后,就能在 OpenCode 里选择 1A1API 的模型对话和编程。

适合谁 习惯图形界面、不想改配置文件的用户

OpenCode Desktop 可以在设置里添加自定义提供商,适合客户演示和日常编程。

复制哪段 API Key、基础 URL、模型名

Key 从 1A1API 后台复制;基础 URL 用 https://1a1api.top/v1;模型名以套餐可用列表为准。

填在哪里 OpenCode 设置 → 服务器 → 提供商

选择自定义提供商,ID 可填 1a1api,显示名称填 1A1API

成功标志 模型选择器出现 1a1api 分组

发送测试句后能正常回复;看不到模型时先重启 OpenCode,再检查模型 ID。

开始前准备

  • 已安装 OpenCode Desktop。
  • 已登录 1A1API 后台。
  • 账号内有可用订阅、余额或额度。
  • 准备复制一个 sk- 开头的 API 密钥。

安全提醒

API 密钥只粘贴到 OpenCode 的 API 密钥输入框,不要发到群里、聊天窗口、公开截图或公开仓库。下面截图中的密钥已做脱敏处理。

01

在 1A1API 创建 API 密钥

登录 1A1API 后台,在左侧菜单点击“API 密钥”,进入后点击右上角“+ 创建密钥”。创建完成后,在密钥列表里找到新密钥并点击复制按钮。

02

打开 OpenCode 设置

启动 OpenCode Desktop,在左下角点击齿轮图标进入设置。在“服务器”下进入“提供商”,找到“自定义提供商”,点击“+ 连接”。

03

添加 1A1API 提供商

提供商 ID 填 1a1api,显示名称填 1A1API,基础 URL 填 https://1a1api.top/v1,API 密钥粘贴刚才复制的 Key,模型填当前订阅可用模型。

04

选择模型并测试

回到 OpenCode 主界面,在输入框附近点击模型选择器,找到 1a1api 分组,选择 GPT-5.5 或你的订阅模型。

提供商 ID1a1api
显示名称1A1API
基础 URLhttps://1a1api.top/v1
API 密钥粘贴 1A1API 后台复制的 sk-... 密钥。
模型填写订阅分组支持的模型名,例如 GPT-5.5gpt-5.5
测试语句让模型回复“我正在通过 1A1API 在 OpenCode 中工作”。
模型名以你的 1A1API 后台、套餐说明或模型列表为准。显示名称只是给自己看的名字,模型 ID 才是请求时真正使用的名称;如果提示模型不存在,优先检查模型 ID 的大小写和连字符。
OpenCode 接入测试提示词
你好,请用一句话回复:我正在通过 1A1API 在 OpenCode 中工作。
1A1API 后台 API 密钥入口
图 1 进入 API 密钥页面

登录后台后,在左侧菜单点击“API 密钥”。

点击创建 API 密钥按钮
图 2 点击“+ 创建密钥”

在 API 密钥页面右上角创建新密钥。

复制 1A1API API 密钥
图 3 复制 API 密钥

密钥一般只显示部分内容,完整内容以复制结果为准。

OpenCode 左下角设置入口
图 4 打开 OpenCode 设置

在 OpenCode Desktop 左下角点击齿轮图标。

OpenCode 自定义提供商连接入口
图 5 连接自定义提供商

进入“服务器 → 提供商”,找到自定义提供商并点击连接。

OpenCode 填写 1A1API 自定义提供商配置
图 6 填写 1A1API 提供商配置

按上方表格填写 ID、名称、基础 URL、API 密钥和模型。

OpenCode 主界面打开模型选择器
图 7 回到主界面选择模型

点击输入框附近的模型选择器。

OpenCode 选择 1a1api 分组中的 GPT-5.5 模型
图 8 选择 1a1api 分组模型

选择 GPT-5.5 或当前订阅可用的其他模型。

提示 API key 无效或 401 怎么办?

检查 API 密钥是否复制完整,是否粘贴到了“API 密钥”输入框,账号是否还有可用额度。

提示模型不存在或 404 怎么办?

大多数情况是模型名称填错了。回到 1A1API 后台或套餐说明里确认模型 ID,注意大小写和连字符。

提示额度不足、429 或 rate limit 怎么办?

说明当前密钥、账号、分组或订阅额度可能已经用完,或者短时间请求太多。可以先等待一会儿再试,或检查 1A1API 后台额度。

OpenCode 里看不到刚添加的模型怎么办?

回到“设置 → 服务器 → 提供商”确认 1A1API 配置还在;如果仍然不显示,可以重启 OpenCode Desktop 后再打开模型选择器。

基础 URL 应该填哪个?

本教程按截图填写 https://1a1api.top/v1。如果你的后台单独提供了其他 OpenAI 兼容地址,以后台当前显示为准,但末尾通常需要带 /v1

CC Switch 接入

把 API 密钥一键导入 CC Switch

1A1API / Sub2API 的“API 密钥”列表里有“导入到 CCS”按钮。它会根据这个密钥所属分组,自动生成 CC Switch 能识别的 ccswitch://v1/import 链接,比手动复制 Base URL、模型和 Key 更不容易填错。

适合谁 同时使用 Claude Code、Codex、Gemini、OpenCode 的用户

CC Switch 的价值是集中管理 provider,减少到处改环境变量和配置文件。

推荐入口 API 密钥列表里的“导入到 CCS”

按钮会根据密钥分组自动带 app、endpoint、model 和用量查询脚本。

确认什么 应用类型、endpoint、默认模型

Claude 走 app=claude,Codex 走 app=codex,不要把两者混用。

成功标志 健康检查 / Stream Check 通过

Codex 切换后建议重开终端;Claude Code 一般更容易热切换。

推荐用法

先安装 CC Switch,再去 1A1API 控制台的“API 密钥”页面点击“导入到 CCS”。浏览器弹出“打开 CC Switch”时允许打开,回到 CC Switch 确认导入即可。

按钮会自动带什么

导入链接会带当前 sk-... Key、站点 API Base URL、provider 名称、客户端类型、用量查询脚本和 30 分钟自动刷新间隔。不要把带真实 Key 的链接发到公开聊天或仓库。

01

安装并打开 CC Switch

先确认系统已经安装 CC Switch,并且浏览器允许打开 ccswitch:// 这种本地协议链接。

02

选对 API 密钥

进入“API 密钥”,确认这个 Key 是启用状态,并且分组对应你要用的工具:Claude Code、Codex、Gemini 或 Antigravity。

03

点击“导入到 CCS”

在密钥右侧操作区点击“导入到 CCS”。如果是 Antigravity 分组,会先让你选择导入为 Claude Code 还是 Gemini CLI。

04

确认导入预览

CC Switch 打开后看清 provider 名称、应用类型、endpoint 和模型,再确认保存。不要把旧 provider 覆盖错。

05

做一次最小验证

Claude Code 问一句 Reply with ok;Codex 切换后建议重开终端;Gemini CLI 也先跑一个最短请求。

Anthropic / Claude 分组自动导入为 app=claude,用于 Claude Code。endpoint 使用后台公开 API Base URL 的 root 地址,不需要手写 /v1/messages
OpenAI / Codex 分组自动导入为 app=codex,用于 Codex CLI。当前 Sub2API 按钮会带默认模型 gpt-5.4;导入后可在 CC Switch 里改成你账号可用的 gpt-5.5 等模型。
Gemini 分组自动导入为 app=gemini。适合 Gemini CLI 或支持 Gemini provider 的工作流。
Antigravity 分组点击按钮后会弹出客户端选择:Claude Code 或 Gemini CLI;endpoint 会自动追加 /antigravity
用量查询导入链接会内置 /v1/usage 查询脚本,并设置 usageAutoInterval=30,方便 CC Switch 定时查看余额 / 剩余额度。
“导入到 CCS”按钮实际会生成的核心字段
resource=provider
app=claude / codex / gemini
name=站点名称,例如 1A1API
homepage=后台公开 API Base URL
endpoint=按密钥分组自动生成
apiKey=当前 API 密钥 sk-...
configFormat=json
usageEnabled=true
usageScript=内置 /v1/usage 用量查询脚本
usageAutoInterval=30

# 只有 OpenAI / Codex 分组会额外带:
model=gpt-5.4
安全提醒:一键导入链接里包含真实 API Key。自己点击可以,截图、发群、写进教程或提交到 GitHub 前,一定要把 apiKey=sk-... 替换成占位符。
手动兜底

按钮不可用时,手动在 CC Switch 里添加

如果浏览器没有唤起 CC Switch,或管理员隐藏了“导入到 CCS”按钮,再用下面的手动方式。手动导入的关键仍然是:先看密钥分组,再选应用类型,最后验证真实请求。

01

复制 API Key

在 1A1API 控制台复制 sk-...,同时看清这个 Key 的分组。不同分组对应的应用和 endpoint 不一样。

02

新增 provider

在 CC Switch 里点击添加供应商。Claude Code 选 Claude,Codex CLI 选 Codex,Gemini CLI 选 Gemini。

03

保存后健康检查

能拉到模型列表最好;拉不到也可以手动填模型 ID。保存后用 Stream Check / 健康检查确认 Key、模型、端点和流式响应正常。

Claude Code应用选 Claude;Base URL 用 https://api.1a1api.top;常用模型 claude-sonnet-4-6claude-opus-4-7claude-haiku-4-5
Codex CLI应用选 Codex;Base URL 用 https://1a1api.top;模型可先用按钮默认的 gpt-5.4,也可改为你账号可用的 gpt-5.5
Gemini CLI应用选 Gemini;Base URL 使用后台显示的 API Base URL;模型按当前分组可用列表填写。
Antigravity如果手动配 Antigravity,endpoint 通常是在后台 API Base URL 后追加 /antigravity
手动导入前先测试模型列表和用量接口
export OPENAI_API_KEY="sk-your-api-key"

# Codex / OpenAI 兼容模型列表
curl https://1a1api.top/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY"

# Claude 兼容模型列表;如果这里不支持模型发现,就在 CC Switch 里手动填写模型名
curl https://api.1a1api.top/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY"

# CC Switch 一键导入会使用类似这个用量接口
curl https://1a1api.top/v1/usage \
  -H "Authorization: Bearer $OPENAI_API_KEY"
手动填写清单
Claude Code:
应用:Claude
供应商名称:1A1API Claude
API 格式:Anthropic Messages
Base URL:https://api.1a1api.top
API Key:sk-your-api-key
获取模型:点模型输入框旁边的下载 / 获取模型按钮
默认模型:claude-sonnet-4-6
验证:点击供应商卡片的健康检查 / Stream Check

Codex CLI:
应用:Codex
供应商名称:1A1API Codex
API 格式:OpenAI Responses
Base URL:https://1a1api.top
API Key:sk-your-api-key
获取模型:点模型输入框旁边的下载 / 获取模型按钮
默认模型:gpt-5.4 或 gpt-5.5
验证:启用后重开 Codex 终端
深度链接模板(只用于排查,不建议手写)
# Claude provider 深度链接结构
ccswitch://v1/import?resource=provider&app=claude&name=1A1API&homepage=https%3A%2F%2Fapi.1a1api.top&endpoint=https%3A%2F%2Fapi.1a1api.top&apiKey=sk-your-api-key&configFormat=json&usageEnabled=true&usageScript=BASE64_USAGE_SCRIPT&usageAutoInterval=30

# Codex provider 深度链接结构
ccswitch://v1/import?resource=provider&app=codex&model=gpt-5.4&name=1A1API&homepage=https%3A%2F%2F1a1api.top&endpoint=https%3A%2F%2F1a1api.top&apiKey=sk-your-api-key&configFormat=json&usageEnabled=true&usageScript=BASE64_USAGE_SCRIPT&usageAutoInterval=30

# 安全建议:
# 1. 公开教程不要放真实 sk-... Key
# 2. 发给团队前先把 apiKey 参数清空或替换成占位符
# 3. 正常用户优先点后台“导入到 CCS”,不要手写这一长串
点击“导入到 CCS”没有反应怎么办?

通常是 CC Switch 未安装、系统没有注册 ccswitch:// 协议,或浏览器拦截了外部应用打开请求。先打开一次 CC Switch,再回浏览器重试;仍不行就用手动填写清单。

为什么导入成了 Codex,不是 Claude?

“导入到 CCS”按 API Key 所属分组判断应用类型。OpenAI 分组会导入 Codex,Anthropic / Claude 分组会导入 Claude。想换应用,先换密钥分组或创建对应分组的新密钥。

为什么一键导入后还要做健康检查?

导入只代表配置写进去了;健康检查会真的发请求,确认 API Key、模型权限、端点、流式响应和网络都正常。

用量不显示怎么办?

一键导入会带 /v1/usage 查询脚本。如果余额不显示,先确认 Key 仍启用、账号有权限访问用量接口、Base URL 没被浏览器或代理拦截。

CC Switch:Claude Code provider 推荐填写
名称:1A1API Claude
类型:Claude / Anthropic / Claude Code
Base URL:https://api.1a1api.top
API Key / Auth Token:sk-your-api-key
默认模型:claude-sonnet-4-6
Opus 模型:claude-opus-4-7
Sonnet 模型:claude-sonnet-4-6
Haiku 模型:claude-haiku-4-5
额外环境变量:CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1
CC Switch:Codex provider 推荐填写
名称:1A1API Codex
类型:OpenAI / Responses / Codex
Base URL:https://1a1api.top
API Key:sk-your-api-key
模型:gpt-5.4 或 gpt-5.5
Review 模型:gpt-5.4 或 gpt-5.5
Reasoning Effort:xhigh
Wire API:responses
disable_response_storage:true
network_access:enabled
切换后手动核对 Codex 配置
# CC Switch 切换后,建议核对这两个文件是否同步
sed -n '1,80p' ~/.codex/config.toml
sed -n '1,40p' ~/.codex/auth.json

# 重点看:
# 1. model_provider 是否为 OpenAI 或你在 CC Switch 里设置的 provider 名
# 2. base_url 是否为 https://1a1api.top
# 3. auth.json 是否写入当前 1A1API 的 sk-... Key
# 4. 已经打开的 codex 窗口不要指望热切换,重开最稳
常见坑:Claude Code 通常能被 CC Switch 热切换;Codex 当前窗口不一定会稳定热更新。切换 Codex provider 后,最稳的方式是关闭当前 Codex 会话,重新打开一个新窗口再测试。
切到 1A1API 后 401 怎么办?

先确认 CC Switch 里填的是 1A1API 的 sk-...,不是旧中转、官方 Key 或过期 Key;再检查 Codex 的 auth.json 是否真的同步。

切到 Claude 模型后 404 怎么办?

多数是 Base URL 写错。Claude provider 用 https://api.1a1api.top,不要写成 https://api.1a1api.top/v1/messages

为什么 CC Switch 切了,Codex 还是旧模型?

Codex 不一定热读取配置。先看 ~/.codex/config.toml 是否变化,再重开 Codex。只看正在运行的旧窗口,容易误判。

新手帮助

图文教程与站内说明

如果用户不熟悉 API、密钥和客户端配置,建议先看图文教程,再回到本页复制终端配置。

分组与计费

分组、余额与订阅

分组决定当前 API 密钥可用的模型、额度规则和调用能力。

分组影响什么

  • 可调用模型
  • 计费倍率
  • 并发能力
  • Responses / Compact 能力

余额和订阅分开计算

余额按实际调用扣费,订阅按套餐规则提供每日额度或周期额度。日志和面板里两者可能分开统计。

调用日志

调用日志怎么看

日志能帮助你判断一次请求走了哪个分组、用了多少 token、花了多少钱、慢在哪里。

用户调用方账号和用户 ID
API 密钥当前使用的 Key 名称
模型例如 gpt-5.5、claude-sonnet-4-6
端点/responses 或 /chat/completions
Token输入、输出、缓存读取
费用本次实际扣费
首 token 耗时模型开始输出前的等待时间
日志里像 541.1K 这种大数字通常表示缓存读取或上下文缓存相关 token,不一定代表本次新输入了 54 万 token。判断贵不贵,优先看“费用”字段。
如果“首 token 耗时”明显变慢,请先检查当前会话上下文是否过长、是否已经接近或超过模型上下文上限。大项目、长对话、反复贴日志或图片生成提示词过长,都可能导致首 token 变慢。
上下文压缩

Compact 模式

控制账号是否参与 /responses/compact 调度。

Auto 跟随系统探测结果,推荐默认使用。
Force On 强制允许该账号参与 compact。
Force Off 强制排除该账号,不走 compact。
模型映射 只在 compact 请求中生效,普通用户通常不用填。
不知道该选什么就保持 Auto。Force On / Force Off 是给确实需要排查或临时验证的账号用的,普通使用者不用动。
推荐做法

推荐最佳实践

大多数客户端优先开启 stream: true
一个项目创建一个独立 API Key,方便统计和风控。
API Key 只放服务端或本地私有配置,不放前端。
大任务拆成摘要、分析、生成、校对几步,更稳定。
故障排查

常见问题与排错

401 Unauthorized

API Key 写错、缺少 Bearer、Key 被删除或禁用。检查 Authorization: Bearer sk-your-api-key

403 Forbidden

分组无权调用模型、余额不足、订阅过期、分组未开启对应调度能力。

404 Not Found

Base URL 写错、客户端重复拼接 /v1、端点不存在。

429 Rate Limited

请求过快、并发过高或当前服务繁忙。建议降低并发、稍后重试;如果持续出现,请把报错时间、模型和 API Key 名称发给客服处理。

522 / 524 Cloudflare 超时

请求很久没有流式返回。优先开启流式、拆分任务;如大型项目、大图生成仍遇到 CF 报错,可尝试把 Base URL 改为 https://api.1a1api.top/v1,部分地区可能需要代理或翻墙。

首 token 很慢

首 token 是模型开始输出前的等待时间。若明显变慢,请先检查上下文是否过长或已经爆上下文;可以新开会话、减少历史记录、压缩日志、拆分文件或降低一次性输入内容后再试。