OmniRoute

环境要求

• Node.js 环境（npm install -g omniroute 需要 npm）
• 本地可访问 20128 端口（仪表盘 http://localhost:20128，API http://localhost:20128/v1）
• 若用 Docker：Docker 环境，支持 AMD64 / ARM64 多架构镜像
• 若跑编程智能体（Claude Code、Codex 等）：需更大内存，容器建议 ≥10g

安装与启动步骤

1. 1全局安装

   用 npm 全局安装 OmniRoute，一条命令支持任意操作系统。出现 ERESOLVE 或 peer-dep 警告属正常，可忽略。

   npm install -g omniroute

   复制

2. 2启动服务

   执行 omniroute 启动本地服务，随后仪表盘在 20128 端口、API 在 /v1 路径下可用。

   omniroute

   复制

3. 3零配置试用

   全新安装无需任何密钥，模型填 auto 即可自动路由并发起对话，验证服务已通。

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

   复制

4. 4连接免费服务商

   在仪表盘 Providers 页连接 Kiro AI（免费 Claude，每月约 50 额度）或无需授权的 OpenCode Free。

5. 5接入编程工具

   把工具的 Base URL 指向本地 /v1，API Key 从 Dashboard → Endpoints 复制，模型填 auto。

6. 6验证运行状态

   请求模型列表接口，能看到已连接模型即接入成功，之后即可交给自动路由与故障转移。

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

   复制

7. 7可选：Docker 部署

   不想装 Node 可改用 Docker，镜像自带数据卷与自动重启；跑编程智能体时需同时加大堆内存与容器内存。

   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

   复制

8. 8可选：远程模式

   服务跑在 VPS 上时，用同一 CLI 登录一次获取受限令牌，后续命令都作用于远端服务器。

   omniroute connect 192.168.0.15
   omniroute models list
   omniroute contexts use default

   复制

关键配置

如何确认成功

打开 http://localhost:20128 能看到仪表盘，或执行 curl http://localhost:20128/v1/models 带上 Bearer 密钥后返回已连接模型列表，即为启动成功。

常见问题

注意事项

• README 中的免费额度（约 1.47B tokens/月）按 16 个有公开正预算的池加五个 Groq 单模型上限计算，并做了池去重；需地区身份验证的（如 ModelScope）单独展示、不计入总数。
• Docker 部署时镜像原生缓冲在 V8 堆之外，容器内存必须给得比 OMNIROUTE_MEMORY_MB 更大。
• 远程模式下令牌分为 read / write / admin 三种作用域，会拉起进程的路由仅限本机回环访问。
• 其他安装方式：从源码 npm install && npm run dev；Termux（Android）pkg install nodejs && npx -y omniroute；macOS 菜单栏 brew install --cask zoispag/tap/