跳转至

Chatbox 接入 OpenAI 兼容 API：安装、配置与排错

最后核验：2026-07-14

适用范围：Chatbox 桌面端与移动端当前稳定版

预计用时：5～10 分钟

← 返回教程目录

[!NOTE] 本文适用于任何符合对应协议的 API。还没有测试 Key 时，可查看 教程配套 API。

1. 为什么选择 Chatbox

Chatbox 是本地优先的跨平台 AI 客户端，支持 Windows、macOS、Linux、iOS、Android 和 Web。它适合希望界面简单、对话记录保存在本机，并能自由填写 API Key 的用户。

本教程使用 Chatbox 的“自定义模型提供方”连接 OpenAI 兼容 API。

2. 准备材料

请提前准备：

  • API Key；
  • API Host；
  • API Path，通常为 /v1/chat/completions；
  • 一个准确的模型 ID。

没有 Key 的读者可以从纽智中转站注册并创建。模型 ID 请从控制台复制，不要根据展示名称手输。

3. 安装 Chatbox

桌面端

  1. 打开 Chatbox 官方下载页。
  2. 或从 GitHub Releases 下载。
  3. 根据平台选择安装包并完成安装。

官方仓库当前列出的最低桌面环境为：Windows 10、macOS 11，以及 Ubuntu 20.04+ 或支持 AppImage 的 Linux 发行版。

移动端

从系统官方应用商店搜索 Chatbox。不要安装来源不明的修改版，尤其不要在非官方客户端中输入付费 API Key。

4. 新建自定义模型提供方

  1. 打开 Chatbox。
  2. 点击侧栏底部“设置”。移动端先点击左上角菜单展开侧栏。
  3. 选择“模型提供方”或 Model Provider。
  4. 点击提供方列表底部“添加”。
  5. 填写一个名称，例如 我的 API。
  6. API 类型选择 OpenAI API compatible。

5. 正确理解 API Host 和 API Path

Chatbox 把请求地址拆成两部分：

最终请求地址 = API Host + API Path

例如，服务商给出的完整聊天接口如果是：

https://接口域名/v1/chat/completions

则通常填写：

API Host: https://接口域名
API Path: /v1/chat/completions

不要得到以下结果：

https://接口域名/v1/v1/chat/completions

不同服务可能带有额外路径前缀，因此最终以服务商接入文档为准。Chatbox 官方默认 API Path 是 /v1/chat/completions。

6. 填写完整配置

配置项 内容
提供方名称 自定义名称
API 类型 OpenAI API compatible
API Key 控制台创建的完整 Key
API Host 服务商提供的接口主地址
API Path 通常为 /v1/chat/completions

填完后先不要急着添加很多模型。

7. 添加第一个模型

  1. 点击“添加模型”。
  2. 在模型 ID 中粘贴控制台显示的准确 ID。
  3. 昵称可以写成便于辨认的名称；昵称不会发送给 API。
  4. 如果不确定模型能力，先不要勾选视觉、工具调用等可选能力。
  5. 保存配置。
  6. 点击“检查”或 Check。

未配置能力的模型会被 Chatbox 当作普通文本模型，这适合第一次连通测试。

8. 首次对话验证

  1. 返回首页并新建对话。
  2. 从输入框附近的模型选择器中选择刚添加的模型。
  3. 发送：
用一句话说明你已正常收到这条消息。

验证标准：

  • 能开始输出，而不是立即报错；
  • 输出能正常结束；
  • 刷新或重启后提供方配置仍存在；
  • 控制台用量记录中能找到本次请求。

9. 多模型配置建议

确认第一个模型可用后，再按需添加其他模型：

  • 日常问答：选择速度快、价格低的模型；
  • 代码与复杂分析：选择推理能力较强的模型；
  • 图片理解：确认接口和模型都支持视觉输入后再开启视觉能力；
  • 工具调用：只有服务端兼容 OpenAI tools/function calling 时才开启。

模型的“思考”“联网”“图片生成”等能力不是客户端单方面决定的。客户端有开关，不代表接口或当前模型一定支持。

10. 上下文与费用控制

Chatbox 会把一定数量的历史消息随新问题一起发送。长对话越往后，单次请求输入通常越大。

节省用量的方法：

  1. 不同主题新建对话；
  2. 长对话完成一个阶段后，让模型总结，再开新对话粘贴总结；
  3. 关闭不需要的自动标题、翻译、联网搜索；
  4. 上传大文件前先确认是否必要；
  5. 在控制台设置消费提醒或额度限制。

11. 常见报错

401：Key 无效

  • 重新复制 Key，检查首尾空格；
  • 确认 Key 没有被删除；
  • 不要把账户密码或兑换码当作 Key；
  • 创建一把新 Key 做交叉验证。

403：没有模型权限

检查 Key 所属分组与模型分组是否匹配。不要在无权限时反复重试，重复请求只会增加排查噪声。

404：路径不存在

这是 Chatbox 配置中最常见的问题。把 API Host 和 API Path 拼起来看：

  • 是否重复 /v1；
  • 是否漏写 /v1；
  • 是否填成 /responses 或 /messages；
  • 是否误填服务商后台网页地址。

400：参数不支持

新建空白对话，关闭思考、工具、图片、联网和自定义参数，只发送纯文本。如果恢复正常，再逐项开启能力，找出不兼容参数。

模型列表为空

部分兼容服务没有实现 /v1/models，但聊天接口仍可用。此时手动添加准确的模型 ID，再测试聊天请求。

输出到一半中断

  • 检查网络是否切换；
  • 暂时关闭流式输出后重试；
  • 缩短上下文；
  • 换一个模型验证；
  • 记录错误中的请求 ID，便于客服定位。

12. 数据备份与迁移

Chatbox 的对话数据主要保存在本地。重装系统、清理应用数据或更换设备前：

  1. 在设置中导出备份；
  2. 将备份保存在可信位置；
  3. 在新设备导入后抽查几个会话；
  4. 确认无误前不要删除旧设备数据。

备份中可能含对话隐私，切勿上传到公开网盘或 GitHub。

13. 安全提醒

  • 截图时遮住 Key 和账户信息；
  • 不在公共设备保存 Key；
  • 不把 Key 写进公开的 Chatbox 配置分享文件；
  • 发现异常用量后立即禁用旧 Key；
  • 第三方 API 的数据处理规则由对应服务决定，敏感内容发送前先确认隐私条款。

14. 官方资料

求助时请提供 Chatbox 版本、系统、错误码、API Host 与 API Path 的拼接结果、模型 ID。完整 Key 必须打码。