OmniRoute 跑不起来？按这个顺序查

2026-07-28

数据截至 2026-07，价格与限额以各官网为准。

OmniRoute 报的错，绝大多数不在 OmniRoute 自己身上。它是一层代理，前面接你的编程工具，后面接一堆第三方供应商，任何一头出问题，症状都表现为「网关不好使」。所以排查的关键不是猜哪里坏了，而是按从近到远的顺序，一层层确认「到这里为止是通的」，把故障范围压缩到一段链路里。

有个常见误解得先破掉：很多人一看到客户端报错，第一反应是去改配置文件、换模型、重装。这几乎是最低效的做法——因为你不知道请求到底走到了哪一步就断了。同一个「连接失败」，可能是本地进程没起来，可能是供应商那边凭证过期，也可能是模型名写错，改配置属于蒙对了算运气。下面这六层顺序，是按「离你最近的先查」排的，每查完一层，你都能确定性地排除掉一大块可能。

它是什么，先有个正确的心理模型

OmniRoute 是一个 MIT 协议的开源 AI 网关，仓库自述能用一个端点聚合大量供应商（不同来源的口径在 268+ 到 290+ 之间浮动，模型数在 500+ 量级），覆盖 Kimi、Claude、GPT、Gemini、GLM、DeepSeek、MiniMax 这些常见的名字。它由 9router fork 而来，是 Go 项目 CLIProxyAPI 的 TypeScript 移植。核心用法是：本地跑起来后，把 Claude Code、Codex、Cursor、Cline、Copilot 这类工具的接口地址统一指向 http://localhost:20128/v1。

理解这个结构，排查思路就自然出来了：请求要依次经过「你的客户端 → 本地网关进程 → 上游供应商 → 具体模型」四个环节。下面就按这条链路正向走一遍。

第一层：本地进程和 20128 端口

最先要确认的不是配置对不对，而是网关到底在不在跑。

启动方式有两条，npx omniroute@latest 直接拉起，或者用 Docker：docker run -p 20128:20128 diegosouzapw/omniroute。起来之后浏览器打开 http://localhost:20128，能看到面板，这一层就算过了。

这里最容易踩的坑有三个。第一，Docker 那条路如果漏了 -p 20128:20128 这段端口映射，容器里服务跑得好好的，宿主机就是连不上，日志还一点异常都不打。第二，20128 这个端口被别的程序占用了，网关起不来或者你打开的其实是别的服务。第三，机器上已经有一个之前留下的 OmniRoute 进程在跑旧版本，你新起的那个根本没抢到端口——遇到诡异现象时，先把残留进程杀干净再重启，比改任何配置都管用。

面板打不开就别往下查了，后面所有层都建立在这一层通的基础上。

第二层：自带的自检命令

面板能开，接着用它自己的命令做一次体检。仓库称命令有 80+ 条，排查阶段真正常用的就几条：

omniroute —— 启动网关和面板
omniroute setup —— 首次运行向导，配置乱了可以重新走一遍
omniroute doctor —— 自检，这是排查时第一个该跑的
omniroute chat —— 交互式 TUI 聊天
omniroute models --search <term> —— 查某个模型当前可不可用

doctor 的价值在于它把「环境层面的问题」一次性告诉你，省得你逐个猜。先跑它，再看下面几层。chat 这个 TUI 也有诊断价值：如果在 TUI 里对话是通的，说明网关到供应商这一整段没问题，故障就锁定在你的客户端配置那一头了——这一步能省掉大量无谓的来回。

第三层：供应商这一层，Test Connection 是分界线

网关本身没问题，接下来看上游接没接上。

加供应商的路径是：面板左侧 Providers → + Add Provider → 搜索并点选，也可以直接走 /dashboard/providers。免费供应商无需凭证，直接 Connect 即可；加完之后一定要点 Test Connection 验证一次。

这个按钮是整条链路的分界线：它通过，说明网关能正常跟上游说上话，后面再出问题就是模型或客户端的事；它不通过，你就不用再折腾客户端了，问题在凭证或上游本身。

认证类型有四种，各自的失效方式不一样，值得分开记：

OAuth：由 Omniroute 代管登录，不需要 API key。授权会过期，过期后表现为突然就不通了，重新走一遍授权即可。
web cookie：这类最脆弱，你在浏览器里退出登录、换设备、或者对方站点刷新会话，cookie 就失效了。频繁掉线优先怀疑它。
API key：付费类型，部分有免费额度。key 填错、被吊销、额度耗尽都会表现为连接失败。
Local：接本机的 Ollama、LM Studio、vLLM 之类。这类不通基本是本地那个服务自己没起来，或者端口填错，跟网关无关。

第四层：模型 ID 写错，是最高频的「看起来像挂了」

这一层的错最迷惑人：链路全通，就是一发请求就报错。

OmniRoute 的模型 ID 用的是供应商原生格式，仓库示例里能看到 claude-opus-4-8、gpt-5.5、glm-5.1、kimi-k2.5 这类写法。注意有的带点号版本号并不是笔误，而是上游 API 本来就那么要求的。你凭印象手敲、或者从几个月前的教程里抄一个旧名字，都很容易对不上。

两个务实的做法：一是拿不准就先用 omniroute models --search <term> 查一下当前可不可用，也可以直接请求 GET /api/models/catalog 看目录；二是模型填 "auto"，交给 OmniRoute 自动挑选，先把链路跑通，再回头换成指定模型。先通后调，别一上来就跟模型名死磕。

第五层：客户端那一头的地址

前面四层都验过了，TUI 里也能聊，客户端还是不行，那问题就只剩配置这一处。

要填的是 http://localhost:20128/v1，注意 /v1 这个后缀别漏；面板地址是 http://localhost:20128，两者不是一回事，漏掉后缀是很典型的错误。另外，Docker 跑的网关如果客户端也在容器里，localhost 指的是容器自己而不是宿主机，这类网络语义问题在容器场景里几乎必踩一次。

各家工具的配置位置差别不小。仓库把 33 个工具的逐一配置放在 docs/reference/CLI-TOOLS.md，除了前面提到的几个，还支持 Kiro、Command Code、Antigravity、Windsurf、AMP 以及任意 OpenAI 兼容工具；OpenCode 走的是插件 @omniroute/opencode-provider，不是改地址那种改法。与其凭经验猜某个工具的配置项叫什么，不如直接翻这份文档对着抄。

第六层：网络与准入，这一层改配置没用

到这里还不通，就该往链路的最远端看了。

OmniRoute 只是本地的一层转发，它并不改变你到各家上游服务器的网络可达性。上游是境外服务的，该连不上还是连不上。这一点必须诚实讲清楚：Anthropic 官方公布的受支持国家/地区列表不含中国大陆（anthropic.com/supported-countries）；xAI 也没有面向中国大陆的官方开放渠道。其余几家官方同样并未把中国大陆列为受支持地区，具体以各自官网的地区政策页为准。

所以如果症状是「连不上上游端点」这种网络层错误，那不是网关的 bug，也不是你配置写错了，改多少遍都不会好。本文不提供也不背书任何第三方中转渠道，相关的合规与稳定性风险由使用者自负。

有些「不通」其实是正常的

不是所有异常都算故障，下面这几种属于机制本身的表现，不必去修：

免费档随时会变。 目录里标称有相当数量的供应商带免费档、其中一部分被描述为永久免费，免费选项包括 Kiro、OpenCode Free、Pollinations，文档建议从 Kiro AI 起步——免费、无需 API key、可用 Claude 系模型。但这类信息变动极快，今天能用明天限流是常态，一切以仓库文档当前版本为准，别把「无限免费」当成承诺。你遇到的「突然不能用了」，很可能上游那边确实就是变了。

回退是设计出来的行为。 接了多个免费供应商就会启用自动回退，网关是配额感知的，某一家配额见底会自动切到下一家。所以你看到实际响应的模型跟你预期的不一样，通常是回退生效，不是路由乱了。仓库给过一个零成本组合示例：gemini-cli/gemini-3-flash-preview（每月 180K 免费）→ if/kimi-k2（无限免费）→ qw/qwen3-coder-plus（无限免费）——这几个额度口径同样以仓库当前文档为准。

token 数对不上。 它带 RTK+Caveman 压缩，仓库称能省 15-95% token。开着压缩时，你按原始输入估算的 token 数跟实际统计对不上很正常，不是记账出了问题。

诚实说局限

有几件事得说在前面。一是这是第三方聚合网关，各家凭证要交给本地代理托管，OAuth 和 web cookie 这两类尤其要想清楚——你把会话凭证交出去了，是否符合上游服务条款、出问题谁负责，都得自己判断，本文不做背书。二是免费额度类信息变动极快，本文写到的任何数量、额度、模型名，都可能在你读到时已经变了，务必以仓库文档当前版本为准。三是它多了一层转发，链路变长意味着排查也变长，出问题时你要多分辨一层「是网关的问题还是上游的问题」，这个成本在生产环境里不是零。

排查顺序速查

面板 http://localhost:20128 能不能打开——不能就先解决端口和进程。
跑 omniroute doctor；再用 omniroute chat 判断故障在网关侧还是客户端侧。
供应商 Test Connection 过不过——不过就查凭证类型对应的失效方式。
模型 ID 是不是原生格式；拿不准先用 "auto" 或查一次模型目录。
客户端地址是不是 http://localhost:20128/v1，/v1 有没有漏；容器场景注意 localhost 指向谁。
以上都过还不通，考虑网络与准入，这一层不是改配置能解决的。

小结

OmniRoute 的排查难点不在于错误信息有多晦涩，而在于它同时连着两头，症状容易误导人。按「进程端口 → 自检命令 → 供应商连接 → 模型 ID → 客户端地址 → 网络准入」这个顺序往下走，每一步都有明确的验证动作，不用靠猜。其中 omniroute chat 和供应商的 Test Connection 是两个最有价值的分界点，通过它们能一次性把范围切成两半。免费档相关的「不通」大多不是故障，而是上游变了或回退生效，判断清楚再动手。最后记住那条最费时间的教训：如果卡在网络准入这一层，改配置是没有用的。