你在 Claude Code 里挂了 Router，本来只想让它按任务把请求分给不同后端，结果一跑就报错：要么启动就退出，要么切模型失败，要么某些请求通、某些请求挂。这类问题的麻烦在于报错信息经常只给一个笼统的结果，真正的原因藏在配置层级或转发环节。这篇按「先分清是哪一层出错」的思路，给一份排查顺序和修复清单。
你在 Claude Code 里挂了 Router，本来只想让它按任务把请求分给不同后端，结果一跑就报错：要么启动就退出，要么切模型失败，要么某些请求通、某些请求挂。麻烦的地方在于报错经常只给一个笼统的结果，真正的原因藏在配置层级或转发环节。这篇文章不讲概念，只讲怎么把出错的那一层揪出来。
排查思路就一句话：先分清报错发生在哪一层，再顺着日志从入口往后推。下面按「定位层级 — 对照配置 — 顺日志推 — 修完回归」四步走，每步都给判断标准和可执行动作。适合自己搭 Router 的人，也适合帮别人看这类问题的同学。
先分清报错发生在哪一层
把报错按发生位置分成四类，这比抓着错误文本搜半天有用得多。第一层是 Router 本体没起来，表现是进程或命令直接退出；第二层是路由匹配没命中，规则写错或模型名对不上；第三层是上游请求失败，鉴权、额度、限流、超时都算；第四层是下游回包解析失败，流式格式或字段不兼容。判断方法很直接：先看 Router 自己有没有打出路由日志，能打出说明第一层过了；再看请求有没有真的发到上游，发出去才轮到第三层。
| 报错位置 | 典型表现 | 先查什么 |
|---|---|---|
| Router 本体 | 启动即退出、命令报错 | 命令、依赖、配置文件是否读到 |
| 路由匹配 | 切模型失败、规则不生效 | 模型标识、匹配顺序、兜底路由 |
| 上游请求 | 全部或部分请求挂 | 鉴权头、额度、限流、超时设置 |
| 回包解析 | 只有流式请求报错 | 返回格式、字段名、结束标志 |
- 看 Router 启动日志有没有异常退出，能正常启动说明进程层没问题
- 看单次请求有没有命中规则，命中说明匹配层没问题
- 看转发出去的实际 URL 和请求头，发出去了才轮到上游排查
- 只有流式请求报错、非流式正常时，重点看回包解析而不是路由规则
配置层逐项对照清单
配置错误是这类报错里最常见也最容易反复的一类，因为报错文本往往不指向具体那一行。对照的时候重点不是「我配了没有」，而是「程序实际读到的是不是这份」。尤其是改了文件却没生效的假象，多数是文件路径和程序读取路径不一致，或者环境变量把配置文件覆盖了。
另外，切换后端的关键字段要逐条核对：base url、鉴权头、模型名。错一个字母就是整条路由失败，而且错误可能到第三层才暴露出来。路由规则里的模型标识必须和上游实际可用的名一致，默认兜底路由也要配上，否则命中不到规则的请求会直接掉出去。
- 确认 Router 的配置文件路径是否真的被读到，别改了文件程序读的是另一份
- 确认环境变量与配置文件的优先级，搞清哪个说了算
- 路由规则里的模型标识逐字对上上游可用名
- 默认兜底路由必须存在，防止未命中请求直接失败
- 各后端的 base url、鉴权头、模型名三项逐条比对
如果怀疑是上游本身慢而不是路由错，可以到 /tools/speed-test 先量出各后端的延迟基线，把「其实是上游慢」这类误判排除掉，再回头调路由。
按日志顺序定位：从入口往后推
日志是唯一能告诉你「断在哪一段」的东西，但得按顺序看。第一步看 Router 启动日志有没有异常退出，第二步看单次请求有没有命中规则，第三步看转发出去时的实际 URL 和请求头。把一次失败请求的完整链路记下来：入参、命中的规则、转发目标、上游返回的状态码与错误体。缺哪一段，就说明断在哪一段。
- 记录一次失败请求的完整链路把入参、命中的规则、转发目标、上游状态码与错误体一起记下来，形成一条可复现的记录
- 对照日志找出断点看上面四项哪个缺失：没有转发目标说明路由层没命中；有目标但上游报错说明是上游问题
- 标注关键字段请求标识、目标后端、耗时、状态码，方便和 /api-log-fields-replay 的复盘方法对齐
- 区分流式与非流式只有流式报错就重点查回包解析，两类都挂再回去查路由和上游
如果日志里只能看到一个笼统的失败结果，说明关键字段没记全，那就先补日志字段，再复现一次。没有可对比的日志，后面的修复都是靠猜。
修复后的验证动作与回归
改完别只看一次成功就算过。路由这种配置最容易「修好一条压坏另一条」，所以验证要成体系。按最小可用路径挨个后端各发一次请求，确认每条路由都通；再准备一组固定用例，覆盖不同模型标识、流式与非流式、超时边界，改配置后重跑一遍。
- 每个后端各发一次请求，逐条路由确认连通
- 固定用例覆盖模型标识、流式非流式、超时边界三类
- 给路由配降级：主后端失败切备用，但设好重试上限
- 把配置纳入版本管理，出错时直接对比上次能用的版本
想对照其他人在同类配置上的取舍，可以到 /sites 看不同中转和工具的实际配置说明，再到 /guide 里的排查类内容核对自己的步骤有没有漏项；涉及具体数字的部分，建议到 /price-watch 核对当时的记录，而不是凭印象判断。
报错先分层，日志按顺序推，配置改完必须回归——这三件事做到，大部分 Router 报错都能自己定位。下一步把你这次报错的关键字段和路由配置对照站内的排查清单过一遍，顺便看下同类的工具目录和指南，很多坑别人已经踩过，直接抄结论比重新试快得多。→
常见问题
Router 启动就报错退出，从哪查？
先确认是不是读到了你改的那份配置，路径和文件名最容易出错；再看配置语法是否合法、引用的后端字段有没有缺失。把启动日志完整看一遍，通常退出前会给一行具体原因。如果日志里只有一句笼统失败，试着用最小配置启动（只留一条路由），能起来说明是某条规则写坏了。
为什么有的模型能路由成功，有的就报错？
大概率是那条路由指向的后端本身有问题：模型标识对不上、该后端没配鉴权、或者后端限流。先单独拿这条路由对应的后端直连测一次，通就是 Router 配置问题，不通就是后端或凭证问题。别把所有失败都归到 Router 上。
流式请求报错但非流式正常，怎么处理？
先看回包解析那一层，很多 Router 在转发流式响应时对分块和结束标记的处理和后端实现有关，字段对不上就断。可以先用非流式确认路由本身没问题，再单独测流式，把两边的原始响应结构对比一遍，差异点通常就是原因。
