Chatbox 接入自定义 API 后，报错大多不是“模型坏了”，而是四类问题：身份不对、地址或模型不对、额度或并发触顶、网络与 TLS 不通。先分类再验证，比反复重装客户端有效得多。

本文按 401、404（含 model not found）、429 和连接失败展开，并补充流式中断、多设备配置同步与日志取证。界面名称以你当前的 Chatbox 版本为准，模型与价格以站内模型价格为准。

说明：Chatbox 是其权利人的产品与商标，本文仅作技术排错说明，不代表任何隶属关系；不同版本的字段名称和默认值可能不同。

一、先保存证据，再判断类别

现象 常见状态码或错误 第一判断 先查什么
401 Unauthorized invalid_api_key、空响应 Key 或请求头 Key 是否完整、是否属于该地址
404 / model not found not_found_error 路径或模型 ID 主机、API 路径、模型 ID
429 Too Many Requests rate_limit_error、insufficient_quota 限流或余额 用量、并发、账单
Failed to fetch / Network Error 无状态码 网络不可达 DNS、代理、防火墙、TLS
5xx server_error 上游或网关故障 重试并记录 request id

排错前先记下发生时间、Chatbox 版本、HTTP 状态码、响应体和请求 ID。没有这些信息，只能靠猜；有这些信息，才能判断问题在客户端、网络还是服务端。

二、401：Key 没有被认出来

401 表示服务端不认这把 Key。高频原因包括：

  • 复制时带入空格、换行或全角字符，粘贴后看起来一样，实际不同；
  • 把 Chatbox AI 的许可证密钥当成 API Key，填进了自定义提供方；
  • Key 已被删除、轮换，或所属项目被停用；
  • 用 A 服务商的 Key 请求 B 服务商的地址；
  • 请求经过公司代理，代理返回 401 登录页，响应体是 HTML 而不是 JSON。

先确认 API 模式选的是 OpenAI 兼容，再重新粘贴 Key。不要用“看起来一样”来判断，直接绕过客户端测试：

export ZSQH_API_KEY="sk-你的密钥"

curl -sS "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"}]}' \
  -w "\nHTTP %{http_code}\n"

返回 200 和 choices，说明 Key 与地址有效；仍报 401，问题在 Key 的复制、权限或代理。403 通常是“认得出你，但不允许使用这个模型”，不要和 401 混在一起反复换 Key。

三、404 与 model not found：地址和模型各查一遍

404 有两种：路径不存在，和模型不存在。前者看 URL，后者看模型 ID。Chatbox 把 API 主机和 API 路径分开填写，最容易出现的错误是 /v1 重复：主机已经以 /v1 结尾，路径又带 /v1/chat/completions，最终请求变成 /v1/v1/chat/completions。

判断标准只有一个：最终请求地址里 /v1 只出现一次。主机填 https://ai.zhongshangqihang.com 时，路径可留空或按当前版本文档填写；主机填 .../v1 时，路径不要再重复。改完保存，用“检查”按钮或 curl 复测。

model_not_found 与路径无关。模型 ID 区分大小写、版本后缀和供应商前缀，必须从模型价格页或控制台复制。手动添加模型时，还要确认模型类型是聊天，能力勾选与实际一致，否则模型可能不出现，或一调用就失败。

“获取模型列表”失败也不一定代表配置错。部分网关不开放模型列表接口，手动填入准确的模型 ID 仍可正常对话。

四、429：限流、并发和余额

429 有两层含义：请求太快，或者没有额度。OpenAI 兼容接口常用 rate_limit_error 表示前者，用 insufficient_quota 表示后者。两者都可能是 429，但处理方式相反。

  • 请求太快：降低并发，减少同时打开的会话和客户端；长上下文会放大 token 消耗。
  • 没有额度：检查网关用量和账单，充值或更换 Key；单纯重试不会恢复。
  • 响应头有 Retry-After 时按它等待；没有时用指数退避加随机抖动。
  • 不要在 Chatbox 里连续点“检查”或连续重发，短时间内容易叠加请求。
  • 同一个 Key 在多台设备、多个窗口共用，也会共享并发额度。

如果只在长对话里出现 429，先压缩上下文或新建会话，再确认模型的上下文窗口。设置里的“最大上下文消息数”可以调低，但它只能缓解上下文压力，不能替代用量与并发管理。

五、连接失败：DNS、代理、SSL 和防火墙

Failed to fetch、Network Error、一直转圈，都表示请求没有拿到有效响应。先确认浏览器能打开网页，再用 curl 测试同一个域名。curl 也失败，问题在网络或网关；curl 成功而 Chatbox 失败，问题多在客户端代理、路径拼接或证书信任。

  • 公司网络：防火墙或安全网关可能拦截陌生域名，需要 IT 放行。
  • 代理：系统代理、VPN、Chatbox 内的代理开关可能叠加；只保留一层，代理地址不要填进 API 主机。
  • TLS：self signed certificate、UNABLE_TO_VERIFY_LEAF_SIGNATURE、证书过期，常见于企业解密代理；应安装企业根证书，而不是关闭校验。
  • 系统时间：偏差过大会导致证书校验失败。
  • 手机网络：Wi-Fi 与蜂窝网络结果不同，说明问题在本地网络或 DNS。

如果错误只在某台机器出现，优先对比系统代理、hosts、DNS 和证书，不要先怀疑模型。

六、流式输出中断和“回答到一半停了”

Chatbox 默认使用流式输出。中途停止常见于三种情况：代理或网关缓冲了 SSE、连接空闲超时、上游在生成途中断开。表现是前半段正常，后半段突然结束，或一直停在“正在输入”。

排查时先关闭流式输出（若版本提供该开关），用同一条问题对比。非流式能完整返回，说明问题在 SSE 链路；再检查代理的缓冲设置、超时时间和网络稳定性。长回答、推理模型和高峰期更容易触发，适当缩短输出或换时间重试。

另外，推理模型在给出正文前可能长时间“思考”，看起来像卡住。先等待，再用非流式请求确认是否真的没有响应。

七、多设备、会话与配置同步

Chatbox 的会话和设置默认保存在本机。换电脑或手机后看不到历史，通常不是 API 故障，而是数据没有跟过来。需要迁移时，使用客户端提供的导出、导入或备份功能；不同版本的能力不同，以当前版本为准。

较新的 Chatbox 版本支持导入 JSON 格式的模型提供方配置，可以把主机、模型列表和能力一次性带到另一台设备。但 API Key 仍建议单独管理：按设备或按人发 Key，泄露时只吊销一把。

如果两台设备表现不同，先比较版本、系统代理和模型配置，再比较 Key。不要用“另一台能用”直接推断当前设备是网络问题。

八、日志与取证：把问题说清楚

Chatbox 不同版本的日志和诊断入口不一样，有的在设置里提供导出，有的需要借助系统日志。无论有没有内置日志，都建议手动记录以下信息：

  • 发生时间（含时区）和是否稳定复现；
  • Chatbox 版本、操作系统和网络环境；
  • HTTP 状态码、响应体全文（删除 Key）；
  • 响应头里的 request id；
  • 同一请求的 curl 结果，以及流式与非流式的对比。

提交问题时，把 Key 打码，保留模型 ID、时间点和状态码。只写“连不上”通常无法定位；带上这些证据，多数问题一轮就能判断方向。

九、一套固定的排查顺序

  1. 用 curl 直连网关，确认 Key、主机和模型是否有效。
  2. curl 失败：查 DNS、代理、TLS、防火墙和网关状态。
  3. curl 成功但 Chatbox 失败：查 API 类型、/v1 是否重复、模型 ID 和客户端代理。
  4. 401 查 Key，404 查路径与模型，429 查用量与并发，连接失败查网络与证书。
  5. 每次只改一个变量，改完立即复测并记录结果。

这套顺序的价值在于把“客户端问题”和“服务端问题”分开。多数所谓 Chatbox 报错，最后都能归到某一条配置或某一层网络上。

需要统一管理 Key、用量和模型入口，可以注册中商起航 AI 网关；可用模型和计费方式以模型价格页为准，价格可能调整，以下单时页面为准。

常见问题

Chatbox 显示 Failed to fetch，是 Key 错了吗？

不一定。这个提示只说明客户端没有拿到响应，Key 错误只是可能原因之一。先用 curl 测同一主机；curl 也失败，优先查网络、代理和证书。

为什么 curl 能通，Chatbox 却连不上？

常见原因是客户端代理、/v1 重复、API 类型选错、系统证书不被信任，或客户端版本对路径的拼接方式不同。逐项对比最终请求地址。

429 一直重试会恢复吗？

如果是限流，退避并降低并发可能恢复；如果是额度不足，重试不会恢复，需要检查账单或更换 Key。先看响应体里的错误类型。

获取模型列表失败，还能手动添加吗？

可以。部分网关不开放模型列表接口，手动填入准确的模型 ID 仍可对话。前提是模型 ID、API 类型和主机都正确。

换设备后会话和配置会自动同步吗？

会话默认保存在本机，不一定会自动同步。用导出、导入迁移；较新版本可导入提供方 JSON 配置，但 API Key 仍建议重新填写并单独管理。

相关阅读：