AI 工具提示 model not found？先按这份配置清单排查

AI 工具提示 model not found？先按这份配置清单排查

配置 Codex、ChatBox 或 Cherry Studio 这类 AI 工具时，遇到 model not found 报错的人可不少。这个报错有个特点——特别容易让人误判。

很多人第一反应是去换 API Key，或者怀疑接口地址是不是写错了。但其实更常见的原因，往往就是客户端里填的 model 和当前接口支持的模型列表没对上。

下面就从排查清单入手，一步步来捋。

先看三个核心字段

大多数 OpenAI 兼容 API 配置，绕来绕去都离不开这三项：

base_url
api_key
model

其中：

• base_url：接口入口地址，相当于门牌号。
• api_key：身份认证，相当于通行证。
• model：这次请求要调用的模型，相当于具体找谁办事。

只要 model 不在当前接口支持范围内，model not found 就很可能出现。

1. 不要手打 model，直接复制接口模型名

model 不是展示名称，也不是自己随便写的别名。很多人在这一步翻车。

常见问题：

• 多了空格
• 少了版本号
• 横线、点号写错
• 把页面上展示的名称当成了接口名
• 复制了其他平台的模型名

解决办法很简单：打开当前平台的模型列表，找到接口模型名，直接复制粘贴到客户端配置里就行。

尤其是模型名里带版本号时，千万别手打，手打几乎必出错。

2. 客户端默认模型可能不可用

很多工具会预置一个默认模型，比如 GPT-4 或者某个通用模型。但如果你用的是自定义 OpenAI 兼容接口，这个默认模型不一定存在。

于是就会出现一种让人抓狂的情况：

base_url 正确
api_key 正确
model 不匹配

请求已经发出去了，但接口侧根本找不到这个模型，直接给你一个 model not found。

推荐流程：

1. 先用平台里最基础的可用模型测试，比如最简单的轻量模型。
2. 跑通之后再切换到目标模型。
3. 保存配置后，重启工具或者新建会话。

先确认链路通不通，再调模型，这是最稳的打法。

3. 检查 Key 是否有模型权限

模型存在，不代表当前 Key 一定能调用。这就好比你有门禁卡，但某些房间的权限没开。

需要看：

• Key 是否启用
• Key 所在分组是否允许调用该模型
• 是否绑定了对应模型权限
• 账号额度或状态是否正常
• 调用日志里有没有更明确的错误提示

如果后台完全没有请求记录，优先查 base_url 和客户端配置。如果后台有请求记录，那就优先查模型名、权限和额度。

4. base_url 和 model 必须对应

不要混用不同平台的配置。举个例子，接口地址来自 A 平台，模型名却用的是 B 平台的，请求出去大概率找不到模型。

正确的做法：

base_url = 当前平台给定的接口地址
api_key = 当前平台生成的 API Key
model = 当前平台模型列表里的接口名称

这三项最好是同一个后台生成的，像三兄弟一样绑在一起。

5. 保存后确认配置已生效

有些客户端有个小毛病：保存配置后，当前会话不一定马上生效。明明改了，但请求还是用旧的配置发出去。

可以试试这几招：

• 重启客户端
• 新建一个会话
• 重新选择模型提供方
• 清掉旧的默认模型
• 再发一次最简单的测试请求

这个步骤听起来很基础，但经常能省掉一大堆无效排查。

排查表

最短排查路径

复制平台模型名
-> 替换客户端 model
-> 确认 base_url 和 model 来自同一平台
-> 检查 Key 权限
-> 重启工具
-> 看后台日志

小结

model not found 不一定是 Key 的问题。更常见的原因是模型名不匹配、客户端默认模型不可用，或者当前 Key 没有对应模型权限。

以后配置这类工具时，可以把 base_url、api_key、model 当成一组配置一起管理。这样在 Codex、ChatBox、Cherry Studio 之间切换时，能少踩很多坑。