Claude Code model not found 怎么排查：入口、Key 和模型映射

model not found 是什么意思

如果 Claude Code 能进入 CLI，但发出第一轮请求后返回 model not found、not_found_error 或模型不存在，先保留错误片段，再按入口、Key、模型名和网关映射逐层查。

不要同时修改 URL、Token、模型名和代理地址。这个错误有时确实是模型名错了，但入口格式错、Key 对不上供应商、网关没有映射、旧终端变量残留，也会落到同一个表现。

model: not_found_error
message: model not found

哪些日志值得先保存

先把错误里和模型、入口、状态码有关的几行保存下来。不要保存真实 API Key、Authorization header 或完整 Token。

如果日志里出现的是 404 endpoint not found，优先去看入口路径；如果明确出现 model not found，再继续检查模型名和网关映射。

• 错误名：not_found_error、model not found、model not available
• 请求入口：当前 ANTHROPIC_BASE_URL 指向哪个服务
• 模型名：Claude Code 实际发出的主模型和 Haiku / 子任务模型
• 网关：是否经过 LiteLLM、OpenRouter、公司代理或本地转发

入口地址会不会填错

第一步检查 ANTHROPIC_BASE_URL。Claude Code 需要 Anthropic-compatible 入口，不是 OpenAI-compatible 入口。入口填错时，错误不一定写成 404，也可能表现成 model not found。

DeepSeek 的 Anthropic 格式入口是 https://api.deepseek.com/anthropic。不要填 https://api.deepseek.com，也不要自己追加 /v1/messages。

$env:ANTHROPIC_BASE_URL

Key 和模型名要不要同一家

入口、Key 和模型名要来自同一家供应商。DeepSeek 的入口配 GLM、MiniMax 或公司网关里的模型名，不一定会请求到你以为的模型；经过网关时，还可能返回 model not found。

Token 不要完整打印到屏幕。只看长度，再确认当前 shell 里读到的主模型名、Haiku 模型名和子任务模型名。

$env:ANTHROPIC_AUTH_TOKEN.Length
$env:ANTHROPIC_MODEL
$env:ANTHROPIC_DEFAULT_HAIKU_MODEL
$env:CLAUDE_CODE_SUBAGENT_MODEL

如果你使用 ANTHROPIC_API_KEY 而不是 ANTHROPIC_AUTH_TOKEN，也要用同样方式确认当前 shell 里读到的是目标供应商的 Key。

推荐的最小复现配置

如果你改过很多轮配置，先开一个新的 PowerShell，只放入口、Key 和一个明确模型。这样可以把“当前进程没读到配置”和“模型名不可用”分开。

示例模型名来自 DeepSeek 官方 Claude Code 文档。DeepSeek 文档说明，不支持的模型名会映射到 deepseek-v4-flash；如果你接的是其它供应商或网关，把入口、Key 和模型名全部换成同一家文档里的值。

$env:ANTHROPIC_BASE_URL="https://api.deepseek.com/anthropic"
$env:ANTHROPIC_AUTH_TOKEN="<你的 DeepSeek API Key>"
$env:ANTHROPIC_MODEL="deepseek-v4-flash"

怎么确认模型名真的生效

最小配置进入当前 PowerShell 后，再启动 Claude Code。先指定同一个明确模型，避免 DEFAULT 模型变量把请求切到另一个名字。

如果这一步成功，再把 Opus、Sonnet、Haiku 和子任务模型逐个加回去。加回某一项后又报 model not found，问题就在那一个模型名或网关映射上。

claude --model deepseek-v4-flash

网关模型映射会不会出错

如果你通过 LiteLLM、OpenRouter、公司代理或本地转发访问模型，供应商原始模型名不一定能直接用。网关可能要求你使用它自己的模型别名。

这时不要继续猜模型名。去网关配置或网关文档里确认 Claude Code 发出的模型名会被映射到哪个真实模型，以及这个模型是否允许当前 Key 调用。

网关只配置了真实模型名，没有配置 Claude Code 发出的别名

在网关里增加模型别名映射，或者把 ANTHROPIC_MODEL 改成网关已经允许的别名。

主模型能用，Haiku 或子任务模型报找不到

继续检查 ANTHROPIC_DEFAULT_HAIKU_MODEL 和 CLAUDE_CODE_SUBAGENT_MODEL。Claude Code 不只会请求主模型。

同一个模型在 OpenAI SDK 能用，在 Claude Code 不能用

先确认网关是否支持 Anthropic Messages。OpenAI-compatible 可用，不等于 Claude Code 的 Anthropic 请求可用。

旧环境变量会不会覆盖新模型

旧终端里可能还留着之前的 ANTHROPIC_BASE_URL、ANTHROPIC_MODEL 或 DEFAULT 模型变量。你在系统设置或 settings 文件里改了值，旧进程不一定会刷新。

临时排查时，建议新开 PowerShell。需要在当前窗口继续排查时，可以先清理这几个变量，再重新放入最小配置。

Remove-Item Env:ANTHROPIC_BASE_URL -ErrorAction SilentlyContinue
Remove-Item Env:ANTHROPIC_MODEL -ErrorAction SilentlyContinue
Remove-Item Env:ANTHROPIC_DEFAULT_OPUS_MODEL -ErrorAction SilentlyContinue
Remove-Item Env:ANTHROPIC_DEFAULT_SONNET_MODEL -ErrorAction SilentlyContinue
Remove-Item Env:ANTHROPIC_DEFAULT_HAIKU_MODEL -ErrorAction SilentlyContinue
Remove-Item Env:CLAUDE_CODE_SUBAGENT_MODEL -ErrorAction SilentlyContinue

模型是不是下线或没权限

只有当入口、Key、当前变量和网关映射都确认没问题时，再判断模型是否下线、改名或没有权限。供应商模型名会变，旧教程里的模型名最容易在这一步失效。

重新打开供应商模型列表，按当前文档填模型名。最后审校日期是 2026-06-17；如果你隔一段时间再看，先复查模型列表和网关入口。

• 官方文档里已经没有这个模型名：按新模型名更新 ANTHROPIC_MODEL 和 DEFAULT 模型变量。
• DeepSeek 旧模型名发生兼容迁移：按当前 Anthropic API 文档确认映射关系，再决定是否显式填写 deepseek-v4-pro 或 deepseek-v4-flash。
• 账号没有权限调用这个模型：换成当前账号可用的模型，或在供应商后台开通权限。
• 网关管理员限制了模型列表：使用网关允许的别名，不要直接套供应商原始模型名。

修完后怎么确认不再报错

修复后不要只看 Claude Code 有没有启动。成功标准是第一轮请求能返回、子任务模型不再报找不到、启动后没有同时出现 404 或 unsupported parameter。

参考来源

相关文章