Vuncloud 博客
← 返回机房手记专栏

OmniRoute 保姆级教程：从 0 到 1 搭建免费 AI Gateway，统一接入 Claude、GPT、Gemini、DeepSeek 等大模型

发布于

一个 /v1 · 自带账号 · 只听 127.0.0.1约 12 分钟阅读

双显示器上的代码编辑器与前景键盘，对应在本机搭建 OmniRoute AI Gateway

Cursor、Claude Code、Codex、Gemini CLI 各认各的地址和密钥。供应商一多，限额、账单和「这家今天 429」就散落在每套配置里。OmniRoute 把这件事收成你自己机器上的一个 OpenAI 兼容入口：客户端只记 http://127.0.0.1:20128/v1，Claude、GPT、Gemini、DeepSeek 以及目录里的其他模型从仪表盘接进去。软件是 MIT，仓库目前在 release/v3.8.53 这条发布线上；下面的端口、命令和路由规则以该版 README 为准，供应商数量会随版本变。

「免费」指的是网关本身不收费。额度在你接上的供应商账上。官方把第三方免费档做成仪表盘上的 /dashboard/free-tiers 估算，并写明那是汇总，不是 OmniRoute 发给你的 token。已经在付费的订阅，也可以走你自己的账号流程，让编程工具共用这一条地址。若你更关心各家 API 标价，可以对照 编程工具月账单 和 OpenRouter 计价：那是托管路由，OmniRoute 是你本机上的网关。

20128
仪表盘与 /v1 同一端口，默认在本机
MIT
软件免费；模型额度记在供应商账上
auto
只在已接入且合格的连接之间路由

网关放在哪一层

把它想成一台只跑在你机器上的翻译插座。上游仍是 OpenAI、Anthropic、Google、DeepSeek 或目录里的其他供应商；下游是任何认 OpenAI Chat Completions 或 Responses 的客户端。v3.8.53 文档口径是约 375 家供应商、约 1475 个原始模型 ID，其中一部分带免费档发现标记。这些数字两周会重审，以仪表盘目录为准，不要抄旧截图。

  • 你保管两把钥匙。供应商 API key（或 OAuth）只放进 OmniRoute。给 Cursor / 脚本用的是 Dashboard → Endpoints 里的网关密钥。
  • 模型名在连上之后才有意义。先调 /v1/models，再用返回的 ID。README 里的示例写成 openai/gpt-5.4、glm/glm-5.2 这种「供应商/型号」，以你列表里实际出现的为准。
  • 兼容面很宽。官方点名 Claude Code、Codex、Cursor、Cline、Continue、OpenCode、Copilot、OpenClaw 等。认自定义 Base URL 的，填地址即可；官方还提供 omniroute run 拉起其中 7 个 CLI。
额度在供应商，不在这个仓库

README 写的是 Bring your own provider accounts。免费档可能要注册、审核或绑定支付方式，也可能随时关闭。标记 tos: avoid 的供应商默认不进 auto，连上账号也不会自动改掉这条策略。

从 0 安装：npm 与 Docker

需要本机有 Node.js。最快的一条路：

npm install -g omniroute
omniroute

看到 npm warn ERESOLVE 或 peer 依赖警告，按官方说明可以先忽略。启动后浏览器打开 http://127.0.0.1:20128，API 在 http://127.0.0.1:20128/v1。无头、只要代理时用 omniroute serve --headless（或环境变量 OMNIROUTE_HEADLESS=1），仪表盘和只给面板用的子系统会关掉。

npm 11 要放行安装脚本

npm 11 可能拦住包的生命周期脚本。OmniRoute 的 postinstall 要跑，才会准备好原生运行时文件。3.8.53 文档给出的允许列表是：

npm install -g --allow-scripts=omniroute,keytar,onnxruntime-node,@parcel/watcher,@swc/core,protobufjs,esbuild omniroute

若 npm 提示的包名和上面不一致，以那次警告里的名字为准。允许脚本意味着这些包的安装脚本会执行，只在你确认来源后再做。CI 或慢机器可以设 OMNIROUTE_SKIP_POSTINSTALL=1，那只跳过原生 SQLite 预热，二进制复制那一步仍会跑。

Docker 要按编程负载加内存

镜像名仍是文档里的 diegosouzapw/omniroute。:latest 跟踪已发布的最高稳定 SemVer，不跟踪 git main。生产请钉具体版本。官方示例把端口绑在回环上：

docker run -d --name omniroute --restart unless-stopped --stop-timeout 40 \
  -e OMNIROUTE_MEMORY_MB=8192 --memory=10g \
  -p 127.0.0.1:20128:20128 -v omniroute-data:/app/data diegosouzapw/omniroute:latest

镜像默认堆只有 1024MB，够面板和短对话。Claude Code、Codex 走 POST /v1/responses 时，官方写明需要更大的 V8 堆，否则长上下文会把进程打到内存致命错误。一个编程代理的示例是堆 8192、容器至少 10g。两路重叠的长请求要到 10240–12288 的堆，容器 12–16g。Apple Silicon 走镜像的 arm64 构建即可。卷 omniroute-data 里有密钥，备份和删除都按机密处理。

双手在笔记本上操作，对应把 Claude、GPT、Gemini、DeepSeek 接到同一个 OmniRoute 接口
客户端只保留一个 Base URL。供应商密钥留在网关里。

接入 Claude、GPT、Gemini、DeepSeek

打开仪表盘的 Providers，选一家你现在有资格用的，贴 API key 或走它的账号流程。四家实验室的钥匙分别在各自控制台申请，OmniRoute 不代你开通：

供应商你准备什么接到哪里
OpenAI（GPT）platform.openai.com 的 API keyProviders → OpenAI
Anthropic（Claude）console.anthropic.com 的 key，或你已经在付的 Claude 订阅账号流程Providers → Anthropic / 对应 OAuth
GeminiGoogle AI Studio 的 key，或 Gemini CLI 的 OAuthProviders → Gemini
DeepSeekplatform.deepseek.com 的 API keyProviders → DeepSeek

免费档是另一张清单，不是这四把钥匙的同义词。仪表盘第一次向导里可以出现「设置免费供应商」，它按当前免认证目录列出，让你逐个勾选后才创建连接，不会在你点完成时偷偷加一家。目录里出现过 Pollinations、Cloudflare AI、SiliconFlow 的 DeepSeek 免费档等，条款、地区和是否还在都由对方决定。旧文里的「免密钥 Claude」若标了 tos: avoid，默认进不了 auto。用之前打开 Free Tiers 页看当天的资格说明。

网页 Cookie 类供应商（例如 Gemini Web）还要额外的浏览器运行时。npm 包带了 Playwright，不带 Chromium 二进制；第一次调用前按仓库里的 Playwright Chromium 说明准备，否则请求会在浏览器层失败。

让 IDE 和 CLI 共用一个地址

在 Endpoints 复制网关密钥。然后：

Base URL: http://127.0.0.1:20128/v1
API Key:  （Dashboard → Endpoints）
Model:    auto

先确认模型列表，再让 IDE 说话：

curl http://127.0.0.1:20128/v1/models \
  -H "Authorization: Bearer YOUR_KEY"

curl http://127.0.0.1:20128/v1/chat/completions \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"auto","messages":[{"role":"user","content":"Hello"}]}'

Cursor、Cline、Continue 以及任何能改 OpenAI Base URL 的插件，填上面三行即可。发不出自定义请求头的客户端，可以用文档里的令牌化兼容地址，例如 http://127.0.0.1:20128/vscode/YOUR_KEY/chat/completions。能带头的，仍优先 Authorization: Bearer。

命令行不必手改每个工具的配置文件。官方的一键启动会按进程注入凭据，Qwen / Gemini 还会用一次性的隔离 home：

omniroute run claude --model auto
omniroute run codex  --model auto
omniroute run gemini --model auto
omniroute configure codex

omniroute run 覆盖 Claude Code、Codex、Aider、Goose、OpenCode、Qwen Code、Gemini CLI。configure 会把供应商和模型写进该工具自己的配置，文档列出的目标包括 codex、claude、opencode、qwen、aider、goose、gemini、cline、continue、kilo。--dry-run 只打印将要使用的环境变量和参数。--api-key-env NAME 让密钥留在环境变量名里，不进 shell 历史。

auto、回退，以及谁不会进自动路由

auto 在已经接入且合格的连接之间选。刚装完、一家都没接时，它可以没有任何合格目标，这是预期行为。选中的策略、供应商和延迟会回到响应头 X-OmniRoute-Decision，排错时先看这一头，再看客户端日志。

  • 额度感知的回退。某条连接打满限额后，调度可以改走仍有余量的连接。v3.8.53 还加了按剩余额度加权的策略，并尽量把同一段对话钉在原连接上。
  • 订阅路线可以失败关闭。文档里的 subscription 组合只用你已经在付的订阅额度，失败就停，不会悄悄落到另一把会计费的钥匙上。付费钥匙和订阅钥匙不要放进同一个「随便 fallback」的组合里。
  • tos: avoid 默认排除。连上不等于进入 auto。要固定某把网关密钥只用一个模型，用该密钥的 forcedModel，而不是在客户端写死一个上游地址。

压缩是可选流水线，对客户端透明。文档把它做成可组合引擎，实际用了哪一套会写在 X-OmniRoute-Compression 响应头里。省多少取决于模型和请求，不要把 README 上的区间当成每条请求的承诺。记忆功能默认关闭。凭证脱敏也是选开的。

放在 Cloud Mac 上：回环加 SSH

网关适合挂在一台一直开着的 Mac 上：本机回环听 20128，你的笔记本用 SSH 把端口转回来。Cloud Mac 的区域固定、可以 SSH，Apple Silicon 也能跑官方 arm64 镜像。管理界面不要绑 0.0.0.0。

ssh -N -L 20128:127.0.0.1:20128 user@your-cloud-mac

隧道起来之后，笔记本上的 Cursor 或 omniroute run 仍填 http://127.0.0.1:20128/v1。看起来是本机，流量走到云端那台 Mac 的回环。供应商密钥留在云端数据卷或本机用户目录，不进 Git。若你已经在同一台机器上跑 OpenClaw，把它的模型地址指到这同一个 /v1，密钥仍只留一份在网关里。

需要面板登录时，文档提供可选的 OIDC；密码登录仍然保留。远程驱动另有带范围的 token（connect / contexts / tokens），按官方 Remote Mode 使用，不要为了省事把仪表盘挂到公网 IP。

卡住时先查这几处

  1. /v1/models 是空的。Providers 里还没有成功的连接，或客户端用错了钥匙（把供应商 key 当成了网关 key）。
  2. auto 说没有路线。只接了被排除的供应商，或免费档当天没有资格。换一个你确认可用的付费 key，或在模型栏填 /v1/models 里的具体 ID。
  3. npm 全局安装后命令找不到原生模块。回到 npm 11 的 --allow-scripts，用警告里的包名重装。
  4. Docker 里编程代理中途退出。把 OMNIROUTE_MEMORY_MB 和 --memory 提到编程负载那一档，而不是维持 1024MB。
  5. 网页供应商第一次请求失败。补 Playwright 的 Chromium，再重试，不要先改路由策略。
  6. 版本对不上。375 家、1475 个模型 ID 是 v3.8.53 文档当时的口径。升级后以仪表盘和 仓库 README 为准。

FAQ

短答：软件免费，额度在供应商；地址是本机 20128 的 /v1；auto 只走合格连接；编程代理在 Docker 里要加大内存；端口留在回环，远程用 SSH 转发。完整问答在页头的 FAQ 结构化数据里。

机房手记 · 网关

网关常驻回环，SSH 转到你的笔记本

OmniRoute · 20128 · Cloud Mac

查看 Cloud Mac 套餐
限时优惠 点击查看套餐