开发者每月需支付 $20–200 不等，以使用 Claude Pro、Codex Pro 或 GitHub Copilot。即便付费，配额也有限制——每日使用时长上限、每周限制，或是每分钟的速率限制。在编码过程中，服务提供商突然停止响应，导致开发者思路中断，效率大打折扣。

OmniRoute 如何解决这个问题：

• 智能四层回退 — 如果订阅配额用尽，自动切换到 API Key → 低价 → 免费方案，全程无需人工干预
• 提供商限制跟踪 — 缓存的配额快照按服务器端计划刷新（默认 PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES=70），同时支持在 UI 中手动刷新
• 多账户支持 — 每个提供商支持多个账户，自动轮询切换——当一个账户用尽时，无缝切换到下一个
• 自定义组合链 — 可自定义回退链，提供 13 种负载均衡策略（优先级、加权、先填满、轮询、P2C、随机、最少使用、成本优化、严格随机、自动、lkgp、上下文优化、上下文中继）
• 结构化组合构建器 — 分步骤构建组合，明确选择提供商、模型和账户，支持重复提供商及固定目标账户
• 配额感知的 P2C 策略 — 基于二的幂次账户选择现会考虑配额余量、退避机制、近期错误以及连续使用情况
• Codex 企业配额 — 直接在仪表板中监控企业/团队工作区的配额

OpenAI 使用一种格式，Claude（Anthropic）使用另一种，Gemini 则是第三种。如果开发者想测试不同提供商的模型或在它们之间进行回退，就需要重新配置 SDK、更换端点，并处理不兼容的格式问题。而一些自定义提供商（如 FriendLI、NIM）还拥有非标准的模型端点。

OmniRoute 如何解决这个问题：

• 统一端点 — 单一的 http://localhost:20128/v1 作为所有 100 多家提供商的代理
• 格式转换 — 自动且透明地实现 OpenAI ↔ Claude ↔ Gemini ↔ Responses API 的格式互转
• 响应净化 — 去除非标准字段（x_groq、usage_breakdown、service_tier），避免这些字段导致 OpenAI SDK v1.83+ 出错
• 角色归一化 — 将非 OpenAI 提供商的 developer 角色转换为 system；将 GLM/ERNIE 的 system 角色转换为 user
• “思考”标签提取 — 从 DeepSeek R1 等模型中提取 <think> 块，并将其标准化为 reasoning_content
• Gemini 的结构化输出 — 自动将 json_schema 转换为 responseMimeType/responseSchema
• stream 默认为 false — 符合 OpenAI 规范，避免在 Python/Rust/Go SDK 中出现意外的 SSE 流

像 OpenAI 和 Codex 这样的提供商会屏蔽某些地理区域的访问。用户在进行 OAuth 授权或 API 调用时，经常会遇到 unsupported_country_region_territory 错误。这对来自发展中国家的开发者来说尤其令人沮丧。

OmniRoute 如何解决这个问题：

• 三层代理配置 — 支持全局（所有流量）、单提供商（仅针对某一家提供商）以及单连接/密钥级别的代理配置
• 彩色代理标识 — 可视化指示：🟢 全局代理，🟡 提供商代理，🔵 连接代理，始终显示当前 IP 地址
• 通过代理交换 OAuth Token — OAuth 流程也经过代理，从而解决 unsupported_country_region_territory 问题
• 通过代理测试连接 — 连接测试均使用已配置的代理（不再直接绕过）
• SOCKS5 支持 — 完全支持 SOCKS5 代理用于出站路由
• TLS 指纹欺骗 — 通过 wreq-js 模拟浏览器 TLS 指纹，以绕过机器人检测
• CLI 指纹匹配 — 重新排列请求头和请求体字段，使其与原生 CLI 二进制文件的签名一致，从而大幅降低账号被标记的风险。同时保留代理 IP——既能保持隐蔽性，又能实现 IP 匿名化

并非所有人都能负担每月 20 至 200 美元的 AI 订阅费用。学生、来自新兴国家的开发者、业余爱好者和自由职业者都需要以零成本获取高质量的模型。

OmniRoute 如何解决这个问题：

• 内置免费层级提供商 — 原生支持 100% 免费的提供商：Qoder（通过 OAuth 提供 5 款无限量模型：kimi-k2-thinking、qwen3-coder-plus、deepseek-r1、minimax-m2、kimi-k2）；Qwen（4 款无限量模型：qwen3-coder-plus、qwen3-coder-flash、qwen3-coder-next、视觉模型）；Kiro（Claude + AWS Builder ID 免费）；Gemini CLI（每月 18 万 token 免费）
• Ollama Cloud — 在 api.ollama.com 上托管的 Ollama 模型，提供免费的“轻量使用”层级；使用 ollamacloud/<model> 前缀
• 纯免费组合链 — 将 gc/gemini-3-flash → if/kimi-k2-thinking → qw/qwen3-coder-plus 组合起来，即可实现每月零成本且无中断的服务
• NVIDIA NIM 免费访问 — 在 build.nvidia.com 上可获得约 40 RPM 的开发者永久免费访问权限，涵盖 70 多种模型（正从积分模式过渡到纯速率限制模式）
• 成本优化策略 — 自动选择最便宜可用提供商的路由策略

当将 AI 网关暴露到网络（LAN、VPS、Docker）时，任何拥有该地址的人都可以消耗开发者的令牌或配额。如果没有保护措施，API 就容易遭到滥用、提示注入等攻击。

OmniRoute 如何解决这个问题：

• API 密钥管理 — 提供按提供商生成、轮换和范围限定密钥的功能，并设有专门的 /dashboard/api-manager 页面
• 模型级权限控制 — 可将 API 密钥限制在特定模型上（如 openai/* 或通配符模式），并提供“允许全部”或“限制”开关
• API 端点保护 — 要求访问 /v1/models 必须使用密钥，并可阻止特定提供商出现在列表中
• 认证防护 + CSRF 保护 — 所有仪表板路由均受到 withAuth 中间件和 CSRF 令牌的保护
• 速率限制器 — 基于 IP 的速率限制，窗口时间可配置
• IP 过滤 — 提供白名单和黑名单功能，用于访问控制
• 提示注入防护 — 对恶意提示模式进行净化处理
• AES-256-GCM 加密 — 静态存储中的凭据采用加密保护

AI 提供商可能会变得不稳定，返回 5xx 错误，或遭遇临时的速率限制。如果开发者只依赖一家提供商，就会被打断。如果没有熔断机制，反复重试可能导致应用程序崩溃。

OmniRoute 如何解决这个问题：

• 设置驱动的锁定层级 — 提供商配置文件可在同一界面控制默认账户/模型锁定、全局模型隔离以及提供商熔断机制，同时显式上游的 Retry-After 窗口仍具有更高优先级
• 指数退避 — 针对账户/模型锁定以及更高级别的隔离，逐步延长重试间隔
• 防羊群效应 — 使用互斥锁和信号量保护，防止并发重试风暴
• 组合回退链 — 如果主提供商失败，系统会自动按链路顺序切换，无需人工干预
• 组合熔断器 — 自动禁用组合链中出现故障的提供商
• 健康仪表板 — 提供运行时间监控、熔断状态、锁定情况、缓存统计信息以及 p50/p95/p99 延迟数据

开发者会使用 Cursor、Claude Code、Codex CLI、OpenClaw、Gemini CLI、Kilo Code 等工具。每款工具的配置都不一样（API 端点、密钥、模型）。当切换供应商或模型时，重新配置非常耗时。

OmniRoute 如何解决这个问题：

• CLI 工具仪表板 — 专用页面，支持 Claude Code、Codex CLI、OpenClaw、Kilo Code、Antigravity、Cline 的一键设置
• GitHub Copilot 配置生成器 — 可为 VS Code 生成 chatLanguageModels.json 文件，并支持批量选择模型
• 入门向导 — 针对首次使用的用户，提供四步引导式设置流程
• 一个端点，支持所有模型 — 只需配置一次 http://localhost:20128/v1，即可访问 100 多家服务提供商

Claude Code、Codex、Gemini CLI、Copilot 等工具都使用 OAuth 2.0 协议，且令牌会过期。开发者需要不断重新认证，还会遇到 client_secret is missing、redirect_uri_mismatch 等问题，以及在远程服务器上出现的各种失败情况。尤其是在局域网或 VPS 上使用 OAuth 时，问题更加突出。

OmniRoute 如何解决这个问题：

• 自动刷新令牌 — OAuth 令牌会在过期前在后台自动刷新
• 内置 OAuth 2.0 (PKCE) — 自动化流程适用于 Claude Code、Codex、Gemini CLI、Copilot、Kiro、Qwen、Qoder 等工具
• 多账号 OAuth — 通过提取 JWT/ID 令牌，支持同一供应商下的多个账号
• 局域网/远程 OAuth 修复 — 自动检测私有 IP 以设置 redirect_uri，同时提供手动 URL 模式用于远程服务器
• Nginx 后端 OAuth 支持 — 使用 window.location.origin 以兼容反向代理
• 远程 OAuth 指南 — 提供 Google Cloud 凭证在 VPS/Docker 环境中的详细步骤指南

开发者会使用多家付费服务提供商，但却没有统一的费用视图。每个服务商都有自己的计费仪表板，但缺乏整合后的汇总信息。这可能导致意外的成本累积。

OmniRoute 如何解决这个问题：

• 成本分析仪表板 — 按照每个供应商跟踪每次调用的费用，并进行预算管理
• 分级预算限制 — 为每个级别设置支出上限，超出后会自动切换到备用方案
• 按模型定价配置 — 可针对不同模型自定义价格
• 按 API 密钥的使用统计 — 记录每个密钥的请求次数及最后使用时间
• 分析仪表板 — 包括统计卡片、模型使用图表、供应商表格等，显示成功率和延迟信息

当调用失败时，开发者往往不清楚是由于速率限制、令牌过期、格式错误，还是服务提供商自身的问题。日志分散在不同的终端中，缺乏可观ability，调试只能靠反复试错。

OmniRoute 如何解决这个问题：

• 统一日志仪表板 — 分为四个标签页：请求日志、代理日志、审计日志和控制台
• 控制台日志查看器 — 实时终端风格的查看器，带有颜色编码等级、自动滚动、搜索和筛选功能
• SQLite 摘要日志 — 请求和代理日志索引可在重启后继续查询，而无需将大型负载数据块加载到 SQLite 中
• 翻译 Playground — 提供四种调试模式：Playground（格式转换）、Chat Tester（往返测试）、Test Bench（批量测试）和 Live Monitor（实时监控）
• 请求遥测 — 提供 p50/p95/p99 延迟信息以及 X-Request-Id 追踪
• 基于文件的详细记录 — 应用日志会根据大小、保留天数和归档次数轮转；详细的请求/响应负载则保存在 DATA_DIR/call_logs/ 目录下，并独立于 SQLite 摘要日志进行轮转
• 系统信息报告 — 运行 npm run system-info 可生成包含完整环境信息的 system-info.txt 文件（Node 版本、OmniRoute 版本、操作系统、CLI 工具、Docker/PM2 状态等）。提交问题时附上该文件，可帮助快速定位问题。

在不同环境中（本地、VPS、Docker、云）安装、配置和维护 AI 代理是一项繁重的工作。硬编码路径、目录权限错误（EACCES）、端口冲突以及跨平台构建等问题都会增加难度。

OmniRoute 如何解决这个问题：

• npm 全局安装 — npm install -g omniroute && omniroute，简单完成
• Docker 多平台支持 — 原生支持 AMD64 和 ARM64 架构（Apple Silicon、AWS Graviton、Raspberry Pi）
• Docker Compose 配置文件 — 提供 base（不包含 CLI 工具）和 cli（包含 Claude Code、Codex、OpenClaw）两种配置
• Electron 桌面应用 — 适用于 Windows/macOS/Linux 的原生应用，配备系统托盘、开机自启动和离线模式
• 分端口模式 — API 和仪表板分别运行在不同端口上，适用于高级场景（反向代理、容器网络）
• 云端同步 — 通过 Cloudflare Workers 在不同设备之间同步配置
• 数据库备份 — 自动备份、恢复、导出和导入所有设置，并提供 DISABLE_SQLITE_AUTO_BACKUP 选项，方便外部管理备份

非英语国家的团队，尤其是拉丁美洲、亚洲和欧洲的团队，常常因为界面仅支持英文而面临困难。语言障碍不仅降低了产品的采用率，还增加了配置错误的可能性。

OmniRoute 如何解决这个问题：

• 仪表板国际化 — 支持 30 种语言 — 所有 500 多个文本键均已翻译，包括阿拉伯语、保加利亚语、丹麦语、德语、西班牙语、芬兰语、法语、希伯来语、印地语、匈牙利语、印尼语、意大利语、日语、韩语、马来语、荷兰语、挪威语、波兰语、葡萄牙语（PT/BR）、罗马尼亚语、俄语、斯洛伐克语、瑞典语、泰语、乌克兰语、越南语、中文、菲律宾语以及英语
• RTL 支持 — 对阿拉伯语和希伯来语提供从右到左的支持
• 多语言 README 文档 — 提供 30 种语言的完整文档翻译
• 语言选择器 — 页眉处的地球图标，可实时切换语言

AI 不仅仅局限于聊天补全。开发者还需要生成图片、转录音频、创建用于 RAG 的嵌入向量、对文档进行重新排序以及内容审核等功能。而每种功能对应的 API 端点和格式都不相同。

OmniRoute 如何解决这个问题：

• 嵌入 — /v1/embeddings，支持 6 家供应商和 9 模型以上
• 图像生成 — /v1/images/generations，支持 10 家供应商和 20 模型以上（OpenAI、xAI、Together、Fireworks、Nebius、Hyperbolic、NanoBanana、Antigravity、SD WebUI、ComfyUI）
• 文本转视频 — /v1/videos/generations — ComfyUI（AnimateDiff、SVD）和 SD WebUI
• 文本转音乐 — /v1/music/generations — ComfyUI（Stable Audio Open、MusicGen）
• 音频转录 — /v1/audio/transcriptions — Whisper + Nvidia NIM、HuggingFace、Qwen3
• 文本转语音 — /v1/audio/speech — ElevenLabs、Nvidia NIM、HuggingFace、Coqui、Tortoise、Qwen3、Inworld、Cartesia、PlayHT，以及现有供应商
• 内容审核 — /v1/moderations — 内容安全检查
• 重排序 — /v1/rerank — 文档相关性重排序
• 响应 API — 对 Codex 的完整 /v1/responses 支持

开发者希望知道哪种模型最适合自己的应用场景——代码生成、翻译、推理等——但手动比较效率太低。目前还没有集成的评估工具。

OmniRoute 如何解决：

• LLM 评估 — 使用预加载的 10 个案例进行黄金集测试，涵盖问候语、数学、地理、代码生成、JSON 格式合规性、翻译、Markdown 和安全性拒绝等内容
• 4 种匹配策略 — exact、contains、regex 和 custom（JS 函数）
• 翻译器 Playground 测试台 — 批量测试，支持多组输入和预期输出，并可跨供应商对比
• 聊天测试器 — 全流程交互，可视化响应结果
• 实时监控 — 实时展示所有通过代理的请求流

随着请求量的增长，如果没有缓存机制，相同的查询会导致重复计算，浪费成本。而缺乏幂等性则会使重复请求白白占用处理资源。此外，还需遵守各供应商的速率限制。

OmniRoute 如何解决：

• 语义缓存 — 两层缓存（签名 + 语义），有效降低成本并减少延迟
• 请求幂等性 — 为相同请求提供 5 秒去重窗口
• 速率限制检测 — 分别跟踪每个供应商的 RPM、最小间隔和最大并发数
• 可编辑的速率限制 — 在“设置 → 弹性”中配置默认值，并持久化保存
• API 密钥验证缓存 — 三层缓存，确保生产环境性能
• 健康仪表盘与遥测 — 提供 p50/p95/p99 延迟、缓存统计和运行时间等信息

开发者希望所有响应都以特定语言呈现、采用特定语气，或者限制推理 token 数量。如果要在每个工具或每次请求中单独配置，显然不现实。

OmniRoute 如何解决：

• 系统提示注入 — 全局应用到所有请求的提示
• 思考预算验证 — 每个请求的推理 token 分配控制（透传、自动、自定义、适应性）
• 9 种路由策略 — 全局策略决定请求如何分发
• 通配符路由器 — 使用 provider/* 模式动态路由到任意供应商
• 组合启用/禁用切换 — 可直接在仪表盘上切换组合
• 手动组合排序 — 拖动组合卡片调整顺序，并将排序结果持久化到 SQLite 中
• 供应商开关 — 一键启用或禁用某个供应商的所有连接
• 被屏蔽的供应商 — 将特定供应商从 /v1/models 列表中排除

许多 AI 网关仅将 MCP 隐藏为实现细节，而团队需要一个可见且易于管理的操作层。

OmniRoute 如何解决：

• MCP 出现在仪表盘导航和端点协议选项卡中
• 专门的 MCP 管理页面，包含流程、工具、作用域和审计记录
• 内置快速入门指南，用于 omniroute --mcp 和客户端接入

智能体工作流既需要直接回复，也需要长时间的流式执行，并能够控制其生命周期。

OmniRoute 如何解决：

• A2A JSON-RPC 端点（POST /a2a），支持 message/send 和 message/stream
• SSE 流式传输，可传递终端状态
• 任务生命周期 API，用于 tasks/get 和 tasks/cancel

运维团队需要了解 MCP 是否真正存活，而不仅仅是 API 是否可达。

OmniRoute 如何解决：

• 运行时心跳文件，包含 PID、时间戳、传输方式、工具数量和作用域模式
• MCP 状态 API 结合心跳和近期活动情况
• UI 状态卡片显示进程/运行时间/心跳新鲜度

当工具修改配置或触发运维操作时，团队需要具备法医级别的可追溯性。

OmniRoute 如何解决：

• 基于 SQLite 的审计日志记录 MCP 工具调用
• 支持按工具、成功/失败、API 密钥筛选，并提供分页功能
• 仪表盘审计表格及自动化统计端点

不同的客户应仅拥有对工具类别的最小权限访问。

OmniRoute 如何解决：

• 10 种细粒度的 MCP 作用域，用于控制工具访问
• 在 MCP 管理界面中强制实施作用域并控制可见性
• 为运维工具设置安全的默认配置

团队需要在突发事件或成本事件发生时，快速调整运行时配置。

OmniRoute 如何解决：

• 直接在 MCP 仪表盘上切换组合激活状态
• 从预定义的策略包中应用弹性配置
• 从同一运维面板重置熔断器状态

如果没有生命周期的可见性，任务故障将难以诊断。

OmniRoute 如何解决：

• 按状态和技能列出并筛选任务，支持分页
• 可深入查看任务元数据、事件和产物
• 提供任务取消端点和 UI 操作，并带有确认提示

流式工作流需要对并发性和实时连接有清晰的运营洞察。

OmniRoute 如何解决：

• 将活跃流计数器集成到 A2A 状态中
• 显示最后任务的时间戳和各状态下的任务数量
• A2A 仪表盘卡片，用于实时监控运营状况

外部客户和编排器需要机器可读的元数据来进行接入。

OmniRoute 如何解决：

• 代理卡片在 /.well-known/agent.json 中公开
• 管理 UI 中展示了功能和技能
• A2A 状态 API 包含用于自动化的发现元数据

如果用户无法发现协议接口，采用率和支持质量就会下降。

OmniRoute 的解决方案：

• 整合的 端点 页面，设有代理、MCP、A2A 和 API 端点选项卡
• MCP 和 A2A 的内联服务状态切换（在线/离线）
• 从概览页面到专用管理选项卡的链接

仅靠模拟测试不足以在发布前验证协议兼容性。

OmniRoute 的解决方案：

• E2E 套件会启动应用，并使用真实的 MCP SDK 客户端传输层
• A2A 客户端测试涵盖发现、发送、流式传输、获取和取消流程
• 对 MCP 审计和 A2A 任务 API 进行交叉检查断言

按协议划分可观测性会导致盲区并延长 MTTR。

OmniRoute 的解决方案：

• 在一个产品中提供统一的仪表盘、日志和分析
• 覆盖 OpenAI、MCP 和 A2A 层的健康状况、审计和请求遥测
• 提供用于状态监控和自动化的运营 API

运行多个独立的服务会增加运营成本并引入更多故障模式。

OmniRoute 的解决方案：

• 将兼容 OpenAI 的代理、MCP 服务器和 A2A 服务器集成在一个堆栈中
• 共享身份验证、弹性、数据存储和可观测性
• 在所有交互界面中保持一致的策略模型

当团队拼接多个临时服务和脚本时，开发速度会显著下降。

OmniRoute 的解决方案：

• 面向客户端和智能体的统一端点策略
• 内置的协议管理 UI 和冒烟测试路径
• 生产就绪的基础架构（安全性、日志记录、弹性和备份）

在深度调试过程中，包含工具结果的长对话历史会迅速超出提供商的令牌窗口，导致请求失败和孤立的上下文。

OmniRoute 的解决方案：

• 主动上下文压缩 — 在请求到达上游之前评估令牌预算，并通过智能二分查找机制主动修剪旧的对话历史。
• 结构完整性保护 — 自动跟踪显式的 tool_use 定义，并确保如果工具输入被截断，其对应的 tool_result 也会被安全移除，从而防止 API 验证错误。
• 多层丢弃 — 逐步丢弃系统消息、常规消息，最终严格执行长度限制，同时不破坏对话逻辑。

对于 Void Linux 用户，您可以使用 xbps-src 构建原生软件包。将以下内容保存为 srcpkgs/omniroute/template：

# ‘omniroute’ 的模板文件
pkgname=omniroute
version=3.4.1
revision=1
hostmakedepends="nodejs python3 make"
depends="openssl"
short_desc="支持多模型提供商的智能路由通用 AI 网关"
maintainer="zenobit <zenobit@disroot.org>"
license="MIT"
homepage="https://github.com/diegosouzapw/OmniRoute"
distfiles="https://github.com/diegosouzapw/OmniRoute/archive/refs/tags/v${version}.tar.gz"
checksum=009400afee90a9f32599d8fe734145cfd84098140b7287990183dde45ae2245b
system_accounts="_omniroute"
omniroute_homedir="/var/lib/omniroute"
export NODE_ENV=production
export npm_config_engine_strict=false
export npm_config_loglevel=error
export npm_config_fund=false
export npm_config_audit=false

do_build() {
	# 根据目标 CPU 架构确定 node-gyp 使用的架构
	local _gyp_arch
	case "$XBPS_TARGET_MACHINE" in
		aarch64*) _gyp_arch=arm64 ;;
		armv7*|armv6*) _gyp_arch=arm ;;
		i686*) _gyp_arch=ia32 ;;
		*) _gyp_arch=x64 ;;
	esac

	# 1) 安装所有依赖 – 跳过脚本（do_build 中无网络，原生模块将在下面单独编译；better-sqlite3 是 serverExternalPackage，因此 Next.js 在 next build 期间不会执行它）
	NODE_ENV=development npm ci --ignore-scripts

	# 2) 构建 Next.js 单体包
	npm run build

	# 3) 将静态资源复制到单体包中
	cp -r .next/static .next/standalone/.next/static
	[ -d public ] && cp -r public .next/standalone/public || true

	# 4) 为目标架构编译 better-sqlite3 的原生绑定。
	#    直接使用 node-gyp，以便利用 xbps-src 交叉工具链中的 CC/CXX，而不会被 npm 修改。
	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")

	# 5) 将编译好的绑定放入单体包中
	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/"

	# 6) 移除特定于架构的 sharp 包 – 上游设置了 images.unoptimized=true，因此运行时不会使用 sharp；x64 的 .so 文件会破坏 aarch64 的剥离过程
	rm -rf .next/standalone/node_modules/@img

	# 7) 复制 Next.js 静态分析遗漏的 pino 运行时依赖：
	#    pino-abstract-transport – pino 工作线程所需
	#    split2 – pino-abstract-transport 的依赖
	#    process-warning – pino 自身的依赖
	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

	# 防止安装后钩子删除空的 Next.js 应用路由器目录
	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
}

以 stdio 模式启动 MCP 传输：

omniroute --mcp

推荐的验证流程如下：

1. 通过 stdio 连接你的 MCP 客户端。
2. 运行 omniroute_get_health。
3. 运行 omniroute_list_combos。
4. 打开 /dashboard/mcp 确认心跳、活动和审计记录。

用于自动化的有用 API：

• GET /api/mcp/status
• GET /api/mcp/tools
• GET /api/mcp/audit
• GET /api/mcp/audit/stats

发现代理：

curl http://localhost:20128/.well-known/agent.json

发送任务：

curl -X POST http://localhost:20128/a2a \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":"setup-a2a","method":"message/send","params":{"skill":"quota-management","messages":[{"role":"user","content":"总结配额状态。"}]}}'

管理生命周期：

• GET /api/a2a/status
• GET /api/a2a/tasks
• GET /api/a2a/tasks/:id
• POST /api/a2a/tasks/:id/cancel

运维 UI：

• /dashboard/a2a 用于任务/状态/流的可观ability 和快速操作

使用真实客户端验证两个协议：

npm run test:protocols:e2e

这将验证：

• MCP SDK 客户端连接/列表/调用
• A2A 发现/发送/流式传输/获取/取消
• 在 MCP 审计和 A2A 任务管理 API 中交叉核对数据

Claude Code (Pro/Max)

仪表板 → 供应商 → 连接 Claude Code
→ OAuth 登录 → 自动刷新令牌
→ 5 小时 + 每周配额跟踪

模型：
  cc/claude-opus-4-6
  cc/claude-sonnet-4-5-20250929
  cc/claude-haiku-4-5-20251001

专业提示： 复杂任务使用 Opus，追求速度则用 Sonnet。OmniRoute 会按模型分别跟踪配额！

OpenAI Codex (Plus/Pro)

仪表板 → 供应商 → 连接 Codex
→ OAuth 登录（端口 1455）
→ 5 小时 + 每周重置

模型：
  cx/gpt-5.2-codex
  cx/gpt-5.1-codex-max

Codex 账户限额管理（5h + 每周）

每个 Codex 账户现在在 仪表板 -> 供应商 中都有策略开关：

• 5h（开启/关闭）：强制执行 5 小时窗口阈值政策。
• Weekly（开启/关闭）：强制执行每周窗口阈值政策。
• 阈值行为：当启用的窗口使用率达到或超过 90% 时，该账户会被跳过。
• 轮转行为：OmniRoute 会自动路由到下一个符合条件的 Codex 账户。 -重置行为：当提供商的 resetAt 时间过去后，该账户会自动重新进入轮转（无需手动重新启用）。

场景：

• 5h ON + Weekly ON：任一窗口达到阈值时，账户会被跳过。
• 5h OFF + Weekly ON：只有每周用量会阻止该账户。
• 5h ON + Weekly OFF：只有 5 小时用量会阻止该账户。
• 当 resetAt 过去后，账户会自动重新进入轮转（无需手动重新启用）。

Gemini CLI (免费 18 万/月！)

仪表板 → 供应商 → 连接 Gemini CLI
→ Google OAuth
→ 每月 18 万次补全 + 每日 1 千次

模型：
  gc/gemini-3-flash-preview
  gc/gemini-2.5-pro

超值选择： 巨大的免费层级！请在付费层级之前优先使用。

GitHub Copilot

仪表板 → 供应商 → 连接 GitHub
→ 通过 GitHub 进行 OAuth
→ 每月重置（每月 1 日）

模型：
  gh/gpt-5
  gh/claude-4.5-sonnet
  gh/gemini-3.1-pro-preview

NVIDIA NIM (免费开发者访问 — 70+ 模型)

1. 注册：build.nvidia.com
2. 获取免费 API 密钥（包含 1000 次推理积分）
3. 仪表板 → 添加供应商 → NVIDIA NIM：
   • API 密钥：nvapi-your-key

模型： nvidia/llama-3.3-70b-instruct、nvidia/mistral-7b-instruct 以及 50 多种其他模型

专业提示： 兼容 OpenAI 的 API — 可无缝对接 OmniRoute 的格式转换！

DeepSeek

1. 注册：platform.deepseek.com
2. 获取 API 密钥
3. 仪表板 → 添加供应商 → DeepSeek

模型： deepseek/deepseek-chat、deepseek/deepseek-coder

Groq（提供免费层级！）

1. 注册：console.groq.com
2. 获取 API 密钥（包含免费层级）
3. 仪表板 → 添加供应商 → Groq

模型： groq/llama-3.3-70b、groq/mixtral-8x7b

专业提示： 超高速推理 — 非常适合实时编码！

OpenRouter（100+ 模型）

1. 注册：openrouter.ai
2. 获取 API 密钥
3. 仪表板 → 添加提供商 → OpenRouter

模型： 通过一个 API 密钥即可访问来自所有主要提供商的 100 多种模型。

仪表板行为： OpenRouter 模型从“可用模型”中管理。手动添加、导入和自动同步都会更新同一列表。

GLM-4.7（每日重置，$0.6/1M）

1. 注册：Zhipu AI
2. 从 Coding Plan 获取 API 密钥
3. 仪表板 → 添加 API 密钥：
   • 提供商：glm
   • API 密钥：your-key

使用： glm/glm-4.7

实用技巧： Coding Plan 以七分之一的价格提供三倍配额！每日上午 10:00 重置。

MiniMax M2.1（5 小时重置，$0.20/1M）

1. 注册：MiniMax
2. 获取 API 密钥
3. 仪表板 → 添加 API 密钥

使用： minimax/MiniMax-M2.1

实用技巧： 长上下文（1M tokens）中最便宜的选择！

Kimi K2（$9/月固定）

1. 订阅：Moonshot AI
2. 获取 API 密钥
3. 仪表板 → 添加 API 密钥

使用： kimi/kimi-latest

实用技巧： 固定 $9/月可使用 10M tokens，相当于 $0.90/1M 的有效成本！

Qoder（通过 OAuth 提供 5 种免费模型）

仪表板 → 连接 Qoder
→ Qoder OAuth 登录
→ 无限使用

模型：
  if/kimi-k2-thinking
  if/qwen3-coder-plus
  if/glm-4.7
  if/minimax-m2
  if/deepseek-r1

Qwen（通过设备码提供 4 种免费模型）

仪表板 → 连接 Qwen
→ 设备码授权
→ 无限使用

模型：
  qw/qwen3-coder-plus
  qw/qwen3-coder-flash

Kiro（Claude 免费版）

仪表板 → 连接 Kiro
→ AWS Builder ID 或 Google/GitHub
→ 无限使用

模型：
  kr/claude-sonnet-4.5
  kr/claude-haiku-4.5

示例 1：最大化订阅 → 廉价备份

仪表板 → 组合 → 新建

名称：premium-coding
模型：
  1. cc/claude-opus-4-6（订阅主模型）
  2. glm/glm-4.7（廉价备份，$0.6/1M）
  3. minimax/MiniMax-M2.1（最便宜的后备，$0.20/1M）

在 CLI 中使用：premium-coding

示例 2：纯免费（零成本）

名称：free-combo
模型：
  1. gc/gemini-3-flash-preview（每月 18 万次免费调用）
  2. if/kimi-k2-thinking（无限使用）
  3. qw/qwen3-coder-plus（无限使用）

成本：永远 $0！

Cursor IDE

设置 → 模型 → 高级：
  OpenAI API 基础 URL：http://localhost:20128/v1
  OpenAI API 密钥：[来自 OmniRoute 仪表板]
  模型：cc/claude-opus-4-6

Claude Code

使用仪表板中的“CLI 工具”页面进行一键配置，或手动编辑 ~/.claude/settings.json。

Codex CLI

export OPENAI_BASE_URL="http://localhost:20128"
export OPENAI_API_KEY="your-omniroute-api-key"

codex "your prompt"

OpenClaw

选项 1 — 仪表板（推荐）：

仪表板 → CLI 工具 → OpenClaw → 选择模型 → 应用

选项 2 — 手动： 编辑 ~/.openclaw/openclaw.json：

{
  "models": {
    "providers": {
      "omniroute": {
        "baseUrl": "http://127.0.0.1:20128/v1",
        "apiKey": "sk_omniroute",
        "api": "openai-completions"
      }
    }
  }
}

注意： OpenClaw 只能在本地 OmniRoute 上运行。为避免 IPv6 解析问题，请使用 127.0.0.1 而不是 localhost。

Cline / Continue / RooCode

设置 → API 配置：
  提供商：OpenAI 兼容
  基础 URL：http://localhost:20128/v1
  API 密钥：[来自 OmniRoute 仪表板]
  模型：if/kimi-k2-thinking

OpenCode

步骤 1： 将 OmniRoute 添加为自定义提供商：

opencode
/connect
# 选择“其他”→ 输入 ID：“omniroute”→ 输入你的 OmniRoute API 密钥

步骤 2： 在项目根目录创建或编辑 opencode.json：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "omniroute": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "OmniRoute",
      "options": {
        "baseURL": "http://localhost:20128/v1"
      },
      "models": {
        "cc/claude-sonnet-4-20250514": { "name": "Claude Sonnet 4" },
        "gg/gemini-2.5-pro": { "name": "Gemini 2.5 Pro" },
        "if/kimi-k2-thinking": { "name": "Kimi K2（免费）" }
      }
    }
  }
}

步骤 3： 在 OpenCode 中选择模型：

/models
# 从列表中选择任意 OmniRoute 模型

提示： 将你 OmniRoute /v1/models 端点中提供的任何模型添加到“models”部分。使用来自 OmniRoute 仪表板的格式“provider/model-id”。

“语言模型未提供消息”

• 提供商配额已耗尽 → 检查仪表板上的配额跟踪器
• 解决方案：使用组合后备或切换到更便宜的层级

速率限制

• 订阅配额用尽 → 切换到 GLM/MiniMax
• 添加组合：cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking

OAuth 令牌过期

• OmniRoute 会自动刷新
• 如果问题仍然存在：仪表板 → 提供商 → 重新连接

费用过高

• 检查仪表板 → 成本中的使用统计
• 将主模型切换到 GLM/MiniMax
• 对于非关键任务，使用免费层级（Gemini CLI、Qoder）

仪表板/API 端口错误

• PORT 是标准基础端口（默认也是 API 端口）
• API_PORT 仅覆盖 OpenAI 兼容 API 监听器
• DASHBOARD_PORT 仅覆盖仪表板/Next.js 监听器
• 将 NEXT_PUBLIC_BASE_URL 设置为你的仪表板/公共 URL（用于 OAuth 回调）

云同步错误

• 确认 BASE_URL 指向你正在运行的实例
• 确认 CLOUD_URL 指向你期望的云端点
• 保持 NEXT_PUBLIC_* 值与服务器端值一致

首次登录不成功

• 检查 .env 中的 INITIAL_PASSWORD
• 如果未设置，回退密码为 123456

没有请求日志

• SQLite 中的 call_logs 存储了请求日志表和分析视图的摘要元数据
• 详细的请求/响应负载会以每个请求一个 JSON 文件的形式写入 DATA_DIR/call_logs/
• 如果需要详细的各阶段负载，可在仪表板 → 日志 → 请求日志 中启用管道捕获
• 导出日志 会按需读取这些文件，而 导出全部 会将 call_logs/ 目录与 storage.sqlite 一起导出
• 如果还希望将应用控制台日志记录到 logs/application/app.log，请设置 APP_LOG_TO_FILE=true
• 根据需要调整 APP_LOG_MAX_FILE_SIZE、APP_LOG_RETENTION_DAYS、APP_LOG_MAX_FILES 和 CALL_LOG_MAX_ENTRIES

连接测试显示 OpenAI 兼容提供商为“无效”

• 许多提供商并未公开 /models 端点
• OmniRoute v1.0.6+ 包含通过聊天完成的回退验证
• 确保基础 URL 包含 /v1 后缀

🔐 远程服务器上的 OAuth

⚠️ 对在 VPS、Docker 或任何远程服务器上运行 OmniRoute 的用户非常重要

为什么 Antigravity / Gemini CLI 的 OAuth 在远程服务器上会失败？

Antigravity 和 Gemini CLI 提供商使用 Google OAuth 2.0。Google 要求 OAuth 流程中的 redirect_uri 必须与应用在 Google Cloud 控制台中预先注册的 URI 完全匹配。

OmniRoute 中捆绑的 OAuth 凭证仅针对 localhost 注册。当您在远程服务器上访问 OmniRoute 时（例如 https://omniroute.myserver.com），Google 会以以下错误拒绝认证：

Error 400: redirect_uri_mismatch

解决方案：配置您自己的 OAuth 凭证

您需要在 Google Cloud 控制台中创建一个适用于您服务器 URI 的 OAuth 2.0 客户端 ID。

操作步骤

1. 打开 Google Cloud 控制台

访问：https://console.cloud.google.com/apis/credentials

2. 创建新的 OAuth 2.0 客户端 ID

• 点击 "+ Create Credentials" → "OAuth client ID"
• 应用程序类型："Web application"
• 名称：任意名称（例如 OmniRoute Remote）

3. 添加已授权的重定向 URI

在 "Authorized redirect URIs" 字段中，添加：

https://your-server.com/callback

将 your-server.com 替换为您的服务器域名或 IP 地址（如有必要，请包含端口，例如 http://45.33.32.156:20128/callback）。

4. 保存并复制凭证

创建完成后，Google 会显示 客户端 ID 和 客户端密钥。

5. 设置环境变量

在您的 .env 文件（或 Docker 环境变量）中：

# 对于 Antigravity：
ANTIGRAVITY_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com
ANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-your-secret

# 对于 Gemini CLI：
GEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com
GEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret
GEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret

6. 重启 OmniRoute

# 使用 npm：
npm run dev

# 使用 Docker：
docker restart omniroute

7. 再次尝试连接

仪表盘 → 提供商 → Antigravity（或 Gemini CLI）→ OAuth

现在 Google 将正确重定向到 https://your-server.com/callback。

临时解决方案（无需自定义凭证）

如果您目前不想设置自己的凭证，仍然可以使用 手动 URL 流程：

1. OmniRoute 会打开 Google 授权 URL。
2. 授权完成后，Google 会尝试重定向到 localhost（这在远程服务器上会失败）。
3. 从浏览器地址栏复制完整 URL（即使页面未加载）。
4. 将该 URL 粘贴到 OmniRoute 连接模态框中显示的字段。
5. 点击 "Connect"。

这种方法可行，因为 URL 中的授权码是有效的，无论重定向页面是否成功加载。

Error 400: redirect_uri_mismatch

https://seu-servidor.com/callback

# 对于 Antigravity：
ANTIGRAVITY_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com
ANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret

# 对于 Gemini CLI：
GEMINI_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com
GEMINI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret
GEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret

# 如果使用 npm：
npm run dev

# 如果使用 Docker：
docker restart omniroute

• 运行时: Node.js 18–22 LTS (⚠️ Node.js 24+ 不支持 — better-sqlite3 的原生二进制文件不兼容)
• 语言: TypeScript 5.9 — src/ 和 open-sse/ 全部采用 100% TypeScript（自 v2.0 起，核心模块中无 any 类型）
• 框架: Next.js 16 + React 19 + Tailwind CSS 4
• 数据库: better-sqlite3 (SQLite) + LowDB (JSON 旧版) — 用于存储领域状态、代理日志、MCP 审计记录、路由决策、内存及技能数据
• Schema 验证: Zod（用于 MCP 工具的输入输出验证及 API 协议定义）
• 协议: MCP（通过标准输入输出/HTTP）+ A2A v0.3（基于 JSON-RPC 2.0 和 SSE）
• 流式传输: 服务器发送事件 (SSE)
• 认证: OAuth 2.0 (PKCE) + JWT + API 密钥 + MCP 作用域授权
• 测试: Node.js 测试运行器 + Vitest（包含单元测试、集成测试和端到端测试在内的 900 多个测试用例）
• CI/CD: GitHub Actions（发布时自动进行 npm 发布及 Docker Hub 更新）
• 网站: omniroute.online
• NPM 包: npmjs.com/package/omniroute
• Docker 镜像: hub.docker.com/r/diegosouzapw/omniroute
• 系统韧性: 熔断器、指数退避、防雪崩机制、TLS 欺骗防护、自动组合自我修复功能