你需要准备什么
开始之前，确认机器上已经装好 Node.js 18+ 版本，这是跑 OmniRoute 的硬性基座。如果你习惯用容器，也得提前拉好 diegosouzapw/omniroute 镜像。手头最好留几个主流大模型厂商的 API Key —— 虽然网关自带 OpenCode Free 等开箱即用的免费通道，但自带 Key 能解锁更高配额、更稳定的并发。终端得能联网，毕竟首次启动要从注册表拉取约 358 家提供商的元数据（官方文档站当前口径，随版本变动），离线环境得靠预置配置绕过。
动手安装
打开终端，直接扔进去：
npm install -g omniroute
等个几十秒，全局二进制 omniroute 就落地了。不想污染全局？改用 npx omniroute 临时跑也行。Docker 派直接：
docker run -d -p 20128:20128 diegosouzapw/omniroute
跑起来后，浏览器打开 http://localhost:20128/v1 能看到标准 OpenAI 兼容的 /models 列表，说明网关已就绪。顺手访问 /dashboard/free-tiers，仪表盘会实时展示各家免费层的剩余额度、限速阈值、区域鉴权限制 —— 这些数据直接决定了后续 fallback 的优先级。
配置接入
以 Cursor 为例，进 Settings → Models → Add Model，Base URL 填 http://localhost:20128/v1，API Key 随便填个 sk-local 占位（网关不校验这层），Model 下拉会自动刷出 auto 这个零配置魔法模型。auto 背后对接的是预置的 OpenCode Free 通道，开箱即用、零 Key 启动。同理，Claude Code、Codex、OpenCode、Cline、Copilot 只要支持自定义 OpenAI 兼容端点，全能按这套口径接入。想指定模型？把 Model 换成 anthropic/claude-3.5-sonnet 这种 provider/model 格式，网关会按 19 种路由策略里的 cheapest 或 fastest 自动挑最优通道。
怎么帮你省钱的
OmniRoute 不只是个转发层，它在请求入站后做了三件事：
第一，四层自动 fallback：Subscription（订阅制额度）→ API Key（自带 Key）→ Cheap（最低单价）→ Free（免费层）。免费额度耗尽、触发限速、区域鉴权失败、返回 429/403，统统自动降级下一层，用户层零感知。注意：各家免费额度绝非无限量，有的日限 50 万 Token，有的强制美区 IP，有的并发仅 1 路 —— 这些限制全在仪表盘里如实暴露，网关不造假、不兜底。
第二，RTK + Caveman 双引擎压缩：把上下文里的重复模板、冗长系统提示词、历史对话摘要化，实测能在不损任务质量前提下压缩 15%-95% Token。长上下文任务（如整仓库重构、长文档问答）收益最大，短对话收益边际递减。
第三，19 种路由策略组合拳：round-robin 负载均衡、priority 按优先级、latency 选最快、cheapest 选最便宜、fallback-only 纯兜底……配合提供商约 358 家的实时价格表（从官方定价页同步，延迟分钟级），网关能在毫秒级完成「选模型→选通道→压Prompt→发请求→解流式响应」全链路。网关本身 MIT 开源、0 元起步、不收任何中介费，钱全付给上游厂商，GitHub 仓库 随时可审计。
别在这几个地方翻车
免费层≠无限量：仪表盘里标着「Free」的通道，大多有日配额、并发限制、区域锁。别指望白嫖跑生产级高并发，自备 Key 才是正道。
压缩有副作用：RTK/Caveman 对代码生成、结构化输出类任务偶尔会丢关键注释或破坏 JSON 格式。关键任务建议在请求头加
x-omniroute-compress: false关掉压缩，或改用provider/model显式指定不走压缩通道。流式响应偶发截断：部分上游厂商的 SSE 分块边界与网关解析器对不齐，表现为最后一段内容丢失。临时绕法：在客户端把
stream: false强制走非流式，或者换家稳定的上游。Docker 端口映射别写反：宿主机
-p 20128:20128左边是宿主端口，右边是容器内固定 20128。改宿主端口随意，容器内端口动不得，不然健康检查挂了、仪表盘进不去。约 358 家提供商是动态口径：官方文档站写「约 358 家」，旧帖常挂「375 家」 —— 别信旧数字。注册表随版本增减，新增厂商得等网关自动拉取或重启刷新。
