OmniRoute 中文教程：npm / Docker 安装、端口配置与 Coding Agent 接入
OmniRoute 把多个模型 provider 放到一个 OpenAI 兼容地址后面，适合需要切换 provider、失败重试或统一配置多个 Coding Agent 的人。本文把安装、首次启动、连接和边界写清楚，不把 provider 的免费额度当成产品承诺。
1. 安装
npm
npm install -g omniroute omniroute --version
Docker
docker run -d --name omniroute --restart unless-stopped \ --stop-timeout 40 -p 20128:20128 \ -v omniroute-data:/app/data \ diegosouzapw/omniroute:latest
如果使用源码，官方文档的入口是 .env.example、npm install 和 PORT=20128 npm run dev。生产环境不要直接把 dashboard 暴露到公网。
2. 首次启动
omniroute setup omniroute
默认 dashboard 是 http://localhost:20128，OpenAI 兼容接口是 http://localhost:20128/v1。数据目录由 DATA_DIR 控制，默认是 ~/.omniroute；官方 README 说明凭据在本地以 AES-256-GCM 加密保存。
3. 连接 Claude Code、Codex 或 Cursor
在客户端填写：
| 字段 | 值 |
|---|---|
| Base URL | http://localhost:20128/v1 |
| API Key | 从 Dashboard → Endpoints 复制 |
| Model | auto，或明确的 provider/model |
OmniRoute 使用 OpenAI 兼容接口，所以还可以接入 Cline、Copilot、Continue 等支持自定义 base URL 的客户端。若客户端有自己的 Anthropic 原生协议配置，不要假设改 Base URL 后所有高级功能都保留，先用最小请求验证。
4. 验证
omniroute doctor omniroute chat
doctor 用来检查 provider、端口和原生依赖；chat 可以在终端直接发起交互请求。验证时至少确认三件事：dashboard 能打开、/v1 能返回模型列表或错误信息、请求确实到达你选择的 upstream。
5. 和直接调用 provider 的区别
只用一个 provider 时，直接使用官方 SDK 更简单。OmniRoute 的价值在于把多个客户端统一到一个 base URL，集中处理 provider 切换、回退、配额和模型别名；代价是多维护一个本地 gateway，还要单独保护 dashboard、日志和凭据。
验证边界
验证状态：official_docs_checked_not_locally_installed；核对日期 2026-09-22。核对官方 README 与 v3.8.50 release；未在当前工作区启动 gateway 或连接真实 provider。
观察结果：官方命令包含 npm install -g omniroute、omniroute setup、默认端口 20128 和 omniroute doctor；
限制：未验证每个 provider 的实时额度、OAuth 流程或客户端高级协议兼容性。 依据：官方仓库 README / release 页面，核对日期 2026-09-22。
这里仅补原教程没有展开的事实和边界。安装命令与操作步骤仍以前文为准。
先判断这个项目是否适合你
采用建议
同时使用多个模型 provider 或多个 Coding Agent，需要统一 base URL、回退和模型别名的人。采用前需要核对：本地 gateway 不代表请求留在本机。
原教程未展开的系统信息
核心功能
npm/Docker 启动
官方 README 同时给出 npm 全局安装和 Docker 镜像路径，默认服务端口为 20128。
setup/doctor 与 provider routing
setup 负责首次配置，doctor 检查 provider/端口/原生依赖，路由层负责切换 provider 和模型。
架构与数据流
客户端请求先到本地 OmniRoute gateway，再由 gateway 按配置转发到上游 provider；dashboard、凭据存储和路由策略属于本地 gateway 的运维边界。
常见问题
OmniRoute 用什么端口？
默认使用 20128；dashboard 是 http://localhost:20128，API 是 http://localhost:20128/v1。可用 PORT 修改。
Docker 数据放在哪里？
命名卷 omniroute-data 挂载到 /app/data；如果使用源码或 npm，可通过 DATA_DIR 指定目录。
Model 应该填 auto 还是具体模型？
先用 auto 验证路由能工作；需要稳定复现时再填写明确的 provider/model，并记录版本和配置。
OmniRoute 会不会把数据传到外部？
gateway 自己在本机运行，但它会把请求转发给你配置的上游 provider。
如何确认教程对应的版本？
运行 omniroute --version，并对照官方 v3.8.50 release；若版本不同，应优先看对应 release notes。