OmniRoute 安装与配置完全指南：从 npm 一键安装到 MCP/A2A 协议与超时调优

OmniRoute 安装与配置完全指南从 npm 一键安装到 MCP/A2A 协议与超时调优【免费下载链接】OmniRouteNever stop coding. Free MIT AI gateway: one endpoint, 352 providers (150 free), 1200 models Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax. Works with Claude Code, Codex, Cursor, OpenCode, Cline Copilot. Quota-aware auto-fallback, RTKCaveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 550 contributors项目地址: https://gitcode.com/GitHub_Trending/om/OmniRoute本文是 OmniRoute统一 AI 网关的完整安装与配置参考。OmniRoute 通过单一 OpenAI 兼容端点聚合数百家 Provider 与上千个模型支持自动故障转移、RTKCaveman 压缩、MCP/A2A 协议与桌面/PWA 客户端。读完本文你将掌握从 npm、pnpm、AUR、源码、Docker 到 Electron 的全部安装路径能够把 Claude Code、Codex CLI、Cursor、Cline、OpenCode 等编码工具接入 OmniRoute配置 MCP/A2A 协议并针对流式请求精细调优超时参数。快速上手版可先看 README 的 Quick Start。安装方法OmniRoute 提供六种官方安装路径npm推荐、pnpm、Arch Linux AUR、从源码、Docker 与 Electron 桌面应用。全部方式最终都在本地启动同一个网关进程默认监听http://localhost:20128。npm推荐npm install -g omniroute omniroute安装后直接运行omniroute即可启动。Dashboard 打开在http://localhost:20128API 基础 URL 为http://localhost:20128/v1。需要说明的是package.json 的engines字段要求 Node.js22.22.2 23 || 24.0.0 27请在符合要求的运行时版本下安装。pnpmpnpm add -g omniroutelatest --allow-buildbetter-sqlite3 --allow-buildswc/core omniroutepnpm 用户注意--allow-build标志是必需的它用于启用better-sqlite3与swc/core两个原生模块的构建脚本。pnpm approve-builds -g命令在 pnpm v11 的全局安装场景下不受支持。这一点与仓库中 package.json 的pnpm.onlyBuiltDependencies声明包含better-sqlite3、swc/core、esbuild、sharp等相互印证——这些依赖都携带原生编译脚本需要显式放行。Arch LinuxAURyay -S omniroute-bin systemctl --user enable --now omniroute.serviceAUR 包omniroute-bin安装 OmniRoute 并提供一个 systemd 用户服务单元适合在 Arch 系发行版上以服务方式常驻运行。从源码构建npm install PORT20128 DASHBOARD_PORT20129 NEXT_PUBLIC_BASE_URLhttp://localhost:20129 npm run devWindows 提示默认情况下当旧的%USERPROFILE%\.omniroute目录不存在时OmniRoute 使用%APPDATA%\omniroute作为数据目录。可通过设置DATA_DIR选择其他数据目录位置。注意事项npm install首次运行时会自动从.env.example生成.env。后续安装不会覆盖已存在的.env因此你的自定义配置会被保留。如需重新初始化请先删除.env再重新运行。.env.example 是运行时读取的全部环境变量的权威契约文件从必填密钥JWT_SECRET、API_KEY_SECRET、INITIAL_PASSWORD到存储、端口、安全、代理等 3000 行配置均有逐项注释。Docker完整的 Docker 部署Compose 配置档、Caddy HTTPS请参考 Docker 指南。仓库同时提供了 docker-compose.yml、docker-compose.prod.yml 以及 contrib/podman 的 Podman 部署素材。桌面应用ElectronOmniRoute 提供基于Electron 41 electron-builder 26.10构建的桌面封装。可用脚本workspace 根目录执行npm run electron:dev # 以热重载方式运行桌面版 npm run electron:build # 为当前系统构建自动检测 npm run electron:build:win # Windows 安装包NSIS portable npm run electron:build:mac # macOSdmg ziparm64x64 npm run electron:build:linux # LinuxAppImage deb rpm npm run electron:smoke:packaged # 对打包产物做冒烟测试桌面安装包随 GitHub Releases 发布。关于 Electron 的深度说明代码签名、IPC 桥、发行渠道参见 ELECTRON_GUIDE.md。Headless 服务器CI / 自动化面向无人值守安装Docker、Kubernetes、CI使用omniroute setup --non-interactive omniroute providers test-batch配合环境变量INITIAL_PASSWORD、OMNIROUTE_WS_BRIDGE_SECRET等可完全脚本化地拉起一个 OmniRoute 实例。其中INITIAL_PASSWORD是首次启动时设置 Dashboard 初始密码的引导变量OMNIROUTE_WS_BRIDGE_SECRET用于认证内部 Codex Responses WebSocket 桥接生产环境必填未设置时所有 WS 桥接请求会被拒绝见 .env.example。CLI 选项一览命令说明omniroute启动服务器PORT20128API 与 Dashboard 同端口omniroute setup引导式 CLI 入门设置密码与首个 Provideromniroute doctor不启动服务器运行本地健康检查omniroute providers从 CLI 发现、列出、校验与测试 Provideromniroute configCLI 工具配置——list、get、set、validateomniroute status离线状态面板——版本、DB、工具、配置omniroute logs从 API 流式读取用量日志支持--followomniroute update检查或应用 OmniRoute 更新omniroute provider管理 Provider 连接——add、list、remove、test、defaultomniroute --port 3000将规范/API 端口设为 3000omniroute --mcp启动 MCP 服务器stdio 传输omniroute --no-open不自动打开浏览器omniroute --help显示帮助无头配置可用标志或环境变量脚本化omniroute setup --non-interactive --password $OMNIROUTE_PASSWORD omniroute setup --non-interactive --add-provider --provider openai --api-key $OPENAI_API_KEY omniroute setup --non-interactive --add-provider --provider openai --api-key $OPENAI_API_KEY --test-provider不打开 Dashboard 也能运行本地诊断omniroute doctor omniroute doctor --json omniroute doctor --no-liveness通过 SSH 或脚本管理 Provider无需打开 Dashboardomniroute providers available omniroute providers available --search openai omniroute providers available --category api-key omniroute providers list omniroute providers test id-or-name omniroute providers test-all omniroute providers validateCLI 工具配置1) 连接 Provider 并创建 API Key打开 Dashboard →Providers连接至少一个 ProviderOAuth 或 API Key。打开 Dashboard →Endpoints创建一个 API Key。可选打开 Dashboard →Combos设置故障转移链。2) 指向你的编码工具把任意 OpenAI 兼容编码工具指向 OmniRouteBase URL: http://localhost:20128/v1 API Key: [从 Endpoint 页面复制] Model: if/qwen3.8-max-preview或任意 provider/model 前缀如果编辑器无法发送Authorization: Bearer ...头改用基于 token 的兼容 baseBase URL: http://localhost:20128/api/v1/vscode/YOUR_KEY/ Models URL: http://localhost:20128/api/v1/vscode/YOUR_KEY/models Chat URL: http://localhost:20128/api/v1/vscode/YOUR_KEY/chat/completions Ollama Tags URL: http://localhost:20128/api/v1/vscode/YOUR_KEY/api/tags这套接入方式适用于 Claude Code、Codex CLI、Cursor、Cline、OpenClaw、OpenCode 以及所有 OpenAI 兼容 SDK。值得注意的是.env.example 显示这条 token 化路由还内置了上下文净化器OMNIROUTE_VSCODE_SANITIZE_CONTEXT默认开启请求中的隐式活动编辑器上下文editorContext、activeEditor、currentFile等会在转发上游前被剥离显式附加的敏感文件.env、私钥、kubeconfig、凭据内容会被打码从安全角度建议保持默认。用setup-*自动配置与其手动粘贴 base URL 和密钥不如让 OmniRoute 依据实时模型目录为每个工具写入它自己的配置文件。每个工具一条命令omniroute setup-codex # ~/.codex/name.config.toml profiles omniroute setup-claude # ~/.claude/profiles/name/settings.json omniroute setup-opencode # ~/.config/opencode/opencode.json (openai-compatible) omniroute setup-cline # Cline CLI VS Code 扩展设置 omniroute setup-kilo # Kilo Code omniroute setup-continue # ~/.continue/config.yaml (Continue / cn) omniroute setup-cursor # 打印 Cursor 应用内步骤 omniroute setup-roo # Roo Code import autoImport 指针 omniroute setup-crush # ~/.config/crush/crush.json omniroute setup-goose # ~/.config/goose/config.yaml omniroute setup-aider # ~/.aider.conf.yml omniroute setup-qwen # ~/.qwen/settings.json ~/.qwen/.env每个命令都接受--remote url --api-key key用于让本地工具指向远端OmniRoute以及--dry-run预览将要写入的内容。每条命令读取的是运行中 OmniRoute本地或远端的实时模型目录并在你机器上写入工具自己的配置文件凡是工具支持用环境变量引用 API Key 的地方都会这样做。关于每个命令具体写入什么、全部标志、本地 vs 远端语义、base-URL/v1约定完整对照表见 CLI Integrations。其中还确认setup-cursor不写任何文件Cursor 配置是封闭的 SQLite仅打印应用内步骤--only patterns可按子串过滤模型如--only glm,kimi。各工具的深度配置Claude Code、Codex CLI、Cursor、Cline、OpenClaw、Kilo Code、Copilot 等见专门的 CLI 工具指南。通用启动器omniroute run除了写入配置的setup-*命令主文档还提供了通用启动器omniroute run target它不写任何配置文件直接把正确的环境变量注入后启动claude、codex、aider、goose、opencode、qwen、gemini。旧的按工具拆分启动器omniroute launchClaude Code与omniroute launch-codexCodex仍然可用。目标及其别名来自 bin/cli/cli-manifest.mjs如claude-code|cc|anthropic、codex-cli|openai-codex|openaiomniroute completion也会补全相同的目标词。协议配置MCP A2AMCP 配置Model Context Protocol以 stdio 模式启动 MCP 传输omniroute --mcp推荐的验证流程# 1. 启动 MCP 服务器 omniroute --mcp # 2. 从你的 MCP 客户端调用 omniroute_get_health # 应返回系统健康状态 omniroute_list_combos # 应返回活动中的 combos # 3. 或运行完整 E2E 套件 npm run test:protocols:e2eMCP 客户端配置Claude Codeclaude mcp add-server omniroute --type http --url http://localhost:20128/api/mcp/streamCursor / Cline在 MCP 设置中添加{ mcpServers: { omniroute: { command: omniroute, args: [--mcp], env: {} } } }完整 MCP 文档工具目录、IDE 配置、Python/TS/Go 客户端见 MCP Server README。从源码层面看open-sse/mcp-server 目录下包含 62 个 TypeScript 文件涵盖服务器主体、审计、描述压缩等模块.env.example 还披露了 MCP 相关的可调项OMNIROUTE_MCP_ENFORCE_SCOPES强制 scope 访问控制、OMNIROUTE_MCP_SCOPESadmin、combos、health、models、routing、budget、metrics、pricing、memory、skills、OMNIROUTE_MCP_COMPRESS_DESCRIPTIONS压缩工具描述以节省 token默认 rtk 算法等供高级部署按需调整。A2A 配置Agent-to-Agent Protocol验证 Agent Cardcurl http://localhost:20128/.well-known/agent.json发送任务curl -X POST http://localhost:20128/a2a \ -H content-type: application/json \ -d {jsonrpc:2.0,id:quickstart,method:message/send,params:{skill:quota-management,messages:[{role:user,content:Give me a short quota summary.}]}}完整 A2A 文档JSON-RPC 2.0、skills、流式传输、任务生命周期见 A2A Server README。超时配置基础超时大多数部署只需要这两个变量变量默认值用途REQUEST_TIMEOUT_MS600000共享基线上游响应启动超时、隐藏的 Undici 超时、TLS 指纹请求、API 桥接 request/proxy 超时STREAM_IDLE_TIMEOUT_MS继承REQUEST_TIMEOUT_MS流式 chunk 之间的最大间隔超过后 OmniRoute 中止 SSE 流保持向后兼容现有的FETCH_TIMEOUT_MS、API_BRIDGE_PROXY_TIMEOUT_MS及其他分层超时变量仍然生效并会覆盖共享基线。从源码看open-sse/config/constants.ts 中定义了STREAM_IDLE_TIMEOUT_MS upstreamTimeouts.streamIdleTimeoutMs并注明可用STREAM_IDLE_TIMEOUT_MS环境变量覆盖这与文档表格完全对应。Provider 特定注意事项对于 Claude Code 兼容上游anthropic-compatible-cc-*OmniRoute 会从解析后的 fetch 超时推导出出站X-Stainless-Timeout头使 Provider 侧的读超时与你的环境变量配置保持对齐。对于第三方 Claude Code 兼容反向代理OmniRoute 保持默认anthropic-beta头集合为保守状态当Client Cache Control处于Auto时只转发客户端提供的cache_control标记。仅当上游明确要求重定向后的 Claude 思考流时才启用按连接切换的 Enable redact-thinking beta 开关。高级超时覆盖变量默认值用途FETCH_TIMEOUT_MS继承REQUEST_TIMEOUT_MS上游响应启动超时用于等待响应头到达之前FETCH_HEADERS_TIMEOUT_MS继承FETCH_TIMEOUT_MSUndici 接收上游响应头的时限FETCH_BODY_TIMEOUT_MS继承FETCH_TIMEOUT_MSUndici 上游 body chunk 之间的时限0表示禁用FETCH_CONNECT_TIMEOUT_MS30000Undici TCP 连接超时FETCH_KEEPALIVE_TIMEOUT_MS4000Undici 空闲 keep-alive 套接字超时TLS_CLIENT_TIMEOUT_MS继承FETCH_TIMEOUT_MS通过wreq-js发起的 TLS 指纹请求超时API_BRIDGE_PROXY_TIMEOUT_MS继承REQUEST_TIMEOUT_MS或600000/v1代理从 API 端口转发到 Dashboard 端口的超时API_BRIDGE_SERVER_REQUEST_TIMEOUT_MSmax(API_BRIDGE_PROXY_TIMEOUT_MS, 300000)API 桥接服务器上的入站请求超时API_BRIDGE_SERVER_HEADERS_TIMEOUT_MS60000API 桥接服务器上的入站头超时API_BRIDGE_SERVER_KEEPALIVE_TIMEOUT_MS5000API 桥接服务器上的 keep-alive 超时API_BRIDGE_SERVER_SOCKET_TIMEOUT_MS0API 桥接服务器上的套接字空闲超时0禁用注意对流式请求FETCH_TIMEOUT_MS只覆盖连接建立 / 等待上游首个响应的阶段。流一旦活跃OmniRoute 只会在真正停顿STREAM_IDLE_TIMEOUT_MS或 Undici body 空闲FETCH_BODY_TIMEOUT_MS时中止因此长时 SSE 流不会因为一次正常的长时间无输出而被误杀。反向代理兼容如果你在 Nginx、Caddy、Cloudflare 或其他反向代理之后运行 OmniRoute请确保代理的超时也高于OmniRoute 的 stream/fetch 超时否则代理可能比网关更早断开长连接造成客户端侧间歇性截断。分离端口模式在高级场景反向代理、容器网络下可让 API 与 Dashboard 分别监听不同端口PORT20128 DASHBOARD_PORT20129 omniroute # API: http://localhost:20128/v1 # Dashboard: http://localhost:20129对应地.env.example 中的端口契约还提供了API_PORT、API_HOST、DASHBOARD_PORT等独立变量端口解析逻辑集中在 src/lib/runtime/ports.ts。另有LIVE_WS_PORT默认20132用于实时监控 WebSocket。Void Linuxxbps-src模板Void Linux 用户可以通过xbps-src构建原生包。将下面这个块保存为srcpkgs/omniroute/template# Template file for omniroute pkgnameomniroute version3.8.0 revision1 hostmakedependsnodejs python3 make dependsopenssl short_descUniversal AI gateway with smart routing for multiple LLM providers maintainerzenobit zenobitdisroot.org licenseMIT homepagehttps://github.com/diegosouzapw/OmniRoute distfileshttps://github.com/diegosouzapw/OmniRoute/archive/refs/tags/v${version}.tar.gz # Regenerate the checksum for each release with: # curl -L -o /tmp/omniroute.tar.gz https://github.com/diegosouzapw/OmniRoute/archive/refs/tags/v${version}.tar.gz sha256sum /tmp/omniroute.tar.gz checksumPLACEHOLDER_REGENERATE_PER_RELEASE system_accounts_omniroute omniroute_homedir/var/lib/omniroute export NODE_ENVproduction export npm_config_engine_strictfalse export npm_config_loglevelerror export npm_config_fundfalse export npm_config_auditfalse do_build() { local _gyp_arch case $XBPS_TARGET_MACHINE in aarch64*) _gyp_archarm64 ;; armv7*|armv6*) _gyp_archarm ;; i686*) _gyp_archia32 ;; *) _gyp_archx64 ;; esac NODE_ENVdevelopment npm ci --ignore-scripts npm run build cp -r .next/static .next/standalone/.next/static [ -d public ] cp -r public .next/standalone/public || true local _node_gyp/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js (cd node_modules/better-sqlite3 node $_node_gyp rebuild --arch$_gyp_arch) local _bs3_release.next/standalone/node_modules/better-sqlite3/build/Release mkdir -p $_bs3_release cp node_modules/better-sqlite3/build/Release/better_sqlite3.node $_bs3_release/ rm -rf .next/standalone/node_modules/img for _mod in pino-abstract-transport split2 process-warning; do cp -r node_modules/$_mod .next/standalone/node_modules/ done } do_check() { npm run test:unit } do_install() { vmkdir usr/lib/omniroute/.next vcopy .next/standalone/. usr/lib/omniroute/.next/standalone for _d in \ .next/standalone/.next/server/app/dashboard \ .next/standalone/.next/server/app/dashboard/settings \ .next/standalone/.next/server/app/dashboard/providers; do touch ${DESTDIR}/usr/lib/omniroute/${_d}/.keep done cat ${WRKDIR}/omniroute EOF #!/bin/sh export PORT${PORT:-20128} export DATA_DIR${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute} export APP_LOG_TO_FILE${APP_LOG_TO_FILE:-false} mkdir -p ${DATA_DIR} exec node /usr/lib/omniroute/.next/standalone/server.js $ EOF vbin ${WRKDIR}/omniroute } post_install() { vlicense LICENSE }该模板揭示了几个值得注意的部署细节构建阶段需要按目标架构用 node-gyp 重新编译better-sqlite3原生模块这也是 npm/pnpm 安装时需要原生构建脚本放行的根本原因运行时包装脚本把DATA_DIR默认指向$XDG_DATA_HOME/omniroute确保数据落盘位置遵循 XDG 规范。卸载命令作用npm run uninstall移除系统应用但保留~/.omniroute中的 DB 与配置npm run uninstall:full移除应用并永久删除所有配置、密钥与数据库各安装方式的详细卸载说明见 UNINSTALL.md。需要特别提醒uninstall:full会不可逆地销毁全部 API 密钥与数据执行前请确认已做好备份。【免费下载链接】OmniRouteNever stop coding. Free MIT AI gateway: one endpoint, 352 providers (150 free), 1200 models Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax. Works with Claude Code, Codex, Cursor, OpenCode, Cline Copilot. Quota-aware auto-fallback, RTKCaveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 550 contributors项目地址: https://gitcode.com/GitHub_Trending/om/OmniRoute创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考