在接入 Claude API、Claude Code、Cursor 或 OpenAI 兼容网关时很多开发者会遇到类似下面的报错model_not_found 404 Model Not Found is not a valid model ID invalid_request_error: model这类问题不一定是代码逻辑写错了。更常见的原因是请求里最终发送出去的model当前 API 服务并不认识。尤其是在下面这些场景中model_not_found很容易出现使用 Anthropic 官方 API使用 OpenAI SDK 调用 Claude 兼容接口使用第三方 API 网关或路由器在 Claude Code 中配置自定义 Endpoint在 Cursor、Continue、Roo Code 等 IDE 工具中配置 Claude项目.env、环境变量、插件配置互相覆盖。本文按实际排查顺序整理一套可复现的处理方法重点讲清楚model_not_found到底是什么意思model、base_url、API Key 为什么必须匹配Claude Code / Cursor / OpenAI SDK 里应该检查哪些配置如何用最小请求快速验证模型是否可用。一、先记住核心原则谁接收请求谁解释 model排查 Claude API 的model_not_found最重要的一句话是base_url指向哪个平台model就必须填写哪个平台支持的模型名。也就是说请求发到 Anthropic 官方 API就使用 Anthropic 官方支持的 model ID请求发到 OpenAI 兼容网关就使用该网关支持的模型名请求发到路由器、LiteLLM 或自建代理就看路由器里如何配置模型映射请求由 Claude Code、Cursor 或插件发出就要确认工具最终生效的配置是什么。不要只问这个 Claude 模型名对不对而要问这个模型名对当前这个base_url来说对不对很多错误都来自把 A 平台的模型名复制到了 B 平台。例如某些平台使用anthropic/xxx这种写法但它不一定能直接用于 Anthropic 官方接口。二、model_not_found 常见原因速查遇到model_not_found建议优先检查下面 6 类问题。原因典型表现处理方式模型名拼错model_not_found、is not a valid model ID去当前平台模型列表复制完整 model ID把展示名当成 model ID写成Claude 3.5 Sonnet不要写产品展示名使用接口要求的模型 ID模型名属于其他平台使用anthropic/xxx、平台专用别名换成当前base_url支持的名称base_url和模型名不匹配官方 URL 第三方模型名或反过来统一 URL、Key、模型名来源API Key 没有权限模型列表有但调用失败检查账号、项目、组织、分组、渠道权限环境变量或工具配置覆盖代码已改但仍报旧模型错误检查.env、全局变量、Claude Code/Cursor 配置简单说排查顺序应该是先确认最终请求里真正发送的model再确认请求实际发往哪个base_url最后确认 API Key 是否属于同一平台并具备调用权限。三、确认你调用的是哪一种 Claude API在排查前先判断当前项目属于哪种接入方式。1. Anthropic 官方 API如果你直接请求的是https://api.anthropic.com/v1/messages或者使用的是 Anthropic 官方 SDK那么模型名应该使用 Anthropic 官方当前支持的 model ID。官方接口常见请求结构如下curl https://api.anthropic.com/v1/messages \ -H x-api-key: $ANTHROPIC_API_KEY \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: 替换为官方支持的模型ID, max_tokens: 100, messages: [ { role: user, content: Hello } ] }这里必须保持三者一致URLAnthropic 官方接口KeyAnthropic 官方 API KeymodelAnthropic 官方支持的 model ID。不要在官方接口里直接填写Claude 3.5 Sonnet claude-sonnet anthropic/xxx这些可能是展示名、简写名或者其他平台的模型命名方式不一定能被官方 API 识别。2. Anthropic Python SDK如果你使用anthropicSDK最小测试代码可以写成from anthropic import Anthropic client Anthropic( api_key你的 Anthropic API Key ) message client.messages.create( model替换为官方支持的模型ID, max_tokens100, messages[ { role: user, content: Hello } ], ) print(message)如果这段最小代码仍然报model_not_found优先检查model是否为官方当前支持的完整 model IDAPI Key 是否有效当前账号或项目是否有该模型权限是否被环境变量覆盖了模型名。3. OpenAI 兼容接口调用 Claude很多网关、聚合平台、自建路由器会提供 OpenAI 兼容格式此时你可能写的是from openai import OpenAI client OpenAI( api_key你的第三方平台 Key, base_urlhttps://你的平台域名/v1 ) resp client.chat.completions.create( model替换为该平台支持的 Claude 模型名, messages[ { role: user, content: Hello } ] ) print(resp)这里要特别注意你虽然使用的是 OpenAI SDK但请求并不一定发往 OpenAI 官方接口。真正决定模型名如何解析的是base_urlhttps://你的平台域名/v1因此base_url指向哪个平台就去哪个平台复制模型名不要默认认为 Anthropic 官方 model ID 一定能在该平台使用也不要把 OpenRouter、LiteLLM、其他网关的模型名直接复制过来。如果base_url没有配置OpenAI SDK 可能会使用默认地址。此时你再传入 Claude 模型名就很容易出现模型不存在或不支持的问题。4. Claude CodeClaude Code 中的模型名可能来自多个位置不一定只看你命令行里写了什么。常见相关环境变量包括ANTHROPIC_MODEL ANTHROPIC_BASE_URL ANTHROPIC_AUTH_TOKEN如果是通过 OpenAI 兼容方式间接调用还可能涉及OPENAI_BASE_URL OPENAI_API_KEY可以先查看当前环境变量env | grep -E ANTHROPIC|OPENAIWindows PowerShell 使用Get-ChildItem Env: | Where-Object { $_.Name -match ANTHROPIC|OPENAI }如果你通过命令行指定模型可以这样测试claude --model 替换为当前接入平台支持的模型名如果仍然报model_not_found继续检查ANTHROPIC_MODEL是否还是旧模型ANTHROPIC_BASE_URL是否指向正确平台ANTHROPIC_AUTH_TOKEN是否与该平台匹配工具内部/model是否覆盖了命令行配置项目.env是否覆盖了全局变量。5. Cursor / Continue / Roo Code 等 IDE 工具IDE 工具里模型配置通常更复杂可能同时存在内置模型选择自定义 API Key自定义 Base URL项目级配置插件级配置全局配置.env文件路由器配置。如果在 Cursor 中调用 Claude 报模型不存在建议按下面顺序查当前使用的是内置模型还是自定义 API自定义 Base URL 是否正确API Key 是否属于该 Base URL 对应的平台模型名是否来自该平台模型列表项目级配置是否覆盖了全局设置插件或扩展是否有单独模型配置。很多时候界面里看起来已经修改了模型但实际请求仍然被插件配置或环境变量覆盖。四、模型名最容易写错的几种方式model_not_found中最常见的问题是模型名不符合当前接口要求。下面是一些典型错误。错误类型错误示例问题原因正确处理把展示名当成接口 IDClaude 3.5 Sonnet这是给人看的产品名不一定是 API ID去平台模型列表复制 model ID使用简写claude-sonnet平台无法判断具体模型或版本使用完整模型名缺少版本信息claude-3-5-sonnet可能缺少平台要求的后缀按文档填写完整 ID跨平台复制anthropic/claude-xxx可能是路由平台格式使用当前接口支持的格式使用旧模型claude-3-5-sonnet-20241022当前平台可能未上架或已替换查询最新模型列表环境变量覆盖代码里是新模型实际请求还是旧模型.env或全局变量优先级更高打印最终请求体确认URL 与模型不匹配官方 Key 第三方模型名URL、Key、模型名不在同一体系统一三者来源注意Claude 模型名不是自然语言名称而是平台定义好的精确字符串。以下内容都可能影响识别大小写横线前缀日期后缀provider 前缀路由器别名平台内部映射。所以不建议手打最好从当前平台的模型列表中复制。五、重点检查 base_url、API Key、model 是否属于同一平台这是整个排查过程中最关键的一步。常见错误组合如下。组合可能问题Anthropic 官方base_urlanthropic/xxxanthropic/xxx通常不是官方 API 直接使用的格式第三方网关base_url 官方 model ID网关不一定支持或映射该模型名OpenAI SDK 默认base_url Claude 模型名请求可能发到了 OpenAI 官方接口API Key 来自 A 平台base_url指向 B 平台鉴权和模型解析都可能失败路由器配置 Claude Provider 错误模型前缀Provider 无法识别模型名自建网关未配置模型映射网关找不到真实上游模型建议你在代码里临时打印以下信息print(base_url:, client.base_url) print(model:, model)如果是 Node.js 项目可以打印环境变量console.log(ANTHROPIC_MODEL:, process.env.ANTHROPIC_MODEL) console.log(ANTHROPIC_BASE_URL:, process.env.ANTHROPIC_BASE_URL) console.log(OPENAI_BASE_URL:, process.env.OPENAI_BASE_URL)如果项目封装比较深最好在发送请求前打印最终请求体确认实际发出的 JSON 里model到底是什么。六、检查环境变量和配置文件覆盖很多项目里模型名并不只写在代码中还可能出现在配置文件和环境变量里。优先检查这些环境变量ANTHROPIC_MODEL ANTHROPIC_BASE_URL ANTHROPIC_AUTH_TOKEN OPENAI_BASE_URL OPENAI_API_KEYLinux / macOSenv | grep -E ANTHROPIC|OPENAIWindows PowerShellGet-ChildItem Env: | Where-Object { $_.Name -match ANTHROPIC|OPENAI }同时检查项目目录中是否存在.env .env.local config.json settings.json config.yaml docker-compose.yml很多开源项目会把模型名写在.env或docker-compose.yml里例如ANTHROPIC_MODEL旧模型名 ANTHROPIC_BASE_URLhttps://某个旧地址即使你在代码里改了模型名运行时仍然可能优先读取.env。建议排查时临时做三件事删除或注释旧的模型环境变量重启终端、IDE 或容器在请求前打印最终配置。如果是在 Docker 环境里还要检查environment: - ANTHROPIC_MODELxxx - ANTHROPIC_BASE_URLxxx修改后需要重新启动容器否则旧环境变量仍然生效。七、用最小请求验证 Key、URL、模型名是否可用业务代码中可能有框架封装、重试逻辑、代理配置、插件缓存。为了排除干扰建议先用最小请求测试。最小请求只验证一件事当前 API Key 当前 base_url 当前 model 组合是否可调用。1. 官方 Anthropic API 最小 curlcurl https://api.anthropic.com/v1/messages \ -H x-api-key: $ANTHROPIC_API_KEY \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: 替换为官方支持的模型ID, max_tokens: 100, messages: [ { role: user, content: Hello } ] }重点检查URL 是否为 Anthropic 官方 APIx-api-key是否为对应的 Anthropic API Keymodel是否来自官方当前支持列表anthropic-version是否正确传入请求体是否为合法 JSON。2. Anthropic SDK 最小 Python 示例from anthropic import Anthropic client Anthropic( api_key你的 Anthropic API Key ) resp client.messages.create( model替换为官方支持的模型ID, max_tokens100, messages[ { role: user, content: Hello } ] ) print(resp)如果最小示例成功而业务项目失败说明问题大概率在项目配置覆盖框架默认模型环境变量网关配置请求构造逻辑。如果最小示例也失败优先回到模型名、Key 权限、接口地址这三项。3. OpenAI 兼容接口最小 Python 示例from openai import OpenAI client OpenAI( api_key你的第三方平台 Key, base_urlhttps://你的平台域名/v1 ) resp client.chat.completions.create( model替换为该平台支持的 Claude 模型名, messages[ { role: user, content: Hello } ] ) print(resp)这里最容易出错的是忘记设置base_urlapi_key和base_url不是同一平台model复制了其他平台的写法网关没有上架该模型网关模型别名没有正确映射。4. Claude Code 最小测试claude --model 替换为当前接入平台支持的模型名如果失败查看环境变量echo $ANTHROPIC_MODEL echo $ANTHROPIC_BASE_URL echo $ANTHROPIC_AUTH_TOKEN如果使用的是 OpenAI 兼容方式还要看echo $OPENAI_BASE_URL echo $OPENAI_API_KEY必要时重启终端或 IDE避免旧变量继续生效。八、不同场景的快速修复方法1. Python 项目报 model_not_found先判断使用的是哪个 SDK。如果是from anthropic import Anthropic排查重点使用 Anthropic 官方模型 ID不要填写anthropic/xxx不要填写第三方平台别名确认 API Key 来自 Anthropic 官方检查ANTHROPIC_MODEL是否覆盖代码。如果是from openai import OpenAI排查重点是否正确设置base_urlapi_key是否属于这个base_urlmodel是否来自该平台模型列表是否误用了 OpenAI 默认地址。2. Node.js 项目报 model_not_foundNode.js 项目里配置通常分散在代码、.env和框架配置中。可以先打印console.log(process.env.ANTHROPIC_MODEL) console.log(process.env.ANTHROPIC_BASE_URL) console.log(process.env.OPENAI_BASE_URL)然后确认最终传入请求的model。如果使用了框架或封装库还要检查默认模型配置provider 配置router 配置.env.local是否覆盖.env部署平台环境变量是否覆盖本地配置。3. curl 报 404 Model Not Foundcurl最容易定位问题直接看两处请求 URLhttps://xxx/v1/messages请求体{ model: xxx }如果 URL 和模型名不是同一平台体系先统一这两个配置。例如官方 URL 就用官方模型 ID网关 URL 就用网关支持的模型名路由器 URL 就看路由器配置的别名或映射。4. Claude Code 报 model_not_found推荐排查顺序查看ANTHROPIC_MODEL查看ANTHROPIC_BASE_URL查看ANTHROPIC_AUTH_TOKEN确认命令行是否传了--model查看工具内部/model设置检查项目.env检查全局配置重启终端或 Claude Code使用当前平台明确支持的模型做最小测试。5. Cursor 调用 Claude 报模型不存在Cursor 里可能存在多套配置Cursor 内置模型自定义 API Key自定义 Base URL项目级配置插件配置全局设置。如果你接入的是自定义网关要确认Base URL 是否为网关地址API Key 是否为该网关的 Key模型名是否为该网关支持的名称没有混用其他教程里的模型 ID。6. 路由器或 OpenRouter 风格模型名无效provider/model形式的模型名通常属于某些路由平台或聚合平台。它不一定适用于Anthropic 官方 API其他第三方网关自建 OpenAI 兼容接口Claude Code 默认配置。如果你使用自建路由器还要检查provider 名称是否正确provider 是否启用模型别名是否映射到真实上游上游api_base_url是否正确上游 Key 是否有调用权限当前渠道是否支持该模型。九、为什么模型列表里有调用时却说不存在这个问题也很常见不一定是拼写错误。可能原因包括1. 当前 Key 没有权限平台页面能展示某个模型不代表你的账号、项目、组织或分组一定有调用权限。需要确认Key 是否属于当前账号当前项目是否允许调用该模型组织或分组是否有限制是否需要额外开通。2. 第三方平台渠道不可用如果使用网关或聚合平台可能存在分组限制渠道不可用上游线路异常模型未映射当前线路未上架该模型。前端能看到模型不代表这次请求一定可以成功路由。3. 模型只支持特定接口有些模型可能只在特定接口下暴露例如messages 接口chat completions 兼容接口某个 provider 的专用接口。如果接口类型不匹配也可能出现模型相关错误。4. 模型别名没有正确映射自建路由器中经常会配置类似model_name: xxx litellm_params: model: yyy如果别名xxx没有正确映射到真实上游模型yyy网关就可能返回model_not_found。5. 工具仍然缓存旧配置Claude Code、Cursor、IDE 插件可能继续使用旧配置。建议重启 IDE重启终端清理项目.env检查全局配置打印最终请求体用最小请求绕过业务代码验证。十、FAQ1. Claude API 模型名可以写claude-sonnet吗不建议。claude-sonnet多数情况下只是简写当前平台未必能识别。更稳妥的方式是从当前平台模型列表中复制完整 model ID。2. Anthropic 官方模型名和 OpenAI 兼容接口模型名一样吗不一定。OpenAI 兼容接口中的model字段由对应平台解释。它可能使用官方 ID也可能使用简化 ID或者使用带 provider 前缀的 ID。3.anthropic/claude-xxx能直接用于 Anthropic 官方 API 吗通常不能直接照搬。anthropic/xxx更常见于某些路由平台或聚合平台。官方接口应使用 Anthropic 官方支持的 model ID。4.model_not_found和invalid_request_error有什么区别model_not_found更偏向于模型无法识别。invalid_request_error范围更宽可能是请求体格式错误参数不合法模型名不合法接口类型不匹配SDK 参数使用错误。实际排查时要结合完整错误信息看。5. 模型下线或改名后怎么办不要把模型名长期硬编码在业务代码里。建议把模型名放到配置项中例如ANTHROPIC_MODEL替换为当前可用模型然后定期对照当前平台模型列表更新。总结Claude API、Claude Code 或 Cursor 报model_not_found时建议按下面顺序排查打印最终请求体确认实际发送的model查看base_url确认请求发往哪个平台到该平台模型列表复制模型名不要手打确认 API Key 和base_url属于同一平台检查ANTHROPIC_MODEL、ANTHROPIC_BASE_URL、OPENAI_BASE_URL等环境变量检查 Claude Code、Cursor、插件和项目.env是否覆盖配置如果使用路由器检查 provider、模型映射和上游接口用最小请求验证 Key、URL、模型名组合是否可用。归根结底核心原则只有一个base_url决定由谁解释模型名model必须来自同一个平台的可用模型列表。