Chatbox 是跨平台的 AI 客户端，支持桌面端和移动端，也能接入多家模型服务商。它有两种典型用法：使用内置的 Chatbox AI 服务，或者自带 API Key 接入自己的模型。本文只讲第二种：如何把 Chatbox 接到 OpenAI 兼容的自定义 API 上。
说明：Chatbox 是其权利人的产品，本文仅作技术接入说明。不同版本的菜单名称和字段位置可能不同，以当前版本为准；模型与价格以站内模型价格为准。
一、先确认你要用哪种模式
| 模式 | 计费方式 | 配置位置 | 适合谁 |
|---|---|---|---|
| Chatbox AI | 按客户端方案计费 | 登录账号即可 | 不想自己管 Key 的用户 |
| 自带 API Key | 由 API 服务商按量计费 | 模型提供方设置 | 已有网关或模型账号的团队 |
| 本地模型 | 取决于本机硬件 | 本地推理服务 | 对数据不出本机有要求的场景 |
两种模式可以并存。建议把自定义服务商单独命名，例如“中商起航”，避免和内置服务混淆。切换模型时先看清当前会话用的是哪个提供方。
二、准备三项参数
- API 密钥：在中商起航 AI 网关创建，按项目命名。
- API 主机：OpenAI 兼容地址，常用
https://ai.zhongshangqihang.com/v1。 - 模型 ID：从模型价格页复制准确的 API 标识。
先用 curl 验证，排除网关侧问题：
export ZSQH_API_KEY="sk-你的密钥"
curl "https://ai.zhongshangqihang.com/v1/chat/completions" \
-H "Authorization: Bearer $ZSQH_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "你的模型ID",
"messages": [{"role": "user", "content": "只回复 OK"}]
}'
能返回 choices 就说明 Key、地址和模型都有效，剩下的只是客户端操作。
三、添加自定义模型提供方
以当前常见版本为例，步骤如下（具体按钮文字以你的版本为准）：
- 打开 Chatbox，点左下角“设置”。
- 在左侧选择“模型提供方”，点底部的“+ 添加”。
- 给提供方起一个容易识别的名称。
- API 模式选择 OpenAI 兼容或对应的 OpenAI 选项。
- 填入 API 密钥和 API 主机。
- 点“获取”拉取模型列表，或者手动添加模型 ID。
- 点“检查”测试连接，选择刚添加的模型。
如果“获取”失败，不代表 Key 一定有问题，也可能是网关没有开放模型列表接口。这时直接手动填模型 ID，再用“检查”验证。
四、API 主机与 /v1
Base URL 是自定义 API 最容易填错的地方。建议按下表核对：
| 项目 | 建议值 | 注意 |
|---|---|---|
| API 模式 | OpenAI 兼容 | 不要选 Anthropic 或 Gemini 模式 |
| API 主机 | https://ai.zhongshangqihang.com/v1 |
末尾不加斜杠 |
| API 密钥 | sk-... |
前后不要有空格 |
| 模型 ID | 以价格页为准 | 区分大小写和版本后缀 |
如果填完整地址报 404，可以试着去掉 /v1；如果填域名报 404，就补上 /v1。不同客户端版本对路径的拼接方式不同，以实际请求结果为准。401 优先查 Key，404 优先查路径，这个判断顺序能省很多时间。
五、模型 ID 与能力配置
手动添加模型时，通常还要选模型类型和能力。常见对应关系如下：
| 模型类型 | 用途 | 需要勾选的能力 |
|---|---|---|
| 聊天模型 | 问答、写作、翻译 | 文本、流式输出 |
| 推理模型 | 复杂分析、规划 | 推理或思考过程 |
| 视觉模型 | 图片理解、截图问答 | 图片输入 |
| 工具模型 | 函数调用、插件 | 工具调用 |
模型类型选错，模型可能不出现在聊天选择器里；能力没勾选，上传图片或调用工具时会失败。拿不准时先只配文本聊天，跑通后再逐项加能力。
六、验证连接
客户端里的“检查”通常会对文本、图片、工具调用分别测试。至少要确认文本请求成功。更稳妥的做法是发一条真实问题，并观察三件事：
- 首字是否正常返回，还是长时间转圈。
- 多轮对话是否保留上下文。
- 长回答是否在中途断开。
如果只有长回答断开，优先查网络代理和流式响应；如果所有请求都失败，回到 Key 和 Base URL。也可以在电脑上开代理软件对比测试，但不要把代理地址填进 API 主机。
七、常见报错与处理
| 现象 | 常见原因 | 处理 |
|---|---|---|
401 Unauthorized |
Key 错误、过期或被删除 | 重新创建 Key，确认没有空格 |
404 Not Found |
API 主机路径不对 | 增减 /v1 后重试 |
model not found |
模型 ID 写错或未开通 | 对照价格页复制 |
| 连接超时 | 网络不可达或代理拦截 | 换网络，检查防火墙 |
| 回答中途停止 | 流式连接被中断 | 关闭流式输出对比测试 |
429 Too Many Requests |
并发或额度受限 | 降低并发，查看网关用量 |
| 图片上传失败 | 模型不支持视觉或能力未勾选 | 换视觉模型并勾选图片输入 |
排错时一次只改一个变量。同时换 Key、地址和模型，即使恢复了也不知道是哪一步修好的，下次还会踩同样的坑。
八、安全与成本
- 移动端和桌面端都可能保存 Key，共用设备要谨慎。
- 给 Chatbox 单独发一把 Key，方便随时吊销。
- 在网关侧设置预算上限，避免长时间挂机消耗额度。
- 不要在对话里粘贴生产密钥、客户名单和合同原文。
- 定期导出或备份重要会话，客户端卸载不等于云端有备份。
- 团队共用时按人发 Key，用量才能拆得清。
常见问题
Chatbox 自带 API Key 还要付订阅费吗？
自带 Key 模式下，模型调用费用由 API 服务商按量收取；Chatbox 客户端本身的收费方式以当前版本为准。两者不要混为一谈。
为什么“获取模型列表”一直失败？
可能是网关没有开放模型列表接口，也可能是 Base URL 路径不对。先手动添加一个模型 ID 测试；如果手动添加能用，就说明只是列表接口不支持。
API 主机要不要加 /v1？
多数 OpenAI 兼容配置需要 /v1。如果加与不加都报错，先用 curl 确认正确的完整请求地址，再回填到客户端，不要靠猜。
能同时配置多个服务商吗？
可以。给每个服务商单独命名，并在会话里明确选择模型。多服务商并存时，最容易发生的是“以为在用 A，实际请求发到了 B”。
手机上能直接用吗？
可以安装移动端并配置自定义服务商，但不同平台的入口和可用能力可能不同，以当前版本为准。敏感 Key 不建议长期保存在手机上。
下一步
Chatbox 的配置只有三个关键点：API 主机、Key、模型 ID。先用 curl 跑通，再进客户端；失败时按 401 查 Key、404 查路径、model not found 查模型 ID 的顺序处理。需要统一入口和用量管理，可以注册中商起航 AI 网关，模型与价格以模型价格页为准。
相关阅读：
