客户端接入

卡皮巴拉兼容 OpenAI 格式，几乎所有支持自定义 API 的 AI 工具都能用。本文给出主流工具的具体配置示范。

通用配置（所有工具都一样）

配置项	填写内容
API 地址 / Base URL	https://api.example.com/v1
API Key	你在管理页面创建的密钥（sk- 开头）
模型名称	比如 gpt-4o-mini，或其他你想用的模型

下面针对常用工具分别说明。

---

Cherry Studio

1. 打开 Cherry Studio，点击左下角 ⚙️「设置」
2. 进入「模型服务」标签
3. 找到「OpenAI」，点击右侧的开关启用
4. 填写：
   • API 密钥：你的 API Key
   • API 地址：https://api.example.com/v1
5. 点击「检查」按钮测试是否连通
6. 在「默认模型」里选你想用的模型

Chatbox

1. 打开 Chatbox，点击左下角「设置」
2. 「模型」标签下，模型提供方选择 「OpenAI API」
3. 填写：
   • API Key：你的 API Key
   • API Host：https://api.example.com/v1
4. 「Model」下拉框选择你要用的模型，或手动输入模型名
5. 点保存

NextChat / ChatGPT-Next-Web

1. 打开 NextChat，点击左下角设置图标
2. 找到「自定义接口」并打开
3. 填写：
   • 接口地址：https://api.example.com/v1
   • API Key：你的 API Key
   • 自定义模型名：填写你要用的模型，多个用英文逗号分隔
4. 保存即可

OpenAI 官方 SDK（开发者）

如果你在写代码，把官方示例里的 baseURL 和 apiKey 换成卡皮巴拉的就行：

Node.js / TypeScript

import OpenAI from 'openai'

const client = new OpenAI({
  baseURL: 'https://api.example.com/v1',
  apiKey: 'your-api-key'
})

const completion = await client.chat.completions.create({
  model: 'gpt-4o-mini',
  messages: [
    { role: 'user', content: '你好' }
  ]
})

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

Python

from openai import OpenAI

client = OpenAI(
    base_url="https://api.example.com/v1",
    api_key="your-api-key"
)

completion = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[
        {"role": "user", "content": "你好"}
    ]
)

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

curl 命令行

curl https://api.example.com/v1/chat/completions \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      { "role": "user", "content": "你好" }
    ]
  }'

Claude Code / Codex / Gemini CLI

这些命令行 AI 编程工具通过环境变量配置，强烈建议使用 CC-Switch 桌面工具 一键切换，比手改配置文件方便得多。

⚠️ 通用注意事项

WARNING

1. API 地址不要重复 /v1：如果客户端会自动追加 /v1，那你只填域名部分；按上面的配置直接填 https://api.example.com/v1 就行
2. Key 不要带空格：复制粘贴时容易带上首尾空格，导致认证失败
3. 模型名要写对：模型名严格区分大小写和符号，照着我们提供的列表填

配完用不了？

走一遍 常见问题排查，里面有典型错误的处理方法。