Chatbox 配置 OpenAI API：官方 Key 与兼容接口设置步骤
简答：Chatbox 配置 OpenAI API，先区分“内置 OpenAI”与“OpenAI API Compatible”两种模式：官方 Key 直接选择 OpenAI 并保留官方 Host；兼容接口则按服务商文档填写 Host、Path 和模型 ID。API Host、API Path 不要重复拼接，模型名必须原样复制，保存后用 Check 或测试消息验证。
定义：Chatbox 配置 OpenAI API，是在客户端的 Model Provider 或 AI Provider 设置中，填写 API 认证信息、接口地址和模型 ID，使 Chatbox 能按 OpenAI 或 OpenAI 兼容协议发送请求。
先看这张表：你应该选择哪种配置方式
先确定你使用的是哪一类 Key，再开始填写字段。Chatbox 官方文档说明，新增自定义提供方时可以选择 OpenAI API compatible；Chatbox 的 OpenAI 指南则提供了直接选择内置 OpenAI 提供方的路径。两者不要混用。
| 使用场景 | Chatbox 中的提供方 | API Host | API Path | 模型填写 |
|---|---|---|---|---|
| OpenAI 官方 API Key | OpenAI | 保留默认官方地址 | 通常不改 | 选择界面列出的可用模型 |
| 兼容 OpenAI 协议的服务 | 新增提供方，选择 OpenAI API compatible | 复制服务商文档中的 Host | 按服务商文档核对，不能凭经验补全 | 复制服务商控制台或文档中的 Model ID |
| 出现 404 | 两种模式都可能发生 | 检查是否已经包含 /v1 | 检查是否再次拼接 /v1/chat/completions | 先确认请求地址，再确认模型 |
Chatbox 官方的自定义提供方说明指出，API Path 通常可留空，默认值为 /v1/chat/completions，但仍应以具体服务商文档为准。由于不同兼容接口可能使用不同路径，最稳妥的做法是保存后点击 Check，并根据最终请求是否返回 404 继续核对。
本文是第三方接入说明，不代表 YUNWU.CYOU（云雾 API）官方页面，也不把该服务的 API Host、模型列表或分组规则当作已核实事实。若你要接入该服务，请以你当前控制台和文档显示的值为准。
路径一：在 Chatbox 中直接配置 OpenAI 官方 Key
如果你使用的是 OpenAI 官方 API Key，优先走 Chatbox 内置的 OpenAI 提供方，不要把官方地址当作自定义兼容接口处理。Chatbox 的 OpenAI Setup Guide 给出的流程是：打开设置，进入 AI Provider 或 Model Settings，添加 OpenAI，粘贴 API Key，并保留默认 API Host。
- 打开 Chatbox，进入左下角的 Settings。
- 进入 AI Provider、Model Settings 或名称相近的模型提供方页面。不同版本的菜单名称可能略有差异。
- 点击添加提供方，选择 OpenAI，不要选择自定义兼容接口。
- 在 API Key 字段粘贴官方 Key，API Host 保留 Chatbox 默认值。
- 保存后选择一个你账户有权限使用的模型，再发送一条短消息测试。
OpenAI API 参考文档说明，API Key 属于机密凭证，应通过 Bearer 认证发送，不要暴露在浏览器端代码或公开仓库中。桌面客户端本身需要保存 Key，因此建议只在可信设备中使用，并为不同用途使用可撤销、可区分的密钥。
如果你不确定 Key 是否有效，不要把完整 Key 发给他人排查。可以先在服务商控制台检查 Key 状态、项目权限和用量，再回到 Chatbox 复测。
可核对的官方说明：Chatbox OpenAI Setup Guide、OpenAI API Reference 的 Authentication。
路径二：配置 OpenAI 兼容接口
如果你使用的是兼容 OpenAI 协议的服务，应在 Chatbox 中新增一个自定义提供方。Chatbox 官方 Model Configuration 文档给出的界面流程是：打开设置，进入 Model Provider，点击 Add，选择合适的 API 类型，填写 API Key 与 API Host，添加至少一个模型，保存后点击 Check。
- 进入 Settings → Model Provider。
- 点击底部的 Add，填写一个便于识别的提供方名称。
- API 类型选择 OpenAI API compatible。
- API Key 填入当前服务商生成的令牌。不要把令牌写入公开截图、代码仓库或可分享的配置文件。
- API Host 只填写服务商文档指定的主机地址。若文档写的是带
/v1的 Base URL，就不要再在 API Path 中重复添加/v1。 - API Path 先按服务商文档填写；如果文档明确采用 Chat Completions 默认路径，可使用
/v1/chat/completions。没有文档依据时不要自行猜测。 - 添加一个模型，Model ID 原样复制。若控制台存在分组、前缀、重定向或路由规则，也按当前文档原样填写，不要擅自删除前缀。
- 保存后点击 Check，再新建对话发送短消息。
一个不绑定具体服务商的配置示例如下。示例中的 Host、Path 和 Model ID 都是占位符，必须替换成你实际使用的服务商文档值：
提供方名称：兼容接口示例
API 类型：OpenAI API compatible
API Key：YOUR_API_KEY
API Host：https://api.example.com
API Path：/v1/chat/completions
Model ID：YOUR_MODEL_IDChatbox 的导入配置文档还使用了 apiHost、apiPath、apiKey 和 modelId 等字段。若你使用 JSON 导入，字段必须按该文档的结构填写；如果只是手动配置，则以当前界面标签为准。导入配置页并没有在当前页面中核实你所使用服务的具体模型，因此不能直接替你填入某个模型名。
可核对的官方页面：Chatbox Model Configuration、Chatbox 导入第三方提供方配置。
最小核对清单：避免 Host 与 Path 拼接成 404
兼容接口最常见的配置问题不是 Key，而是地址重复。你可以按下面顺序核对：
- 把 API Host 和 API Path 分成两栏查看，不要把完整的
/chat/completions地址同时填进 Host。 - 检查 Host 末尾是否多了斜杠。若界面或文档要求根地址，优先使用不带末尾斜杠的形式，避免拼接出双斜杠。
- 检查 Host 是否已经包含
/v1，再查看 Path 是否也从/v1开始。 - 检查 Model ID 是否多了空格、大小写变化或复制了展示名称而不是实际 ID。
- 保存后先点击 Check；如果 Check 失败，再用一个最短问题测试，不要同时修改 Host、Path、Key 和模型，否则无法判断是哪一项导致问题。
| 现象 | 优先检查 | 处理方法 |
|---|---|---|
| 401 | API Key、Bearer 认证、Key 是否过期或复制不完整 | 重新复制 Key，确认使用的是对应项目或账户的凭证，不要在文章或工单中公开完整 Key。 |
| 403 | 账户权限、模型权限、来源限制或服务商策略 | 查看控制台权限和服务商文档；若是官方 API，则核对项目与模型访问权限。 |
| 404 | Host、Path、模型 ID | 重点排查 /v1 重复、完整接口地址被重复拼接，以及模型名写错。 |
| 额度不足 | 账户余额、项目预算或用量限制 | 检查控制台账单和用量。Chatbox FAQ 将 insufficient_quota 归因于账户额度或计费状态，而不是客户端本身。 |
| Failed to fetch | 网络无法访问 API Host、证书或跨域环境 | 先确认设备能访问 Host；优先使用桌面版做连通性验证，网页版还可能受到浏览器网络策略影响。 |
Chatbox FAQ 明确提到，Failed to fetch 常见原因是客户端无法连接所设置的 AI 模型服务器；对于官方 OpenAI 提供方，还应确认当前网络能访问默认 API Host。该 FAQ 也列出了额度不足时的 insufficient_quota 现象。相关判断只能用于排查方向，具体原因仍要结合服务商返回的状态码和响应内容。
如果服务商公告提到模型重定向、模型名前缀、自动换组或分组调整，先按公告更新 Model ID 与分组，再重新 Check。本文未核实这些规则是否适用于当前服务，也不提供未经确认的具体值。
更多错误现象可查看 Chatbox 官方 FAQ；OpenAI 请求认证格式可查看 OpenAI API Reference。
配置完成后的安全与验证建议
完成配置后，建议只做一次短消息测试，再逐步启用视觉、工具调用或长上下文能力。这样能把“认证成功”“模型可用”和“高级能力兼容”分开判断。
- 先验证认证：Check 成功或短消息能返回，说明基础地址和凭证至少通过了一次请求。
- 再验证模型：确认当前 Model ID 与服务商控制台显示一致，不要只看模型昵称。
- 最后验证能力：需要图片、推理或工具调用时，再检查 Chatbox 中对应模型能力配置；Chatbox 文档说明，未配置的模型会按普通文本模型处理。
- 保护 Key：不要把完整令牌放入截图、公共 JSON、浏览器前端代码或版本库。OpenAI 文档建议从环境变量或密钥管理服务加载凭证。
- 记录错误：保留时间、状态码、请求地址的非敏感部分和模型 ID；不要提交完整 Authorization 头。
如果你只是想使用 OpenAI 官方服务，内置 OpenAI 提供方通常比自定义兼容接口少一层路径配置；如果你使用的是其他兼容服务，则必须以该服务当前文档和控制台显示的 Host、Path、模型 ID 为准。
常见问题
Chatbox 里 API Host 应该填什么？
官方 OpenAI Key 使用 Chatbox 内置 OpenAI 提供方并保留默认 Host。兼容接口则只填写服务商文档给出的 Base URL 或 API Host，不要把完整的 /chat/completions 地址重复填入。
API Path 应该写 /v1/chat/completions 还是 /chat/completions？
不能凭经验决定。Chatbox 官方文档给出的常见默认值是 /v1/chat/completions，但不同兼容接口可能不同；先看服务商文档，并检查 Host 是否已经包含 /v1，避免路径重复导致 404。
Chatbox 配置后出现 401，应该怎么办？
先重新复制 API Key，确认没有多余空格、换行或使用了错误项目的 Key；再核对提供方类型和 Host。不要把完整 Key 发给他人，必要时在控制台撤销并重新生成。
出现 Failed to fetch，是 API Key 错了吗？
不一定。Chatbox 官方 FAQ 将该现象首先指向客户端无法连接 API Host。先检查网络、Host、证书和桌面版连通性；如果能连接但返回 401，再继续检查 Key。
为什么模型名称填对了仍然提示模型不存在？
展示名称不一定等于 Model ID。请从当前服务商控制台或文档复制实际模型 ID，保留大小写、前缀和连字符；如果存在分组或路由规则，也要按当前规则填写。
Chatbox 网页版和桌面版配置有什么区别？
基本字段逻辑相同，但网页版直连接口时还可能受到浏览器网络策略影响。遇到 Failed to fetch 时，优先用桌面版验证 Host、Path 和 Key，再判断是否为网页环境问题。
参考资料
- Model Configuration | Chatbox AI（docs.chatboxai.app）
- 导入第三方提供方配置 | Chatbox Docs
- FAQ.md | Chatbox
- OpenAI Setup Guide | Chatbox AI User Guide（chatboxai.app）