Chatbox API Key 配置教程：多模型、密钥安全与同步（2026）

同样是把 Chatbox 接上自定义 API，有人五分钟跑通，有人反复遇到 401。差别通常不在客户端，而在 Key 的创建、存放和使用边界。本文围绕 API Key 讲四件事：怎么创建、怎么配置多模型、存在哪里、怎么轮换与排错。

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

一、先分清两种“Key 来源”

Chatbox 里可能同时存在两套凭证：登录 Chatbox AI 服务的账号，以及你为自定义服务商填写的 API Key。两者计费主体不同，排错时也完全不同。

来源	费用归属	适合场景	注意
Chatbox AI 账号	按客户端方案	不想自己管 Key	与自定义 Key 无关
自带 API Key	由 API 服务商计费	已有网关或模型账号	需自行保管和轮换
本地模型	取决于本机硬件	数据不出本机	不需要远程 Key

出现“明明登录了却报 401”时，先确认当前会话选中的是哪个提供方。账号登录成功，不代表自定义提供方的 Key 填写正确。

二、创建 Key：命名、归属和权限

在中商起航 AI 网关注册后，到控制台创建 Key。创建时最好一次做对三件事：

命名可追溯：用“设备-用途-使用者”的格式，例如 chatbox-mac-alice。
一 Key 一用途：桌面端、手机端、自动化脚本分开，出问题好定位。
记录归属：在内部台账里写清创建日期、负责人和用途。

密钥通常只在创建时完整显示一次，关闭页面后无法再次查看。创建后立即保存到密码管理器，不要截图发到群里。若控制台支持额度、模型范围或 IP 限制，按最小权限设置；不确定有哪些限制，就以“单独一把 Key”为底线。

三、在 Chatbox 中配置多服务商与多模型

多模型并不意味着多把 Key。通常一个提供方配置一把 Key，下面挂多个模型 ID：

打开设置，进入“模型提供方”。
添加一个 OpenAI 兼容提供方，命名建议带环境前缀。
填入 Base URL，通常是 https://ai.zhongshangqihang.com/v1。
填入 API Key，确认前后没有空格。
手动添加模型 ID，或尝试拉取模型列表。
为模型选择类型：聊天、视觉、推理或工具调用。
点“检查”验证，再回对话界面切换模型。

模型 ID 以模型价格页为准。展示名可以自己改，但 API 标识必须逐字一致。把聊天模型和视觉模型分开命名，例如“聊天-主力”“视觉-截图”，切换时不容易选错。

如果团队同时使用 Cherry Studio、LobeChat 等客户端，建议统一提供方命名和模型别名，减少“同一个人在不同客户端用了不同模型”的混乱。

四、Key 存在哪里：本地、同步与备份

桌面端通常把配置保存在本机应用数据目录，移动端保存在应用沙箱内。具体路径随操作系统和版本变化，不建议手动改配置文件。

关于同步，要区分三件事：

聊天记录同步：是否支持、同步范围多大，取决于客户端版本和账号方案。
设置同步：提供方配置可能随账号同步，也可能只在本机。
Key 同步：不要把“配置同步”理解为“Key 一定安全地同步”。很多客户端会把 Key 一并写入配置或备份文件。

因此，导出的备份、迁移的配置目录、共享的截图，都应视为敏感文件。换设备时，推荐重新填写 Key，而不是复制整个数据目录；旧设备确认不再使用后，吊销旧 Key。

五、最小权限：让 Key 只做该做的事

API Key 不是越少越好，而是边界越清楚越好。可执行的做法：

每个成员一把 Key，不共用。
生产用途和试用用途分开，试用 Key 设更低额度。
只在需要的设备上保存 Key，公共电脑用完即删。
网关控制台支持预算、模型白名单或用量提醒时，全部打开。
日志和工单里只写 Key 的末几位，不贴完整密钥。

如果客户端支持多个提供方，也可以按“工作/个人”拆分。这样某一端泄露时，只需吊销一把 Key，不影响其他设备。

六、轮换与吊销：按固定节奏做

建议至少每 90 天轮换一次；发生人员变动、设备丢失、配置误传时立即轮换。顺序不能反：

在控制台创建新 Key，命名加日期后缀。
在 Chatbox 中把提供方的 Key 替换为新值。
发一条测试消息，确认模型正常返回。
确认新 Key 工作后，再吊销旧 Key。
检查网关用量，确认没有陌生调用。
更新内部台账，记录轮换日期。

验证时可以先用一条命令看状态码：

export ZSQH_API_KEY="sk-新密钥"

curl -sS -o /dev/null -w "%{http_code}\n" \
  "https://ai.zhongshangqihang.com/v1/models" \
  -H "Authorization: Bearer $ZSQH_API_KEY"

返回 200 说明认证通过；返回 401 先查 Key 是否复制完整。若网关未开放模型列表接口，改用一次普通的对话请求验证即可。轮换期间不要同时改 Base URL 和模型 ID，否则无法判断问题出在哪一步。

七、常见故障：按状态码分流

现象	常见原因	处理
`401 Unauthorized`	Key 错误、过期、被吊销或带空格	重新创建并完整粘贴
`403 Forbidden`	无模型权限、地域或策略限制	查控制台权限与模型范围
`404 Not Found`	Base URL 路径不对	核对是否该带 `/v1`
`429 Too Many Requests`	并发或额度受限	降并发，查用量与限额
`5xx`	上游服务异常	稍后重试，保留请求时间

排查时一次只改一个变量。先确认是“这一把 Key 的问题”还是“这个模型的问题”：换一把 Key 测试，或换一个模型测试，很快就能分流。

八、团队交接清单

把下面几项写进交接文档，能减少大部分“换人后不能用”的问题：

Key 的负责人、用途、创建日期和下次轮换日期。
提供方名称、Base URL、模型 ID 清单。
哪些设备保存了 Key，哪些是共用设备。
离职、转岗、设备丢失时的吊销流程。
用量异常的检查入口和联系人。

常见问题

Key 会随聊天记录同步到其他设备吗？

不一定。聊天记录同步和配置同步是两件事，Key 是否随配置同步取决于客户端版本和登录方式。不要把同步功能当成密钥保险箱；换设备时重新填写更稳妥。

一把 Key 能同时给桌面端和手机端用吗？

技术上通常可以，但不建议长期这样用。按设备拆 Key，某一端丢失或泄露时可以单独吊销，不影响另一端。

客户端“检查”通过，聊天却报 401？

先确认聊天时选中的提供方和模型，是不是你刚配置的那一个。多提供方并存时，最常见的问题是请求发到了另一个没有填 Key 的提供方。

轮换 Key 后要重新添加模型吗？

通常不需要。模型 ID 属于提供方配置，换 Key 只改认证信息。但如果客户端在换 Key 后清空了模型列表，重新添加即可，模型 ID 仍以价格页为准。

可以把 Key 填进代理软件或浏览器插件吗？

不建议。Key 应只出现在你信任的客户端和网关控制台。代理软件、截图工具和浏览器插件都可能读取或转发配置，能不给就不给。

下一步

Chatbox 的 Key 管理可以归纳为：一把 Key 一个用途，配置与备份都按敏感文件对待，轮换时先建新再吊销旧。需要统一入口、用量和权限管理，可以注册中商起航 AI 网关，模型与价格以模型价格页为准。