💡 直接答案
model not found 通常表示请求的模型名没有被当前 API 服务识别。优先检查模型名是否和后台模型列表完全一致、Base URL 是否填对、/v1 是否符合当前 API 格式、账号是否有模型权限。Claude Code 原生模式通常不带 /v1，Codex 和 Cursor 通常带 /v1。
model not found 是什么意思？
model not found 通常不是 Key 完全无效，更多表示以下几类问题：
看到这类错误时，先核对原始错误文本和常见变体，再按顺序排查：
| 原始错误文本 | 常见变体或包装 | 说明 |
|---|---|---|
model not found |
模型不存在、模型未找到 | 最标准的错误文本 |
model_not_found |
模型不存在（下划线） | 不同客户端或平台的写法差异 |
model is not available |
模型不可用、当前模型不可用 | 部分工具会把权限或渠道问题包装成可用性 |
the model 'xxx' does not exist |
该模型不存在 | 常见于 Cursor、Cline 等工具的提示 |
Model not found or not supported |
模型不存在或不被支持 | 强调模型不被当前服务支持 |
有些工具会把 model not found 显示为 404、model_not_found、模型不存在、model is not available 等变体，排查思路相同。
- 模型名写错：请求的模型名和后台实际路由 ID 不匹配
- 模型不存在：该模型在当前 API 服务中没有被配置或开通
- Base URL 模式不匹配：Anthropic 原生模式和 OpenAI-compatible 模式路由不同
- 路由路径不对：请求发送到了错误的路径，例如本应发 /v1/chat/completions 却发到了 /v1/models
- 工具不支持该模型：部分工具本身不支持某些模型，会包装成 model not found
有些工具会把 model not found 显示为 404、model_not_found、模型不存在、model is not available 等变体，排查思路相同。
不要看到 model not found 就直接判断为服务不可用或 Key 无效，先按以下顺序排查。
model not found 和 401 / 403 / 404 有什么区别？
| 错误码 | 含义 | 常见原因 | 排查方向 |
|---|---|---|---|
| 401 invalid_api_key | API Key 无效、缺失或未被识别 | Key 错误、过期、复制多空格、Key 和 Base URL 不属于同一平台 | 检查 Key 完整性、Base URL 是否匹配 |
| 403 permission denied | API Key 可能有效，但没有目标模型权限 | 账号分组无权限、渠道未开通、模型开关关闭 | 检查后台模型权限、分组、渠道配置 |
| 404 / model not found | 模型名不存在、路由不到、Base URL 模式不匹配 | 模型名写错、模型未开通、请求了后端没有的模型 ID、/v1 缺失或多余 | 检查模型名、Base URL、/v1 格式 |
| 429 rate limit | 频率或额度限制 | 请求太密、并发太高、账户额度不足 | 降低并发、检查账户余额 |
| 503 / 524 | 上游不可用 / 代理层等待超时 | 渠道异常、503 为上游不可用；524 为长请求代理超时 | 检查渠道状态；长任务可尝试 api2 通道 |
model not found 更多偏向模型名或路由问题，403 偏向权限问题。但部分工具会把权限问题包装成模型不可用，建议两者都检查。
第一步：检查模型名是否和后台列表完全一致
这是 model not found 最常见的原因。
模型名不能靠猜
API 对模型名是精确匹配，大小写、横线、下划线、小数点、版本号都要完全一致。以下是常见错误：
claude-opus-4.7和claude-opus-4-7—— 看起来相似，但是不同的模型 IDGPT-4o和gpt-4o—— 大小写不同claude-sonnet-4-20250514和claude-sonnet-4-20250515—— 日期版本不同
模型名应以 LinkAI 后台模型列表为准
不要直接填写前端展示名（如"Claude Opus"），要填写后台模型列表中的实际模型 ID。如果后台列表里没有该模型，请不要填写。
如果不确定当前有哪些可用模型，可以：
- 在 LinkAI 控制台查看已开通的模型列表
- 用 curl 测试：
curl https://api1.link-ai.cc/v1/models -H "Authorization: Bearer 你的APIKey" - 如果 ccSwitch 获取模型列表失败，可以先手动填后台确认存在的模型名
第二步：检查 Base URL 和 /v1 是否匹配当前 API 格式
不同工具使用的 API 格式不同，Base URL 的填写方式也不同。/v1 多了或少了，都可能导致 model not found 或 404。
Claude Code / Anthropic Messages 原生模式
Claude Code 在 Anthropic Messages 原生模式下通常不带 /v1：
- 普通请求：
https://api1.link-ai.cc - 长请求或大上下文：
https://api2.link-ai.cc
Codex / Cursor / OpenAI-compatible 模式
Codex、Cursor 和其他 OpenAI-compatible 客户端通常带 /v1：
- 普通请求：
https://api1.link-ai.cc/v1 - 长请求或大上下文：
https://api2.link-ai.cc/v1
Claude Code Anthropic Messages 原生模式通常不带 /v1；Codex、Cursor、OpenAI-compatible 模式通常带 /v1。如果模式错了，请求可能发送到错误的路由，返回 model not found 或 404。
更多 Base URL 填写说明，参考 Claude Code / Codex / Cursor Base URL 对照表。
第三步：检查账号是否有目标模型权限
有余额不代表有所有模型权限。
- 分组权限：账号所属分组决定了能看到和调用哪些模型
- 渠道权限：部分模型需要开通特定渠道才能调用
- 模型开关：后台可以对单个模型单独开启或关闭
如果是 403，更偏权限问题。如果是 model not found，更偏模型名或路由问题。但部分工具会把权限问题包装成模型不可用。
建议先用后台可见的模型进行小额测试，查看 usage 是否返回、扣费记录是否正常。具体模型权限以后台模型列表和实际请求结果为准。
更多安全检查清单，参考 API 中转站风险清单。
Cursor、Codex、Claude Code 分别怎么排查？
Cursor
Cursor 通常走 OpenAI-compatible 格式：
- Base URL 常见为
https://api1.link-ai.cc/v1 - 403 问题多看模型权限，403 与权限、分组、渠道有关
- model not found 多看模型名是否存在于后台列表
详见 Cursor 自定义 API Provider 配置。
Codex
Codex 通常走 OpenAI-compatible 格式：
- Base URL 常见为
https://api1.link-ai.cc/v1 - 不要填写 Claude Code Anthropic Messages 原生模式常用的地址（不带 /v1）
- 模型名以后台模型列表为准，不要直接填 claude-opus 等展示名
Claude Code / ccSwitch
Claude Code 在 Anthropic Messages 原生模式下：
- Base URL 通常不带 /v1
- 普通请求：
https://api1.link-ai.cc - 长请求或 524/503 超时场景可尝试：
https://api2.link-ai.cc - ccSwitch 获取模型列表失败不一定代表不能用，可以先手动填后台确认存在的模型名测试
详见 Claude Code 524 / 503 超时排查。
获取模型列表失败怎么办？
ccSwitch 或其他工具获取模型列表失败不一定代表 API 不能用。
- 部分工具获取模型列表依赖
/v1/models接口 - Anthropic Messages 原生模式或某些工具的模型发现逻辑和实际请求路径可能不同
- 可以先手动填写后台确认存在的模型名，再用一个短请求测试
- 如果短请求成功，说明模型列表获取失败不影响实际调用
OpenAI-compatible 格式可以用以下命令测试模型列表是否正常：
curl https://api1.link-ai.cc/v1/models \
-H "Authorization: Bearer 你的APIKey"如果返回模型列表，说明 API 路由正常，可以手动填写模型名继续使用。
不确定配置是否正确怎么办？
可以用 AI API Doctor 检查 Base URL、API Key、模型权限和常见错误：
AI API Doctor 是独立的 API 配置诊断工具，可辅助检查配置是否正确。最终是否可用仍应以客户端实际请求结果和后台记录为准。
FAQ
https://api1.link-ai.cc。长请求场景可以尝试 https://api2.link-ai.cc。如果使用 OpenAI-compatible 模式，则通常需要带 /v1，例如 https://api1.link-ai.cc/v1。https://api1.link-ai.cc/v1（普通请求）或 https://api2.link-ai.cc/v1（长任务）。不带 /v1 会导致路径错误，返回 404 或 model not found。