Chatbox 接入自定义 API 教程：Base URL、Key 与模型（2026）

Chatbox 是跨平台的 AI 客户端，桌面端和移动端都能用。它可以直接使用内置的 Chatbox AI 服务，也可以自带 API Key，接入自己的模型服务。本文只讲后者：从安装开始，把 OpenAI 兼容服务商接入 Chatbox，并完成验证、同步和团队配置。

说明：Chatbox 是其权利人的商标，本文仅作技术接入说明，与 Chatbox 团队无隶属关系；界面名称与功能入口以当前版本为准，模型与价格以站内模型价格为准。

一、安装：平台和版本先确认

桌面端适合长时间对话、处理长文档和截图；移动端适合碎片时间提问。两端可以配合使用，但配置入口不完全一样。

安装时注意三点：

从可信渠道下载，安装前核对应用名称和开发者信息。
企业电脑先确认软件白名单，避免装完无法联网。
安装后先升级到当前稳定版本，再开始配置。

旧版本可能没有“自定义模型提供方”，或者字段名称与教程不同。照旧教程硬填，最常见的结果是把 Key 填进了错误的输入框。先升级，再对照界面操作。

二、接入前准备三项参数

不管用哪家网关，自定义服务商都只需要三样东西：

参数	示例	常见错误
API Key	`sk-...`	复制时带空格或换行
Base URL	`https://ai.zhongshangqihang.com/v1`	填成完整接口地址
模型 ID	以价格页为准	用了展示名而不是 API 标识

Key 在中商起航 AI 网关注册后创建，建议按设备和用途命名，例如 chatbox-mac-work。Base URL 使用网关的 OpenAI 兼容地址。模型 ID 从模型价格页复制，注意大小写、版本后缀和连字符。

三项参数先记在一个临时位置，配置完成后再决定是否保存。不要把 Key 写进公开文档或聊天记录。

三、添加 OpenAI 兼容服务商

不同版本的按钮文字会有差异，操作顺序基本一致：

打开 Chatbox，进入“设置”。
找到“模型提供方”或“模型服务”。
点击“添加”或“+”，新建一个提供方。
名称填“中商起航”这类容易识别的字样。
API 模式选择 OpenAI 兼容，不要选 Anthropic 或 Gemini 模式。
填入 API Key 和 Base URL。
点击“获取”拉取模型列表，失败就手动添加模型 ID。
点击“检查”测试连接，并选中刚添加的模型。

一个提供方下可以放多个模型。建议把聊天、视觉、推理模型都放在同一个提供方里，切换时不容易找错。若你同时有测试环境和生产环境，建两个提供方并加前缀区分。

四、Base URL 和模型 ID 怎么填

Base URL 是最容易出错的一项。它应该写到 /v1，由客户端自己拼接后面的接口路径。如果你把 /chat/completions 也填进去，客户端可能再拼一次，结果就是 404。

判断顺序可以记成两句话：

401 优先查 Key：是否过期、是否被删除、前后有没有空格。
404 优先查路径：试着在末尾加减 /v1，一次只改一个变量。

模型 ID 必须以价格页的 API 标识为准。展示名通常更好看，但不能直接用于请求。带日期、带版本号、带 -mini 之类后缀的模型，尤其要逐字核对。

五、验证：先 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"}]
  }'

返回 JSON 里有 choices，说明 Key、地址和模型都有效。接下来再回客户端做三项检查：

发一条短问题，确认首字能正常返回。
连续追问两轮，确认上下文没有丢失。
让模型输出一段长回答，确认不会中途断开。

只有长回答断开时，优先检查网络和流式输出；所有请求都失败时，回到 Key 和 Base URL。客户端里的“检查”通过，只代表基础连通，不代表所有能力都可用。

六、设置与同步：桌面端和手机端怎么配合

Chatbox 的设置项通常包括默认模型、温度、上下文长度、代理和数据目录。建议先改三个：默认模型、是否流式输出、数据保存位置。其余参数保持默认，跑通后再调。

场景	建议做法	注意
桌面端日常使用	保存提供方配置，固定默认模型	定期导出会话备份
手机端临时提问	单独配置提供方，少放模型	共用手机不要长期保存 Key
换电脑	重新填写 Key 和模型 ID	不要直接拷贝整个配置目录
多人共用设备	使用独立系统账户	避免会话和 Key 互相可见

是否支持账号云同步、同步范围包含哪些内容，取决于当前版本和登录方式，以应用内的数据设置页为准。不要默认“聊天记录会同步，Key 也会同步”。多数情况下，Key 属于本机配置，换设备需要重新填写；导出的备份文件也可能包含敏感信息，应按密钥文件保管。

七、团队使用：把配置当成基础设施

小团队最容易忽略的不是接入，而是交接。建议至少做到：

按人发 Key，不用一把 Key 全员共用。
提供方名称统一，例如都以 ZSQH- 开头。
在网关侧设置预算或用量提醒，避免挂机消耗。
成员离职或设备丢失时，先吊销 Key，再处理其他账号。
把 Base URL、模型 ID、客户端版本写进内部文档。

这样做的价值不是“管理更规范”，而是出问题时能快速定位：是某个人的 Key 失效，还是某个模型下线，还是客户端版本不一致。

八、常见问题

Chatbox 不填 API Key 能用吗？

可以使用内置的 Chatbox AI 服务，具体额度和收费方式以当前版本为准。自带 Key 模式走的是你配置的 API 服务商，费用由服务商按量计算，两者不要混为一谈。

Base URL 到底要不要带 `/v1`？

多数 OpenAI 兼容配置需要带 /v1。如果带与不带都报错，先用 curl 找到能返回结果的完整地址，再回填客户端，不要靠猜。

“获取模型列表”失败，是不是 Key 坏了？

不一定。可能是网关没有开放模型列表接口，也可能是路径不对。先手动添加一个模型 ID，再用“检查”或真实对话验证。手动添加能用，就说明只是列表接口不支持。

桌面端能用，手机端却连不上？

先确认两端填的是同一个 Base URL 和模型 ID，再检查手机网络是否拦截了请求。移动端入口和可用能力可能与桌面端不同，以当前版本为准。不要在手机上长期保存高权限 Key。

换电脑后配置还在吗？

聊天记录和配置是否保留，取决于你是否登录账号、是否使用同步功能以及是否导出过备份。Key 建议重新填写；旧设备上的 Key 在确认不再使用后及时吊销。

下一步

Chatbox 接入自定义 API 的关键只有三步：装对版本、填对 Base URL、选对模型 ID。先 curl 验证，再进客户端；遇到报错时按 401 查 Key、404 查路径、模型不存在查 ID 的顺序处理。需要统一入口和用量管理，可以注册中商起航 AI 网关，模型与价格以模型价格页为准。