# Chatbox 集成

> 在 Chatbox 里添加自定义提供方,用 OpenAI / Claude / Gemini 兼容模式接入本平台

来源：https://qd.zsopc.com/docs/integrations/chatbox

> [Chatbox](https://chatboxai.app) 是桌面 / 手机 / 网页都能用的 AI 对话客户端,可以添加自定义模型提供方。本页步骤按 Chatbox v1.24.4(2026-11-12 发布)核对。

## 准备 API Key

在 [qd.zsopc.com/dashboard/keys](https://qd.zsopc.com/dashboard/keys) 创建 API Key(`sk-gpushare-` + 64 位十六进制,创建后可在 Key 详情页随时重新查看)。

## 添加提供方

1. **设置** → **模型提供方** → **添加** → **添加自定义提供商**
2. 弹窗里填 **名称**(随意,如 `小战AIhub`),**API 模式** 选 **OpenAI API 兼容**,点 **添加**
3. 在这个提供方的页面填:
   - **API 主机**: `https://qd.zsopc.com/v1`
   - **API 路径**: 留空(默认 `/chat/completions`)
   - **API 密钥**: 你的 `sk-gpushare-...`
4. 核对 **预览** 一行显示的是 `https://qd.zsopc.com/v1/chat/completions`
5. 在 **模型** 区点 **新建** 填模型 ID(如 `claude-sonnet-4-6`、`gpt-6.1-sol`、`deepseek-v4.1-flash`),或点 **获取** 从 `GET /v1/models` 拉列表后挑选
6. 点 **检查** 选一个刚加的模型做连通测试

> **获取** 拉到的是这把 Key 能调用的全部模型,其中图像、视频等模型不能在对话里用,只添加文本模型即可。完整列表见 [模型列表](../reference/models.md)。

Chatbox 拼地址的规则:API 路径留空、而 API 主机不以 `/v1` 结尾时,它会自己补 `/v1`;填了 API 路径就按「主机 + 路径」原样拼。所以主机写 `https://qd.zsopc.com/v1`、路径留空最稳,**获取**(请求 `主机/models`)也能用。

## 用 Claude / Gemini 原生协议(可选)

再添加一个提供方,API 模式换成对应的一项:

| API 模式 | API 主机 | Chatbox 实际请求 |
|---|---|---|
| Claude API 兼容 | `https://qd.zsopc.com/v1` | `/v1/messages` |
| Google Gemini API Compatible | `https://qd.zsopc.com` | `/v1beta/models/...` |

这两种模式下 API 路径一栏不起作用。Claude 模式填 Claude 模型(如 `claude-sonnet-4-6`),Gemini 模式填 Gemini 模型(如 `gemini-3.1-pro-low`)。只用 OpenAI API 兼容模式也能调这些模型,网关会自动做协议翻译,见 [兼容矩阵](../reference/compatibility-matrix.md)。

## 网页版注意

- **桌面版与手机版**:请求由客户端自己发出,按上面配置即可。
- **网页版**:请求从浏览器直接发往 API,而本平台的 API 不对第三方网页开放跨域访问,直连会失败。打开 **改善网络兼容性** 后,请求改由 Chatbox 的服务器中转 —— 这意味着你的 API Key 会经过 Chatbox 的服务器。介意的话请用桌面版。

## 常见问题

| 现象 | 排查 |
|---|---|
| 401 `invalid_api_key` | Key 是否复制完整(共 76 字符);可在 [Key 详情页](https://qd.zsopc.com/dashboard/keys) 重新查看 |
| 404 / 拉不到模型 | 看 **预览**:应为 `https://qd.zsopc.com/v1/chat/completions`。路径里重复写了 `/v1`,或者填了路径而主机没带 `/v1`,都会 404 |
| 400 `model_not_found` | 模型 ID 拼写,须与 [模型列表](../reference/models.md) 一致 |
| 400 `model_not_allowed` | 这把 Key 设了模型白名单,不含该模型 |
| 402 `quota_exceeded` | 余额不足。所有 Key 共享同一账户余额,到 [充值页](https://qd.zsopc.com/dashboard/billing) 充值 |
| 网页版报网络错误 | 见上方「网页版注意」 |

错误码完整说明见 [错误码](../reference/errors.md)。

## 其他客户端

- [Cherry Studio](./cherry-studio.md) — 桌面客户端
- [LobeChat](./lobechat.md) — 可自托管的对话界面
- [NextChat](./nextchat.md) — 轻量网页对话
- [Open WebUI](./open-webui.md) — 自托管 ChatGPT 风格界面
