配置客户端

这一步的目标是：把前面拿到的 API Key、请求地址和模型名，填进你正在使用的 AI 客户端里。

不同客户端的界面不一样，但核心信息基本相同。只要位置填对，大多数 OpenAI-compatible 工具都可以接入 kapibalaAPI。

第 1 步：先准备 3 个信息

配置客户端前，先确认你手里有这些内容：

信息	示例	说明
API Key	sk-...	在 kapibalaAPI 控制台的 API Key 页面复制
请求地址	https://kapibala.asia 或 https://kapibala.asia/v1	按客户端要求选择是否带 /v1
模型名	gpt-5.5	以当前分组和价格页面支持的模型为准

WARNING

不要把 API Key 填到请求地址里，也不要把请求地址填到 API Key 里。这是客户端配置里最常见的错误。

第 2 步：判断请求地址该怎么填

不同工具对 Base URL 的要求不完全一样。

工具提示	建议填写
Base URL、API 地址、请求地址	https://kapibala.asia
OpenAI Base URL、OpenAI-compatible URL	https://kapibala.asia/v1
文档示例里自动拼接 /chat/completions	通常填写 https://kapibala.asia/v1
CC Switch 里给 Claude Code 填“请求地址”	通常填写 https://kapibala.asia
Codex 的 base_url	通常填写 https://kapibala.asia/v1

如果不确定，先按对应工具教程里的截图填写。配置失败时，再在 https://kapibala.asia 和 https://kapibala.asia/v1 之间切换测试。

第 3 步：按客户端类型填写

OpenAI-compatible 客户端

很多客户端会提供“自定义 OpenAI 提供商”或“OpenAI-compatible Provider”。

通常这样填：

Provider 名称：kapibalaAPI
API Key：sk-...
Base URL：https://kapibala.asia/v1
模型名：gpt-5.5

保存后，先获取模型列表或发送一条测试消息。

Cherry Studio

Cherry Studio 可以通过自定义提供商接入。

如果你用的是 Cherry Studio，可以直接看这篇专项教程：

Cherry Studio 中配置卡皮巴拉 API

Codex

Codex 更推荐使用 CC Switch 或 EchoBird 管理配置。

Codex 的最小配置通常会用到：

model_provider = "kapibala"
model = "gpt-5.5"
model_reasoning_effort = "high"
disable_response_storage = true

[model_providers.kapibala]
name = "kapibala"
base_url = "https://kapibala.asia/v1"
wire_api = "responses"

API Key 通常放在 auth.json 里：

{
  "OPENAI_API_KEY": "sk-..."
}

完整步骤看这里：

Codex 配置卡皮巴拉 API

Claude Code

Claude Code 建议通过 CC Switch 配置供应商和模型映射。

最小配置可以理解为：

供应商名称：卡皮巴拉API
API Key：sk-...
请求地址：https://kapibala.asia
认证字段：ANTHROPIC_AUTH_TOKEN
模型映射：选择当前可用模型

完整步骤看这里：

Claude Code 中配置卡皮巴拉 API

OpenClaw

OpenClaw 也可以通过自定义 provider 接入。

完整步骤看这里：

OpenClaw 中配置卡皮巴拉 API

第 4 步：保存后测试

配置完成后，先做一个很小的测试：

你好，请只回复：kapibalaAPI 已连接

如果客户端能正常回复，再继续做更复杂的任务。

如果客户端有“获取模型列表”“测试连接”“发送测试消息”按钮，优先用这些按钮验证。它们比直接跑正式任务更容易排查问题。

常见问题

现象	常见原因	处理方式
认证失败	API Key 不完整、填错位置，或缺少 Bearer 认证	重新复制完整 sk-...，确认填在 API Key 字段
模型列表为空	地址、Key、分组或余额异常	先确认 Key 可用，再检查请求地址和账户余额
模型不存在	客户端里的模型名不属于当前分组	改成当前分组支持的模型名
请求地址错误	/v1 填法和客户端要求不匹配	在 https://kapibala.asia 和 https://kapibala.asia/v1 之间切换测试
客户端没有请求记录	请求没有到达 kapibalaAPI	检查客户端是否启用了刚保存的 provider
使用记录里有失败记录	请求已到达，但参数或权限有问题	根据状态码、错误信息、模型名和分组继续排查

成功标准

完成这一页后，你应该已经：

1. 把 API Key 填到了客户端的密钥字段。
2. 把请求地址填到了 Base URL、API 地址或请求地址字段。
3. 选择了当前分组支持的模型。
4. 通过测试连接、模型列表或第一条消息确认客户端已经接入成功。