Chatbox 怎么配置 OpenAI 兼容 API：完整图文设置教程
Chatbox 支持接任意 OpenAI 兼容接口，但配置项分布在不同位置，填错一个字段就报模型不存在。这篇按桌面端和移动端分别给出完整设置路径、字段对照表、常见报错的正确写法，以及几个值得改的默认选项。
Chatbox 是目前上手门槛最低的多模型桌面客户端之一：装好、填两个字段、就能聊天。但它的配置界面把"服务商"和"模型"拆成了两层，很多人卡在"接口地址填了却提示模型不存在"这一步。
这篇把配置路径完整走一遍，桌面端和移动端都覆盖，并给出字段对照表和几个实际会遇到的配置错误。
先说结论
- 服务商类型选 OpenAI API（不是 OpenAI 官方账号登录），才能自定义
base_url API Host填https://api.zaimod.com，不要带/v1，Chatbox 会自己拼接- 模型名必须和接口实际支持的名称完全一致，下拉框里没有就手动输入
- 配置完先点"检查连接"，能列出模型列表说明 Key 和地址都对
- 移动端和桌面端的配置互相独立，换设备要重新填一次
一、桌面端配置步骤
以 Windows / macOS 版本为例，路径基本一致。
第 1 步：拿到 API Key
先在注册页创建 Key，复制时注意不要带上前后空格。Key 只在创建时完整显示一次，没存下来就重新建一个。
第 2 步：添加自定义服务商
打开 Chatbox → 左下角「设置」→「模型」标签页 → 找到「添加自定义提供方」。
第 3 步：填写字段
| 字段 | 填什么 | 说明 |
|---|---|---|
| 名称 | 任意，如 zaimod | 只影响显示 |
| API 模式 | OpenAI API 兼容 | 关键，选错就走错协议 |
| API Host | https://api.zaimod.com | 不带 /v1，不带尾部斜杠 |
| API Path | 留空或 /v1/chat/completions | 留空时自动用默认路径 |
| API Key | 你创建的 Key | 通常以 sk- 开头 |
| 模型 | 手动输入模型名 | 见下节 |
有些版本的界面里 API Host 标注为 API 域名 或 Base URL，含义相同。
第 4 步：填模型名
点「+ 添加模型」，手动输入模型 ID。模型 ID 要和接口里的名称逐字符一致，大小写、连字符、版本号后缀都不能差。可以先去模型列表查准确的 ID，或者配置好 Key 后点「检查连接」，让客户端拉取可用模型列表后从下拉框里选。
第 5 步：验证
保存后回到对话界面，在顶部模型选择器里选中刚加的模型，发一条「你好」。能正常返回，配置就完成了。
二、移动端配置差异
iOS 和 Android 版的入口是「设置」→「模型提供方」→ 右上角「+」。
字段和桌面端基本一致，但有两个地方容易踩：
- 移动端默认可能只显示主流服务商列表，需要在列表底部选「自定义」或「OpenAI API 兼容」
- 部分版本把 API Host 拆成「协议 + 域名」两栏，协议选
https，域名填api.zaimod.com
移动端和桌面端的配置不互通。如果你在手机上也想用同一个 Key，重新填一次即可，Key 本身是通用的。
三、常见配置错误的正确写法
提示模型不存在 / model not found
九成是模型名拼错。正确做法是从模型列表复制完整 ID，粘贴进去后检查有没有多出空格。如果模型 ID 带日期后缀或版本号，整段都要带上。
提示 404 或接口不存在
多半是 API Host 里多写了 /v1。Chatbox 会在 Host 之后自动拼接 /v1/chat/completions，你再填一个 /v1 就变成了 /v1/v1/chat/completions。
正确的写法：
API Host: https://api.zaimod.com错误的写法：
API Host: https://api.zaimod.com/v1
API Host: https://api.zaimod.com/v1/
API Host: https://api.zaimod.com/v1/chat/completions提示 401 未授权
三种可能：Key 复制时带了空格或换行；Key 已被删除或失效；Key 前面漏了 Bearer 前缀（Chatbox 会自动加，如果你手动在 Key 字段里填了 Bearer sk-xxx，反而会变成双重前缀）。正确做法是 Key 字段只填 sk- 开头的那串字符。
提示 429 请求过多
这是触发了速率限制，不是配置错误。降低并发或加重试退避即可，具体做法见429 限流处理。
思考过程不显示 / 深度思考模式报错
部分带推理能力的模型会额外返回 reasoning_content 字段。Chatbox 较新版本支持展示，旧版本可能忽略该字段或报错。升级到最新版即可。
四、几个值得改的默认选项
配好基本连通性后，这几个设置能明显改善使用体验：
| 选项 | 位置 | 建议 |
|---|---|---|
| 上下文消息数 | 设置 → 对话 | 默认值偏大，长对话下建议调到 10–20 条 |
| 温度 | 对话设置 | 写代码/翻译用 0–0.3，创意写作用 0.7–0.9 |
| 最大回复 token | 对话设置 | 留空用模型默认，长文任务显式设为 2000 以上 |
| 流式输出 | 设置 → 对话 | 保持开启，否则长回答要等很久 |
| 自动生成标题 | 设置 → 对话 | 关掉可以省一次请求，会话多时成本差异明显 |
上下文消息数这个值尤其值得调。它决定每次请求带多少条历史消息，设得太大不仅成本上去，长对话还容易顶到上下文上限被截断。关于怎么算这份额度，可以看上下文窗口与 Token 预算。
五、和 Cherry Studio 的取舍
如果你在几个客户端之间犹豫，简单对比：
| 维度 | Chatbox | Cherry Studio |
|---|---|---|
| 上手速度 | 更快，字段少 | 配置项更多，功能也更全 |
| 多模型切换 | 支持，切换顺手 | 支持，可分组管理 |
| 知识库 | 较简单 | 内置完整的 RAG 流程 |
| 移动端 | 有官方 App | 有 |
| 适合场景 | 日常对话、临时提问 | 长文档分析、知识库问答 |
两者都能接 OpenAI 兼容接口，配置文件不通用但字段逻辑一样，会配一个就会配另一个。Cherry Studio 的配置细节可以看这篇教程。
六、配置完成后建议做的一件事
在 Chatbox 里连续问几个不同类型的问题，观察哪类请求消耗的 token 明显偏高。Chatbox 会在回复下方显示本次消息的 token 用量，用这个数据反推你的实际使用成本，比按官方单价估算准得多。
另外，如果你打算在团队里推广这套配置，把 API Host、模型 ID 规范、Key 保管方式整理成一页说明发给大家，能省掉大量重复答疑。Key 不要写进聊天记录或文档正文，按多 Key 与额度管理的做法分环境发放。
FAQ
Chatbox 需要登录账号吗？不需要登录官方账号，本地使用即可。选择「自定义提供方」并填入自己的 Key 就能用。
可以同时配置多个服务商吗？可以。配置多个提供方后，在对话界面顶部随时切换模型，历史会话会保留但模型可以选择性切换。
配置好了但回复很慢是什么原因？先确认流式输出已开启。如果开了还是慢，可能是模型本身的响应速度差异，可以换一个更快的模型对比测试。
在 Chatbox 里能用带视觉能力、能看图的模型吗？可以。选择支持视觉的模型后，在输入框旁点附件上传图片即可，客户端会把图片按兼容协议编码发送。
换电脑后配置丢了怎么办？Chatbox 的配置存在本地，不随账号同步。可以在设置里导出配置，在新设备导入后只重新填一次 API Key。
延伸阅读
- OpenAI 兼容协议到底是什么——理解配置项背后的协议结构
- Cherry Studio 接入教程——另一个客户端的配置路径
- 模型列表——查准确的模型 ID
- 快速开始——从创建 Key 到第一次调用
配置只有两个字段，卡住的人往往是漏了"不带 /v1"这一条。现在去创建一个 API Key，按上面的路径填一遍，五分钟内就能聊上。