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。
推荐流程：
- 先用平台里最基础的可用模型测试，比如最简单的轻量模型。
- 跑通之后再切换到目标模型。
- 保存配置后，重启工具或者新建会话。
先确认链路通不通，再调模型，这是最稳的打法。
3. 检查 Key 是否有模型权限
模型存在，不代表当前 Key 一定能调用。这就好比你有门禁卡，但某些房间的权限没开。
需要看：
- Key 是否启用
- Key 所在分组是否允许调用该模型
- 是否绑定了对应模型权限
- 账号额度或状态是否正常
- 调用日志里有没有更明确的错误提示
如果后台完全没有请求记录，优先查 base_url 和客户端配置。如果后台有请求记录，那就优先查模型名、权限和额度。
4. base_url 和 model 必须对应
不要混用不同平台的配置。举个例子，接口地址来自 A 平台，模型名却用的是 B 平台的，请求出去大概率找不到模型。
正确的做法：
base_url = 当前平台给定的接口地址
api_key = 当前平台生成的 API Key
model = 当前平台模型列表里的接口名称
这三项最好是同一个后台生成的，像三兄弟一样绑在一起。
5. 保存后确认配置已生效
有些客户端有个小毛病：保存配置后，当前会话不一定马上生效。明明改了，但请求还是用旧的配置发出去。
可以试试这几招：
- 重启客户端
- 新建一个会话
- 重新选择模型提供方
- 清掉旧的默认模型
- 再发一次最简单的测试请求
这个步骤听起来很基础，但经常能省掉一大堆无效排查。
排查表
| 配置项 | 重点检查 | 常见现象 |
|---|---|---|
base_url | 是否是接口地址，是否带 /v1 | 请求不到后台 |
api_key | 是否启用，是否有权限 | 认证失败或权限不足 |
model | 是否为当前平台支持的接口模型名 | model not found |
最短排查路径
复制平台模型名
-> 替换客户端 model
-> 确认 base_url 和 model 来自同一平台
-> 检查 Key 权限
-> 重启工具
-> 看后台日志
小结
model not found 不一定是 Key 的问题。更常见的原因是模型名不匹配、客户端默认模型不可用，或者当前 Key 没有对应模型权限。
以后配置这类工具时，可以把 base_url、api_key、model 当成一组配置一起管理。这样在 Codex、ChatBox、Cherry Studio 之间切换时，能少踩很多坑。
