在 Chatbox 里添加自定义 OpenAI 兼容服务后最容易混在一起的其实是三个不同问题点击Fetch后列表为空、手动新增模型后出现model_not_found、点击Check后又报图像或工具调用错误。它们不是同一层故障也不应该靠反复换 Key 解决。本文按 Chatbox 官方v1.22.1的当前源码说明真实调用链并用一个只监听127.0.0.1的 Python 夹具复现成功和失败分支。先给结论Fetch成功不只要求 HTTP 200响应还必须有顶层data数组真正用于请求的值是data[].id不是你看到的友好名称。先准备这组最小配置进入 Chatbox 设置添加自定义提供商并选择OpenAI API Compatible。当前界面会显示API Host、API Path、Model模型区域有New、Reset、Fetch配置满足条件后还可以使用Check。如果服务使用标准/v1前缀先把职责拆开字段示例值作用API Hosthttps://your-gateway.example/v1模型列表和聊天请求的共同基址API Path/chat/completions对话资源路径API Key当前服务要求的 Key只保存在客户端不进入文章或截图Model ID从/models的data[].id复制真正发送给服务端的模型值先不要急着点Check。用下面的命令确认模型列表契约BASE_URLhttps://your-gateway.example/v1curl-sS-i$BASE_URL/models\-HAuthorization: Bearer$OPENAI_API_KEY合格的最小响应应同时满足三项状态码是 200、正文是 JSON、顶层存在非空data数组。例如{object:list,data:[{id:provider-model-exact-id,object:model}]}这里真正要复制的是provider-model-exact-id。不要把网站商品名、控制台展示名、自己起的中文别名或另一个客户端的模型名当成服务器 ID。为什么 HTTP 200 仍然可能拉不到模型Chatboxv1.22.1的模型拉取实现会请求normalized API Host/models拿到 JSON 后它直接检查顶层data。没有data就抛出错误存在data时每一项的id被映射为 Chatbox 的modelId。因此下面这个响应虽然是 200仍不满足当前契约{object:list,models:[{name:provider-model-exact-id}]}这类情况常见于“接口看起来像 OpenAI但模型列表字段并不兼容”的服务。此时不要把问题归因成网络失败。你需要查服务方文档确认它是否提供 OpenAI 风格的/models如果模型列表被禁用只能使用 Chatbox 的New手动添加精确 ID。Fetch、New、Check分别做什么Fetch读取服务器模型目录它适合确认当前 Base URL、认证和模型列表数据契约是否同时成立。列表拉取失败时先保存完整状态码和脱敏响应体再判断是 401、404、200 但结构不兼容还是网络错误。New手动保存一个模型 IDNew能绕过“服务没有开放/models”这一限制但它不证明模型存在。手动输入后Chatbox 只是把这个值加入当前提供商的模型列表。下一次真实请求仍会把该modelId发给服务端所以大小写、连字符、日期后缀和区域后缀都必须逐字一致。Check执行能力测试不是一次 ping当前v1.22.1的检查流程先发送基础文本请求基础请求成功后还会继续尝试一张 1x1 图片和一次工具调用。也就是说一次Check最多可能产生三次模型请求。如果你的服务按请求计费、模型不支持图像或工具调用后两项失败不等于基础文本模型不可用。为了把问题收窄建议先用一个最小非流式文本请求确认精确 ID再决定是否运行完整Check。用最小聊天请求验证精确 ID把模型 ID 从/models响应中复制出来MODEL_IDprovider-model-exact-idcurl-sS-i$BASE_URL/chat/completions\-HContent-Type: application/json\-HAuthorization: Bearer$OPENAI_API_KEY\-d{\model\:\$MODEL_ID\,\messages\: [{\role\:\user\,\content\:\reply with OK\}],\stream\: false }成功信号是 HTTP 200并且响应中能读到choices[0].message.content。如果同一个请求把model换成友好名称后出现model_not_found就已经把故障定位到模型值而不是 Base URL、Key 或 Chatbox UI。本地实测200、结构错误、别名错误和精确 ID本次夹具只承认两个模型 ID并故意准备四条分支GET /v1/models - 200 data[].id GET /malformed/v1/models - 200 models[].name无 data POST /v1/chat/completions 别名 - 404 model_not_found POST /v1/chat/completions 精确ID - 200 CHATBOX_MODEL_OK执行命令python3 06-evidence/probe_chatbox_model_fetch.py脱敏结果CHATBOX_VERSION1.22.1 GOOD_MODELS_HTTP200 GOOD_MODEL_IDSfixture-chat-v2,fixture-reasoning-v1 MALFORMED_MODELS_HTTP200 MALFORMED_HAS_DATANO WRONG_MODEL_HTTP404 WRONG_MODEL_ERRORmodel_not_found EXACT_MODEL_HTTP200 EXACT_MODEL_TEXTCHATBOX_MODEL_OK ONLINE_PROVIDER_REQUESTNO FULL_CHATBOX_RUNTIMENO这个实测证明的是 Chatbox 当前源码所需的数据形状以及精确 ID 与友好名称在本地夹具中的差异。它没有启动完整 Chatbox也没有访问真实模型服务因此不能据此推断线上价格、延迟、稳定性或模型能力。按信号判断下一步观察结果优先检查不要先做/models返回 401/403Key、权限、请求头反复改模型名/models返回 404API Host、版本前缀、服务是否提供模型目录直接点完整Check/models返回 200但没有data响应契约或服务方文档把 200 写成“模型拉取成功”data[].id可见但 Chatbox 列表为空当前版本、保存回显、客户端日志自己猜一个友好名称精确 ID 的文本请求 200再决定是否做视觉和工具测试把后续能力失败归因成 Key 失效友好名称报model_not_found逐字对比data[].id删除版本/区域后缀保存后的复核清单重新打开自定义提供商确认 API Host 和 API Path 回显正确。在模型列表中确认保存的是服务器精确 ID昵称只用于显示。先跑一个最小文本请求记录状态码和可读正文。需要能力测试时再点Check并区分基础、图像、工具三项结果。截图和日志只保留状态码、路径、模型 ID 和错误类型不保留 Authorization 值。如果服务没有/models在记录中明确写“手动添加”不要写成“自动拉取成功”。适用边界本文依据 Chatbox 官方v1.22.1和对应提交7450ab2d。后续版本可能调整按钮、测试顺序或数据适配不同 OpenAI 兼容服务也可能隐藏模型列表、使用其他路径或返回不同错误码。最终以你当前版本的设置回显、服务方公开文档和实际脱敏请求为准。不要把真实 Key 写进命令历史、文章、截图或录屏。示例中的域名和模型名都是占位符本地夹具使用固定的fixture-only请求头且只监听回环地址。总结Chatbox 获取不到模型时先把问题拆成“模型目录”“模型 ID”“能力检查”三层。Fetch要求/models返回顶层data真正请求值来自data[].idNew只是手动保存不代表服务端支持Check在基础成功后还可能继续发送图像和工具调用请求。最稳的顺序是先验/models的状态码和结构再复制精确 ID最后只用一个最小文本请求确认 200。把这三步跑通后再处理图像、工具调用或流式能力定位会清楚得多。