cb2api 接入文档

一个与 OpenAI API 完全兼容的 CodeBuddy 代理服务。支持标准 /v1/chat/completions 与 /v1/responses 协议，可直接对接 Codex CLI、Cursor、ChatBox、NextChat 等主流客户端。

OpenAI 兼容流式 / 非流式 Responses API 工具调用凭证自动轮换

1接入地址

根据客户端类型选择对应的 Base URL。两种前缀完全等价，任选其一即可。

🌐 当前服务地址

以下地址由当前访问的主机名自动推导，可直接复制使用。

OpenAI 加载中…

Codex 加载中…

根路径加载中…

说明：路径前缀 /v1 与 /codebuddy/v1 指向同一批接口，行为完全一致。旧版客户端若已使用 /codebuddy/v1，无需修改即可继续使用。

2鉴权方式

所有 API 请求通过 Authorization 请求头携带凭证。

🔑 API Key

由服务方签发后分发。请向服务管理员申请密钥；管理员密码同样可直接作为 Key 使用。

# 请求头格式
Authorization: Bearer sk-your-api-key

签发方式：向服务管理员申请，由管理员生成并分发密钥
兼容方式：直接使用 CODEBUDDY_PASSWORD 管理员密码
用量统计：每个 Key 的调用次数与 Token 消耗可由管理员查看

3快速接入

复制即用的调用示例，无需任何 SDK 也可直接测试。

cURL

Python

Node.js

curl … \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-your-api-key" \
  -d '{
    "model": "deepseek-v4.1-flash",
    "messages": [{"role": "user", "content": "你好"}],
    "stream": false
  }'

from openai import OpenAI

client = OpenAI(
    base_url="…",
    api_key="sk-your-api-key",
)

resp = client.chat.completions.create(
    model="deepseek-v4.1-flash",
    messages=[{"role": "user", "content": "你好"}],
)
print(resp.choices[0].message.content)

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "…",
  apiKey: "sk-your-api-key",
});

const resp = await client.chat.completions.create({
  model: "deepseek-v4.1-flash",
  messages: [{ role: "user", content: "你好" }],
});
console.log(resp.choices[0].message.content);

🔑 查询密钥信息

用密钥自身即可查询其状态、用量、额度、有效期与白名单，无需管理员密码。返回内容不含明文密钥与哈希。

curl … \
  -H "Authorization: Bearer sk-your-api-key"

返回字段示例：key_id、name、enabled、 expired、expires_at、tokens_used、 token_quota、tokens_remaining、total_calls、 allowed_models、allowed_ips、last_used_at。

4接口清单

所有接口同时支持 /v1 与 /codebuddy/v1 两种前缀。

📡 对话与模型

方法	路径	说明
POST	`/v1/chat/completions`	Chat Completions，兼容 OpenAI 标准，支持流式与工具调用
POST	`/v1/responses`	Responses API，供 Codex CLI 等新版客户端使用
GET	`/v1/models`	获取可用模型列表
GET	`/v1/key`	查询当前密钥信息（状态、额度、白名单等）
GET	`/health`	健康检查

🔢 可用模型

以下模型来自服务端实时配置，点击可复制。实际可用性取决于账号权益。

加载中…

5客户端配置

常见客户端的接入参数，按客户端要求填写即可。所有客户端共用同一个 API Key。

通用要点： Base URL 统一填 …；密钥填服务管理员签发的 sk-cb-…； Codex / Claude Code 均走各自官方协议（Responses / Messages），模型名可直接沿用客户端默认值，服务端会自动映射到上游模型。

Codex CLI

Claude Code

Cursor / VS Code

ChatBox / NextChat

其它客户端

Codex CLI

编辑 ~/.codex/config.toml，通过 Responses 协议接入。模型名可填 gpt-5-codex、gpt-5.1-codex 等官方名，服务端会自动映射。

model = "gpt-5-codex"
model_provider = "codebuddy"

[model_providers.codebuddy]
name = "cb"
base_url = "…"
wire_api = "responses"
env_key = "CODEBUDDY_KEY"

# macOS / Linux
export CODEBUDDY_KEY="sk-cb-your-key"
codex

# Windows PowerShell
$env:CODEBUDDY_KEY="sk-cb-your-key"
codex

# Windows CMD
set CODEBUDDY_KEY=sk-cb-your-key
codex

配置项	填写值
base_url	`…`
wire_api	`responses`
env_key	`CODEBUDDY_KEY`（任意名称，与导出变量一致即可）
model	`gpt-5-codex` / `gpt-5.1-codex` / `o3` 等

提示：若 codex 启动后报 401，请确认环境变量已生效（可在同一终端执行 echo $CODEBUDDY_KEY / echo %CODEBUDDY_KEY% 验证）。部分版本需要在配置中额外设置 model_provider = "codebuddy" 才会生效。

Claude Code · 快速开始

通过 Anthropic Messages 协议接入。设置以下环境变量后直接运行 claude，客户端默认下发的 claude-sonnet-4-5、claude-3-5-haiku-20241022 等模型名均由服务端自动映射到上游模型，无需改写。

# macOS / Linux
export ANTHROPIC_BASE_URL="…"
export ANTHROPIC_AUTH_TOKEN="sk-cb-your-key"
claude

# Windows PowerShell
$env:ANTHROPIC_BASE_URL="…"
$env:ANTHROPIC_AUTH_TOKEN="sk-cb-your-key"
claude

关键：Base URL 不要带 /v1。 Claude Code 会自行拼接 /v1/messages，多写一层会变成 /v1/v1/messages 导致 404。填写到根路径即可。

环境变量	填写值
`ANTHROPIC_BASE_URL`	`…`
`ANTHROPIC_AUTH_TOKEN`	签发的密钥 `sk-cb-…`
`ANTHROPIC_MODEL`（可选）	强制指定模型名，如 `deepseek-v4.1-flash`
`ANTHROPIC_DEFAULT_OPUS_MODEL`（可选）	「opus」档位实际下发的模型
`ANTHROPIC_DEFAULT_SONNET_MODEL`（可选）	「sonnet」档位实际下发的模型
`ANTHROPIC_DEFAULT_HAIKU_MODEL`（可选）	「haiku」档位实际下发的模型（用于轻量子任务）
`CLAUDE_CODE_SUBAGENT_MODEL`（可选）	子代理（SubAgent）使用的模型

认证说明：请使用 ANTHROPIC_AUTH_TOKEN 而非 ANTHROPIC_API_KEY，前者会作为 Authorization 头传递，与本服务的鉴权方式一致。若此前连接过官方服务，建议先 unset ANTHROPIC_API_KEY 避免冲突。

模型档位怎么选？

Claude Code 内部用 opus / sonnet / haiku 三个档位名来选模型。当 settings.json 里写 "model": "opus" 时，真正下发的模型名由对应的 ANTHROPIC_DEFAULT_*_MODEL 决定。

档位	读取的环境变量	说明
`opus`	`ANTHROPIC_DEFAULT_OPUS_MODEL`	最强档，主对话默认
`sonnet`	`ANTHROPIC_DEFAULT_SONNET_MODEL`	均衡档
`haiku`	`ANTHROPIC_DEFAULT_HAIKU_MODEL`	轻量档，用于标题生成、上下文压缩等

建议直接把模型名写全，别用档位简写。 写 "model": "deepseek-v4.1-flash" 最直观；若用档位简写，务必把三个 ANTHROPIC_DEFAULT_*_MODEL 都设成同一模型，否则切换档位时会静默用到别的模型。

# 三档统一指向同一模型（推荐做法）
export ANTHROPIC_DEFAULT_OPUS_MODEL="deepseek-v4.1-flash"
export ANTHROPIC_DEFAULT_SONNET_MODEL="deepseek-v4.1-flash"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="deepseek-v4.1-flash"
export CLAUDE_CODE_SUBAGENT_MODEL="deepseek-v4.1-flash"

方式二：写入 settings.json（持久化）

不想每次开终端都 export，可以把配置写进 Claude Code 的配置文件。 macOS / Linux 路径为 ~/.claude/settings.json，Windows 为 %USERPROFILE%\.claude\settings.json。

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "sk-cb-your-key",
    "ANTHROPIC_BASE_URL": "…",
    "ANTHROPIC_MODEL": "deepseek-v4.1-flash",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "deepseek-v4.1-flash",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "deepseek-v4.1-flash",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "deepseek-v4.1-flash",
    "CLAUDE_CODE_SUBAGENT_MODEL": "deepseek-v4.1-flash"
  },
  "includeCoAuthoredBy": false,
  "model": "deepseek-v4.1-flash"
}

配置项说明：

model —— 直接写模型全名最稳妥；写 opus 等简写则回落到对应档位变量
includeCoAuthoredBy —— 是否在 git 提交里加协作者署名，设 false 可关闭
不要使用 ANTHROPIC_DEFAULT_*_MODEL_NAME 这类带 _NAME 后缀的变量，客户端不识别

验证是否接入成功

依次执行以下检查，可快速定位问题出在哪一层。

# 1. 确认环境变量已生效
echo $ANTHROPIC_BASE_URL      # 应为根路径，不带 /v1

# 2. 用 cURL 直接验证密钥与端点（Claude Code 同款协议）
curl "…"/v1/messages \
  -H "x-api-key: sk-cb-your-key" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"deepseek-v4.1-flash","max_tokens":64,
       "messages":[{"role":"user","content":"hi"}]}'

# 3. 查询当前密钥的可用模型与额度
curl "…"/v1/key \
  -H "x-api-key: sk-cb-your-key"

第 2 步返回正常说明服务端与密钥都没问题；若此时 Claude Code 仍报错，问题在客户端配置（多为 Base URL 或模型名）。

常见报错对照表

现象	原因与解决
`404 Not Found`	`ANTHROPIC_BASE_URL` 末尾多了 `/v1`，改成根路径即可（客户端会自己拼 `/v1/messages`）
`403 Invalid password`	密钥错误、已被禁用、已过期，或来源 IP 不在该密钥的白名单内
`403 未授权访问模型`	该密钥配置了模型白名单，但请求的模型不在其中。用 `/v1/key` 查看白名单，或在管理面板放宽限制
`429 额度已用尽`	密钥的累计 token 额度耗尽，在管理面板「清零用量」或调高额度
`400 Invalid model`	模型名不在服务端允许列表中，见下文「模型列表」章节
`11128 安全策略拦截`	上游渠道风控。本服务已自动清洗敏感关键词并支持换账号重试；若持续出现，请把服务端日志中的告警行反馈给管理员
一直卡住无响应	请求已被上游受理但流式返回异常，检查网络与代理设置

模型名如何映射？

Claude Code 写死下发的是 Anthropic 官方模型名，服务端会自动映射成上游模型。你可以直接改用真实模型名（如 deepseek-v4.1-flash）绕开映射。

Claude Code 下发	服务端映射为
`claude-sonnet-4-5` / `claude-sonnet-4-5-20250929`	`deepseek-v4.1-flash`
`claude-opus-4-1` / `claude-opus-4`	`deepseek-v4.1-flash`
`claude-3-5-sonnet-20241022`	`deepseek-v4.1-flash`
`claude-3-5-haiku-20241022`	`deepseek-v4.1-pro`
`claude-3-haiku-20240307`	`deepseek-v4.1-pro`
真实模型名（如 `deepseek-v4.1-flash`）	原样透传，不做改写

重要：如果想让某个模型不被映射，就把真实模型名写进 ANTHROPIC_MODEL 与三个 ANTHROPIC_DEFAULT_*_MODEL 里，不要用 claude-* 这类名字。

把模型列表展示给 Claude Code

Claude Code 本身不拉取 /v1/models，但你可以手动查看当前密钥可用的模型，再从中挑一个填进配置。

curl "…"/v1/models \
  -H "x-api-key: sk-cb-your-key"

返回的 data[].id 即可直接填入 ANTHROPIC_MODEL。当前服务端可用模型：

加载中…

Cursor / VS Code 插件

在 AI 设置中开启自定义 API（OpenAI Compatible），按下表填写。

配置项	填写值
API Base URL	`…`
API Key	`sk-cb-your-key`
Model	`deepseek-v4.1-flash`（或其它已启用模型）
协议	OpenAI Compatible

提示：Cursor 的「自定义模型」需手动添加模型名；若列表拉取失败，可直接手填模型名后保存。

ChatBox / NextChat / 其它 OpenAI 客户端

通用 OpenAI 兼容客户端配置。

配置项	填写值
接口地址 / API Host	`…`
API Key	`sk-cb-your-key`
模型名	手动填写 `deepseek-v4.1-flash` 等

注意：部分客户端会自动在地址后拼接 /v1/chat/completions，此时「接口地址」只需填写到 根路径（如 …），无需包含 /v1。

其它客户端 / 自研应用

支持三种协议，按你的客户端或 SDK 选择对应端点。所有端点都同时支持 /v1 与 /codebuddy/v1 前缀。

协议	端点	适用
OpenAI Chat	`POST /v1/chat/completions`	OpenAI SDK、绝大多数第三方客户端
OpenAI Responses	`POST /v1/responses`	Codex CLI、新版 OpenAI SDK
Anthropic Messages	`POST /v1/messages`	Claude Code、Anthropic SDK

认证方式（二选一，效果相同）：

Authorization: Bearer sk-cb-… —— OpenAI 风格
x-api-key: sk-cb-… —— Anthropic 风格（Claude Code 使用）

# Python · OpenAI SDK
from openai import OpenAI
client = OpenAI(base_url="…", api_key="sk-cb-your-key")

# Python · Anthropic SDK
from anthropic import Anthropic
client = Anthropic(base_url="…", api_key="sk-cb-your-key")

查询密钥状态：调用 GET /v1/key（用密钥自身认证）可查看剩余额度、有效期、可用模型与白名单，便于排查 401 / 429 问题。

6常见问题

返回 401 / 403 怎么办？

表示鉴权失败。请确认请求头为 Authorization: Bearer <key> （Anthropic 风格客户端用 x-api-key），且所用 Key 处于启用状态、未过期且未超出额度。可用 GET /v1/key 查询密钥当前状态。如仍有问题请联系服务管理员。

返回 429 怎么办？

表示该密钥的累计 token 额度已用尽。请向服务管理员申请提高额度、清零用量，或改用其它密钥。GET /v1/key 返回的 tokens_used / token_quota 可确认剩余量。

返回 400 Invalid model 怎么办？

所用的模型名不在服务端允许列表中，或该密钥被限制了模型白名单。可用 GET /v1/models 查看当前密钥可用的模型； Codex / Claude Code 的官方模型名（如 gpt-5-codex、 claude-sonnet-4-5）已内置映射，可直接使用。

密钥过期或额度用尽如何处理？

请向服务管理员申请续期、提高额度或重新签发新的密钥。部分密钥采用「懒启动有效期」：签发后处于待激活状态， 从首次调用才开始计时，未使用则不会过期。

支持非流式请求吗？

支持。即使上游以流式返回，本服务也会自动聚合为非流式响应，设置 "stream": false 即可。

支持工具调用（Function Calling）吗？

支持。OpenAI 的 tools / tool_calls 与 Anthropic 的 tool_use / tool_result 均已适配，流式增量参数（input_json_delta）也能正确回传。

上游偶发拒绝（418 / 403）怎么办？

上游存在随机风控波动。服务端已内置自动重试与凭证轮换，在尚未产出内容时会自动换账号重发，客户端通常无感知。若持续失败，请稍后重试或联系服务管理员。