企业官网建设流程全解析

Claude Code Router 报 model not found 怎么排查

【免费下载链接】claude-code-routerOne local control plane for every AI agent: route across models, fuse new capabilities, orchestrate tools, and stay fully in control.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-code-router

在 Claude Code Router（下文简称 CCR）中，Agent 或客户端发起模型请求时报model not found，通常意味着路由解析出的模型名不在供应商的模型列表里。模型名同时出现在三个地方：供应商模型列表、路由配置选中的模型、Agent 配置里的模型。排查任务就是把这三处的模型名逐一比对，找到不一致的位置并改过来，最后用连通性检测和请求日志确认修复生效。

前提：CCR 已在运行，你能进入桌面端的管理页面（供应商、路由、Agent 配置、设置等入口）。整个排查过程不修改 CCR 仓库代码，只在 CCR 界面内查看和修改配置。

第一步：开启请求日志，确认是哪条请求在失败

model not found可能是某一次特定请求的报错，先固定现场：

1. 到设置 → 日志与观测，打开请求日志（可选地同时打开Agent 观测）。
2. 重新触发一次会报错的 Agent 任务。
3. 打开日志页，按状态、供应商、模型、凭据、请求 ID、模型名、请求体或响应体筛选，找到失败的那条记录。

单条日志会展示request model（客户端原始请求模型）、resolved provider（最终命中的供应商）、resolved model（最终请求的模型）、状态码、响应体、错误信息、耗时、token 和成本估算。记下这三个模型相关字段的具体值，它们是后续比对的基准。

注意两点限制：请求日志只记录开关打开之后新执行的请求；普通请求日志只保留本地当天的数据，进入第二天后会被清理，所以排查要在报错当天完成。日志能力与字段说明见 日志与可观测性 和 开启日志与观测。

第二步：比对三处模型名

按 常见问题 中的结论，模型名出现在三个地方，逐一对比，把不一致的地方改过来。

1. 供应商模型列表

供应商页面里的模型字段是暴露给 CCR 的模型 ID 列表，路由规则、Agent 配置的模型选择、模型目录和客户端/models响应都基于这里。如果路由解析出的模型不在这个列表里，请求就会失败。

进入供应商页面，编辑对应供应商，检查：

• 模型列表里是否包含目标模型 ID。探测不到时可以手动添加：列表旁有搜索模型 / 全部 / 清除和自定义模型，后者适合供应商没有/models接口或新模型还未进入模型目录的情况。
• 自动探测结果不理想时，可在高级设置中关闭自动探测并手动选择协议（OpenAI Chat、OpenAI Responses、Anthropic Messages、Gemini 生成、Gemini Interactions 等）。协议选错也会导致模型探测结果不对。

这一步的详细说明见 接入供应商 和 供应商配置。

2. 路由配置选中的模型

进入路由页面，检查自定义路由规则：

• 规则按列表顺序匹配，第一条命中的启用规则会改写请求。最常用的是改写请求参数中设置request.body.model = 供应商/模型，确认这里填写的目标模型确实存在于目标供应商的模型列表里。
• 注意规则顺序和匹配条件：条件或顺序不对时，请求可能被改写到你以为不会命中的模型上。
• 如果启用了回退（失败时或页面顶部的默认失败处理），降级目标模型同样必须是已配置模型，检查降级链上的每一环。

改完后如何判断规则是否命中：请求日志里的request model、resolved provider、resolved model和路由原因可以用来确认。如果日志里的resolved model不是你预期的模型，说明路由配置仍是问题所在。配置细节与验证方式见 智能路由。

3. Agent 配置里的模型

进入Agent 配置页面，打开对应配置，检查模型字段：

• 模型值格式是供应商名称/模型名称，供应商名称必须是 CCR 里保存的供应商名称，模型名必须是该供应商模型列表中的模型 ID，两者都要与前面两处一致。
• 如果你的 Agent 是从 CCR 打开的（ccr <配置名称>或桌面端终端/播放图标），该配置的模型就是请求的默认来源；Claude Code CLI 也可以在会话内用/model查看并切换 CCR 暴露的模型列表，确认当前选中项。
• 顺带确认配置已应用、启用开关打开、作用范围覆盖当前项目，排除“请求根本没走这条配置”的情况。

说明见 Agent 配置。

验证修复

改完不一致的地方后，用两个方式验证：

1. 检测连通性：在供应商编辑页点击检测连通性，CCR 会用当前的 API 地址、密钥、协议和所选模型发送一次真实请求，结果会展示每个模型是否可用、命中的协议和上游返回的诊断信息。它验证的正是 Key、模型名和协议是否真的可调用。注意检测是真实请求，会限制输出长度但仍可能产生少量 token 消耗或计入供应商侧请求次数，所以通过要检测的模型弹窗只勾选需要确认的模型。检测结果不会自动修改模型列表，可用与否仍以供应商表单中的模型勾选为准。
2. 重发请求 + 看请求日志：重新发起一次 Agent 任务，到日志页确认这条请求的resolved model已是目标模型、状态码正常且错误信息消失。如果发生了回退，响应头里会带有x-ccr-fallback-attempts、x-ccr-fallback-failures和最终命中的x-ccr-fallback-model，日志详情里也会显示关联的重试尝试列表——看到这些说明主模型仍在失败、系统切到了备用模型，要继续对照上一步的三处配置，而不是认为问题已解决。

边界与注意事项

• 连通性检测有真实消耗：按请求或 token 计费的上游，不要一次性检查全部模型。
• 日志留存在当天：请求日志进入第二天后会被清理，适合当日排查，不适合作为长期归档；需要留存时自行导出。
• model not found与 401/403 的区别：如果失败伴随 401/403，那是凭据问题（Key 是否正确、是否启用、Base URL 与协议是否与供应商要求一致），而不是模型名问题，按 常见问题 中对应条目单独处理。
• 失败降级目标会切过 4xx：全局或规则级回退配置为失败降级目标时，任意4xx或5xx都会触发切换到备用模型，因此“请求看起来成功了”不代表原模型配置正确，以resolved model和x-ccr-fallback-*响应头为准。

【免费下载链接】claude-code-routerOne local control plane for every AI agent: route across models, fuse new capabilities, orchestrate tools, and stay fully in control.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-code-router