1. Claude Code 报 model_not_found 的真实场景与排查顺序

Claude Code 报 model_not_found 这件事，本质上是「请求发出去了，但服务端不认这个模型 ID」。它和网络不通、Key 失效是三个完全不同的故障分支。我见过太多人一看到这个报错就去重新生成 API Key，或者把模型名改成聊天界面里显示的「Claude Sonnet」这种展示名，结果越改越乱。正确的排查顺序应该是：先确认 settings.json 的作用域有没有生效，再确认 ANTHROPIC_BASE_URL 指向的地址对不对，然后核对 ANTHROPIC_MODEL 这个值是不是服务端真正接受的 ID，最后用一条最小请求验证返回结果。

Claude Code 是 Anthropic 官方的命令行编码工具，它通过读取 settings.json 里的 env 字段来注入环境变量。ANTHROPIC_BASE_URL 决定请求发往哪里，ANTHROPIC_MODEL 决定请求体里带哪个模型标识。这两个变量各管一段，任何一个出问题都可能表现为 model_not_found。适合谁看？已经装好 Claude Code、已经写了 settings.json、但请求仍然报模型不存在的开发者。如果你还没配过 settings.json，这篇也能当接入教程从零跟做。

我试过把用户级和项目级两个 settings.json 同时放着，结果改了项目级却没生效，因为用户级的字段优先级更高。所以第一步永远是搞清楚你改的是哪个文件。下面按「作用域 → Base URL → 模型名 → 最小验证」四层往下走，每层都有可复制的命令和配置片段。

2. TaoToken 前置准备：拿到 Base URL 和 Key

在动手改 settings.json 之前，你需要先有一个可用的 Anthropic 兼容端点。TaoToken 提供的就是这类端点，它的 API 地址是 https://taotoken.net/api，不带任何查询参数。你需要从这里拿到两样东西：Base URL 和 API Key。

Base URL 的填写有个坑：Claude Code 的 ANTHROPIC_BASE_URL 应该填到域名加 /api 这一层，不要自己再拼 /v1/messages。Claude Code 内部会自己补上 /v1/messages 路径。如果你填成 https://taotoken.net/api/v1/messages，请求就会变成 /v1/messages/v1/messages，直接 404。这个错误在日志里看起来也像模型问题，但其实是路径拼错了。

API Key 的获取入口在控制台的 API Keys 页面。登录后创建一个新 Key，复制出来先存到密码管理器里，不要直接贴在 shell 命令里，否则会进 history。Key 的权限范围要确认包含你要用的模型，如果 Key 只开了部分模型权限，请求一个没开的模型也会返回类似 model_not_found 的错误。

模型 ID 这块要特别注意。TaoToken 的模型对话页面能看到当前可用的模型列表，但那个列表里显示的名字可能是展示名。你要复制的是模型 ID 那一列，通常是小写加连字符的格式。比如 claude-sonnet-4-20250514 这种。不要用「Claude Sonnet 4」这种带空格和大写的展示名去填 ANTHROPIC_MODEL，服务端不认。

如果你打算长期用 Claude Code 做编码，可以考虑 Coding Plan，它比按量计费更适合高频调用场景。但如果你只是先验证链路通不通，用普通 API Key 就够了。接入文档里有完整的端点说明和模型列表，配置前建议先扫一眼。

3. 可复制的 settings.json 配置片段

Claude Code 的 settings.json 分两个位置。用户级在 ~/.claude/settings.json，影响你所有项目；项目级在项目根目录的 .claude/settings.json，只影响当前项目。Windows 用户把 ~ 换成 %USERPROFILE%。两个文件同时存在时，字段的合并规则不是简单覆盖，所以排查阶段建议先用一个明确的文件做最小验证。

下面这份是最小可用配置，只包含 env 字段。你可以直接复制，把 BASE_URL 和 KEY 换成你自己的值：

{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_API_KEY": "sk-你的实际Key", "ANTHROPIC_MODEL": "claude-sonnet-4-20250514", "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-4-20250514", "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-4-20250514" } }

这里有几个字段要解释。ANTHROPIC_BASE_URL 填 https://taotoken.net/api，结尾不要带斜杠。ANTHROPIC_API_KEY 填你从控制台复制的 Key。ANTHROPIC_MODEL 是当前会话默认使用的模型。ANTHROPIC_DEFAULT_SONNET_MODEL 和 ANTHROPIC_DEFAULT_HAIKU_MODEL 是家族别名映射，Claude Code 内部有些功能会按「sonnet」「haiku」这种别名去请求，这两个变量负责把别名翻译成服务端真正接受的模型 ID。如果你只填了 ANTHROPIC_MODEL 没填这两个映射，某些子功能触发时仍然可能报 model_not_found。

如果你用的是项目级配置，路径是 .claude/settings.json，内容格式完全一样。但注意不要把真实 Key 提交到仓库。项目级配置适合放权限和工具边界，Key 建议放用户级或者用环境变量注入。

改完文件后，Claude Code 不会自动热加载。你需要退出当前会话重新启动。如果你在会话里用 /config 命令改的，也要确认它写到了哪个文件。实测下来，最稳的方式是关掉终端重开，再用下面的命令验证。

4. 验证请求与成功结果

配置写好后，不要直接跑复杂任务。先用一条最小请求验证链路。Claude Code 提供了 --print 模式，可以非交互地发一条消息：

claude --print "hello" --model claude-sonnet-4-20250514

如果返回了一段正常的文本回复，说明 Base URL、Key、模型 ID 三者都对上了。如果报错，加上 --debug 看详细日志：

claude --debug --print "hello" 2>&1 | head -50

日志里重点看三样东西。第一，请求的 URL 是不是 https://taotoken.net/api/v1/messages，如果变成了别的路径，说明 Base URL 拼错了。第二，请求体里的 model 字段值是什么，是不是你配置的那个 ID。第三，HTTP 状态码是多少。200 是成功，404 通常是模型 ID 不对或路径不对，401 是 Key 问题，403 是权限问题。

如果你想更精确地验证，可以用 curl 直接打端点，绕过 Claude Code 的封装：

curl -s -o /dev/null -w "%{http_code}" \ https://taotoken.net/api/v1/messages \ -H "x-api-key: sk-你的Key" \ -H "anthropic-version: 2023-06-01" \ -H "content-type: application/json" \ -d '{"model":"claude-sonnet-4-20250514","max_tokens":16,"messages":[{"role":"user","content":"hi"}]}'

返回 200 说明端点和模型都可用。返回 404 且错误信息里提到 model，说明模型 ID 不对。返回 401 说明 Key 无效。这个 curl 的好处是它把 Claude Code 的变量层全部剥掉了，能直接定位是配置问题还是服务端问题。

成功的结果应该是：curl 返回 200，claude --print 返回正常文本，--debug 日志里请求 URL 和模型 ID 都符合预期。三者一致，才算链路真正通了。

5. 本篇常见错误排查对照

报错一：401 Unauthorized。这个不是 model_not_found，但很多人会混淆。401 说明 Key 没被服务端认可。检查 ANTHROPIC_API_KEY 有没有多余空格，Key 有没有被撤销，请求头里是不是用的 x-api-key 而不是 Authorization Bearer。Claude Code 用的是 x-api-key 头，如果你手动 curl 时用了 Bearer，也会 401。

报错二：local proxy failed 或 connection refused。这个说明请求根本没发出去。检查 ANTHROPIC_BASE_URL 是不是写成了 localhost 或者一个不存在的地址。如果你之前配过本地代理，确认那个代理进程还在跑。TaoToken 的地址是 https://taotoken.net/api，不需要本地代理。

报错三：reading choices 或 unexpected response shape。这个通常出现在你把 OpenAI 兼容端点填给了 Claude Code。Claude Code 只认 Anthropic Messages 格式，响应体里应该是 content 数组，不是 choices。如果你看到 reading choices 报错，说明端点协议不匹配，不是模型名的问题。

报错四：OAuth 相关错误。如果你之前登录过 Anthropic 官方账号，Claude Code 可能缓存了 OAuth token，它会优先用那个 token 而不是你的 API Key。解决办法是退出登录或者删掉 ~/.claude 下的凭据缓存，强制走 API Key 模式。

报错五：model_not_found 但模型名看起来没错。这种情况检查三件事。第一，模型 ID 有没有大小写错误，服务端通常区分大小写。第二，ANTHROPIC_DEFAULT_SONNET_MODEL 有没有配，有些子请求走的是别名映射。第三，Key 的权限范围有没有包含这个模型。如果三件套（Base URL + Key + Model ID）都确认了还是 404，用 curl 直接打一次，看服务端返回的原始错误信息。

排查时建议按这个顺序：先 curl 验证端点和模型，再 claude --print 验证 CLI 配置，最后 --debug 看完整请求。每一步都确认了再往下走，不要跳步。

6. 长期使用与接入入口

链路验证通过后，如果你打算把 Claude Code 作为日常编码工具，建议把配置固化到用户级 settings.json，这样所有项目都能用。项目级配置只放跟项目相关的权限设置，不要把 Key 写进去。模型 ID 如果服务端更新了，记得同步改 ANTHROPIC_MODEL 和两个 DEFAULT 映射。

如果你需要频繁调用或者跑 Agent 类任务，Coding Plan 的额度模型比按量计费更划算。如果只是偶尔用，普通 API Key 就够了。模型对话页面可以快速测试某个模型 ID 是否可用，不用每次都开终端。完整的端点说明和模型列表在接入文档里，配置前扫一眼能省很多排查时间。

最后提醒一句：settings.json 里的 Key 是明文存储的，不要把用户级配置文件同步到公开仓库或者云盘。如果 Key 泄露了，第一时间去控制台撤销重新生成。排错截图只保留状态码和模型 ID，Key 和请求体都要打码。