# 🚀 OmniRoute — O Gateway de IA Gratuito
**Criado por [Diego Souza](https://github.com/diegosouzapw)**
## 💰 ~1.62B Tokens / Mês em Free Tiers de Terceiros
> **Utilize as suas próprias contas de fornecedores.** Este é um agregado estimado entre free tiers de terceiros elegíveis separadamente, não uma atribuição de tokens do OmniRoute. Registe-se, obtenha as credenciais quando necessário e ligue os fornecedores que pode utilizar; cada fornecedor controla os seus limites, disponibilidade e termos.
>
> Combinar free tiers manualmente é penoso — dezenas de SDKs, dezenas de limites de taxa e nenhuma ideia de quanto tem realmente disponível. O OmniRoute cataloga **465 entradas de free tier em 34 chaves de pool recorrentes** e calcula o valor principal de tokens a partir dos **17 pools com um orçamento mensal positivo publicado, além de cinco limites Groq por modelo**, deduplicados por pool partilhado. As quotas que só ficam disponíveis após uma verificação de identidade regional (atualmente: ModelScope) são apresentadas separadamente, +~6M após a verificação de identidade regional, e nunca são somadas ao valor principal. O resultado permanece visível no dashboard (`/dashboard/free-tiers`).
> Resumo animado da página `/dashboard/free-tiers` em tempo real. Metodologia completa (deduplicação de pools, níveis de créditos, termos dos fornecedores): **[docs/reference/FREE_TIERS.md](docs/reference/FREE_TIERS.md)**.
>
> Estes valores são reavaliados de duas em duas semanas com base no catálogo em tempo real e **podem variar em ambas as direções** — um fornecedor termina um free tier e o número diminui; surge um novo e aumenta. Publicamos o que o catálogo calcula efetivamente, nunca um cenário otimista arredondado por excesso.
⭐ Adicione uma estrela ao repositório se o OMNIROUTE o ajudou a poupar dinheiro e a tornar o seu trabalho mais fácil.
[](https://github.com/diegosouzapw/OmniRoute)
[](https://www.star-history.com/diegosouzapw/omniroute)
[](https://olud.ai/project/diegosouzapw-omniroute.html)
### 💬 Junte-se à comunidade
**👋 Siga o responsável pela manutenção — seja dos primeiros a conhecer novos fornecedores, lançamentos e dicas:**
[](https://www.linkedin.com/in/diegosouzapw/)
[](https://github.com/diegosouzapw)
[](https://discord.gg/U47eFqAXCn)
[](https://t.me/omnirouteOficial)
[](https://chat.whatsapp.com/FvuCbrpZmQ6I85n2vW5QIC?s=cl&p=a&mlu=4)
[](https://chat.whatsapp.com/KWgatljAjmbELQory59Oti?s=cl&p=a&mlu=4)
[](https://omniroute.online)
**Dúvidas, dicas sobre fornecedores, roadmap e suporte → [Discord](https://discord.gg/U47eFqAXCn) · [Telegram](https://t.me/omnirouteOficial) · WhatsApp [🌍 Global](https://chat.whatsapp.com/FvuCbrpZmQ6I85n2vW5QIC?s=cl&p=a&mlu=4) / [🇧🇷 Brasil](https://chat.whatsapp.com/KWgatljAjmbELQory59Oti?s=cl&p=a&mlu=4) / [Portal](https://portal.sthub.com.br/communities/groups/st-hub/channels/Omniroute-World-8kRjmK)**
## 📈 O Gateway Continua a Crescer
| | v3.8.50 | **v3.8.51** | `v3.8.54+` |
| ------------------------------------------ | :----------------------: | :---------: | :---------------------: |
| 🌐 Fornecedores | 352 | **358** | 388 |
| 🧠 IDs únicos de modelos de chat | 1320 | **1374** | 1491 |
| 🖼️ Ponte de modalidades | 🆕 visão + áudio + vídeo | ✓ | ✓ |
| 📡 Catálogo gratuito do Radar | 🆕 opt-in | ✓ | ✓ |
| ⚖️ Agendamento com conhecimento das quotas | 🆕 Quota-Share | ✓ | ✓ |
| 📊 Telemetria de quotas | 🆕 em direto | ✓ | ✓ |
| 🧰 Modo headless | — | — | 🆕 `serve --headless` |
| 🛤️ Infraestrutura ferroviária LTS | — | — | 🆕 canais de lançamento |
| 🔎 API de descoberta de modelos | — | — | 🆕 `/v1/models/query` |
**→ [Roteiro](ROADMAP.md) — a percorrer a linha até `v3.9.0 LTS`**
## 🧩 Disponível
[](https://www.npmjs.com/package/omniroute)
[](https://hub.docker.com/r/diegosouzapw/omniroute)
[](LICENSE)
## 🆓 Instale, ligue um fornecedor e encaminhe através de um único endpoint
```bash
# Depois de ligar um fornecedor, copie a sua chave do OmniRoute a partir de Painel → Endpoints:
curl http://localhost:20128/v1/chat/completions \
-H "Authorization: Bearer YOUR_OMNIROUTE_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"auto","messages":[{"role":"user","content":"Hello!"}]}'
```
`auto` necessita de uma rota elegível. Uma instalação recente pode não ter destinos elegíveis sem chave, e um fornecedor sem chave pode rejeitar clientes de terceiros. Os fornecedores marcados como `tos: avoid`, incluindo o Kiro, são excluídos do encaminhamento automático por predefinição; ligar uma conta não substitui essa definição. Consulte o [Guia dos Escalões Gratuitos](docs/getting-started/FREE-TIERS-GUIDE.md) antes de escolher um fornecedor.📦 Scripts de início rápido prontos a copiar e colar para **Python, Node.js, PHP e cURL** → [`examples/quickstart/`](examples/quickstart/)
# 💥 A promessa
# 🤔 Porquê o OmniRoute?
## 🤝 Apoiado pelos nossos Amigos de Código Aberto
> **Quer juntar-se como Amigo de Código Aberto?** Estas são as empresas que apoiam o código aberto e ajudam a manter o OmniRoute em movimento — e nós dizemos publicamente para onde vai cada token que nos dão. Contacte-nos: [diegosouza.pw@outlook.com](mailto:diegosouza.pw@outlook.com)
Kimi Moonshot AI
Obrigado à Kimi (Moonshot AI), o nosso Amigo Fundador de Código Aberto, por apoiar este projeto! A Kimi é o laboratório de IA por trás das famílias de modelos de peso aberto K2 e K3 — o Kimi K3 oferece uma janela de contexto de 1M de tokens, visão nativa e codificação de nível de fronteira a uma fração dos preços dos modelos fechados, e funciona de imediato com Claude Code, Codex e todas as ferramentas de codificação que o OmniRoute serve.
O que o apoio da Kimi impulsiona: Os créditos da API da Kimi alimentam o pipeline de lançamento validado por IA do OmniRoute — a fase de validação de fusão impulsionada pelo Kimi K3 que revê cada pull request antes de ser enviada — além do desenvolvimento diário de funcionalidades. O suporte de primeira classe da Kimi é enviado em ambas as vias: a API direta da Kimi (kimi-k3) e o plano de codificação Kimi Code (OAuth e chave API). O OmniRoute é também o primeiro projeto de código aberto brasileiro no programa de apoio da Kimi. Obtenha uma chave API da Kimi com 15% de créditos extra →
Cheaper Inference cheaperinference.com
Obrigado à Cheaper Inference, um Amigo de Código Aberto do OmniRoute, por apoiar este projeto! A Cheaper Inference é um gateway classificado por custo que revende 42 modelos de fronteira — Claude, GPT-5.x, Gemini, Kimi K3, GLM, DeepSeek, Grok e MiniMax — por trás de um único endpoint compatível com OpenAI, encaminhando cada pedido para o fornecedor elegível mais barato sem nunca cobrar acima do preço de tabela do criador do modelo.
Suporte de primeira classe no OmniRoute: Chat Completions, o endpoint nativo /v1/responses, visão, chamada de ferramentas e 3 modelos de imagem (grok-imagine, nano-banana-pro, nano-banana-2, acessíveis como cheaperinference/<model>). Obtenha uma chave API →
Os links marcados com aff=omniroute são links de parceiros. Eles financiam o projeto sem custo adicional para si. 🎟️ Promoção de Afiliados — cupões de inscrição gratuitos de fornecedores que não patrocinamos (clique para expandir)Esta secção destina-se apenas a códigos de referência/cupão. As parcerias patrocinadas encontram-se em 🤝 Apoiado pelos nossos Amigos de Código Aberto acima. O OmniRoute não tem patrocínio ou parceria com os fornecedores aqui listados — estes são cupões públicos que qualquer pessoa pode usar.
AgentRouter agentrouter.org
AgentRouter — inscrição de afiliado · $100 em créditos gratuitos na inscrição (servidor gratuito, espere maior latência — melhor para testes, não para produção). Suporte de primeira classe no OmniRoute desde a v3.8.50: Chat Completions, o formato de comunicação compatível com Anthropic e o caminho compatível com OpenAI. Os modelos disponíveis incluem claude-opus-4-8, claude-opus-5, gpt-5.6-sol e mais. Agarre os seus $100 →
⚠️ Link de afiliado — O OmniRoute não tem patrocínio ou parceria com este fornecedor.
Conhece outro fornecedor com um cupão de inscrição gratuito generoso que beneficie os utilizadores do OmniRoute? Abra uma issue e nós adicioná-lo-emos aqui.
## 🎯 Combos — A Funcionalidade Principal
> Um **combo** é uma cadeia de modelos entre os quais o OmniRoute encaminha pedidos **automaticamente**. Se a quota se esgotar, um fornecedor falhar ou os custos dispararem, o combo pode avançar para o modelo elegível e operacional seguinte. 🛡️
### ⚡ Sem configuração — basta usar `auto`
Não é necessário criar nenhum combo. Defina o seu modelo como `auto` (ou uma variante) e o OmniRoute cria um combo virtual a partir dos fornecedores ligados, avaliados em tempo real:
ID do modelo
O que otimiza
auto
🎯 Predefinição equilibrada (LKGP — mantém o último fornecedor que funcionou corretamente)
auto/coding
🧑💻 Ponderações que dão prioridade à qualidade na geração de código
auto/fast
⚡ Menor latência em primeiro lugar
auto/cheap
💰 Menor custo por token em primeiro lugar
auto/subscription
🎟️ Apenas a quota da subscrição que já paga — falha de forma fechada, sem nunca recorrer a uma alternativa faturável (guia)
auto/thrifty
🪜 Primeiro a quota do plano e, depois, um nível de cada vez até às opções pagas mais baratas — regressa ao plano após a reposição da quota (guia)
auto/offline
🔋 Maior margem de quota/limite de pedidos em primeiro lugar
auto/smart
🔭 Prioridade à qualidade + 10% de exploração para descobrir modelos melhores
auto/lkgp
📌 Afinidade explícita com o último fornecedor que funcionou corretamente
auto/chaos
🧪 Distribuição paralela por um painel de modelos (um por fornecedor, 5 por predefinição), devolvendo uma resposta; uma chamada a montante por modelo do painel, não se trata de injeção de falhas
##
### 🔀 Ou crie o seu próprio combo — 20 estratégias de encaminhamento
Todas as **20** estratégias — combine-as livremente em cada etapa do combo:
#
Estratégia
O que faz
1
priority
Lista ordenada pelo primeiro destino — esgota cada um antes de avançar para o seguinte 🥇
2
fill-first
Utiliza totalmente a quota de cada destino antes de avançar
3
weighted
Seleção aleatória ponderada pelo peso de cada destino
4
round-robin
Percorre ciclicamente os destinos por ordem
5
p2c
Balanceamento de carga aleatório pelo método de escolha entre duas opções
6
least-used
Seleciona o destino com a menor carga atual
7
random
Seleção aleatória uniforme (sem duplicados)
8
strict-random
Seleção aleatória sem eliminar repetições 🎲
9
cost-optimized
Minimiza o custo por pedido com base nos preços do catálogo em tempo real 💸
10
headroom
Seleciona o destino com a maior quota restante
11
quota-weighted
Ignora contas esgotadas e, depois, seleciona proporcionalmente à quota restante ÷ carga em curso — as conversas existentes permanecem fixadas ⚖️
12
reset-window
Prefere o destino cuja janela de quota é reposta mais cedo
13
reset-aware
Ordena pela hora de reposição da quota — janelas curtas primeiro 📊
14
context-relay
Transfere o contexto entre destinos em conversas longas 🧠
15
context-optimized
Seleciona a opção mais adequada ao tamanho do contexto atual
16
cache-optimized
Fixa cada prefixo reutilizável do pedido à mesma conta — maximiza as correspondências na cache de pedidos 🎯
17
lkgp
Último Caminho Conhecido como Funcional — fixa o último fornecedor bem-sucedido e, depois, recorre às regras como alternativa
18
auto
Avaliação em tempo real com 16 fatores para todas as ligações 🤖
19
fusion
Distribui o pedido por um painel de modelos + um avaliador sintetiza uma única resposta 🧬
20
pipeline
Encadeia etapas — a saída de cada destino alimenta o seguinte 🔗
O motor Auto-Combo classifica cada candidato com base em **16 fatores** (estado, quota, custo, latência, adequação à tarefa, qualidade, disponibilidade da sessão…) — consulte [`docs/routing/AUTO-COMBO.md`](docs/routing/AUTO-COMBO.md).
##
### 🧱 A resiliência está integrada (3 camadas independentes)
📖 [Motor Auto-Combo](docs/routing/AUTO-COMBO.md) · [Guia de Resiliência](docs/architecture/RESILIENCE_GUIDE.md)
## 🏆 O Que Distingue o OmniRoute
📊 Metodologia completa e detalhes por funcionalidade face ao 9router, OpenRouter, CLIProxyAPI e LiteLLM → [`docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md`](docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md)
## 💚 Apoie o OmniRoute
O OmniRoute tem licença MIT e é mantido de forma aberta. Se lhe poupar tempo ou dinheiro, veja como pode ajudar a mantê-lo independente — escolha a opção mais adequada para si. O patrocínio nunca afeta a prioridade de encaminhamento; proporciona visibilidade, não uma posição superior.
⭐ Dê uma estrela ao repositório
Grátis — ajuda genuinamente a aumentar a visibilidade
**🇧🇷 PIX** — instantâneo, sem taxas (Brasil)
Chave (aleatória): `5d865059-bc44-483a-962d-43ceb80126eb`
Pix para copiar e colar:
```
00020101021126580014br.gov.bcb.pix01365d865059-bc44-483a-962d-43ceb80126eb5204000053039865802BR5922OMNIROUTE CONTRIBUICAO6006BRASIL62070503***630475DD
```
₿ Criptomoedas — BTC · ETH · USDT-TRC20 · USDC-Solana (clique para expandir)
₿ BTC
Bitcoin (SegWit)
bc1qh00smz004sy85wyl28v77tenkt3ckl6eaep7fd
Ξ ETH
Ethereum (ERC20)
0x64Cf6B68A6Ff34288e89172950a2d00102337a84
₮ USDT
Tron (TRC20)
TKAF41JpuQrHbKTnsQa9svJE2T192Hvsc2
$ USDC
Solana
2emNNZzVVWQc3FQ2wk9M6qXUQmW8AKdjjL174fXR28Tu
⚠️ Envie cada moeda apenas através da rede indicada — o envio através da rede errada pode resultar na perda dos fundos.
🐛 Encontrou um erro ou tem algum comentário? Abra uma [Discussão](https://github.com/diegosouzapw/OmniRoute/discussions).
Notas para programadores: O projeto pode gerar um ficheiro .env local durante npm install/postinstall, para conveniência dos programadores. Este ficheiro é intencionalmente ignorado através de .gitignore (consulte .gitignore) e nunca deve ser incluído num commit — se for incluído acidentalmente, substitua quaisquer segredos expostos e remova o ficheiro do histórico. Consulte docs/DEVELOPER-ENVIRONMENT.md para obter orientações sobre a gestão de ficheiros de ambiente locais e segredos.
## 📡 OmniRoute Radar
O valor principal do nível gratuito continua a ser **~1,62 mil milhões de tokens/mês**, com base no catálogo documentado e sem duplicações entre pools apresentado acima. Os créditos temporários de registo dos fornecedores podem aumentar separadamente o total do primeiro mês para **~2,22 mil milhões**. O Radar é uma sobreposição opcional e assinada do catálogo, destinada a quem pretende informações mais atualizadas sobre a disponibilidade de modelos gratuitos entre lançamentos do OmniRoute; o catálogo da comunidade e todas as funcionalidades gratuitas existentes continuam a ser gratuitos.
Os apoiantes podem receber o catálogo em tempo real e oportunidades adicionais de fornecedores. O respetivo limite máximo, separado e variável, é de **aproximadamente 3 mil milhões de tokens/mês, no máximo**, dependendo da disponibilidade dos fornecedores. Este limite máximo não constitui uma garantia: os fornecedores podem alterar as quotas, os critérios de elegibilidade, os modelos ou as regiões a qualquer momento.
O Radar é opcional e utiliza apenas pedidos GET. O cliente OmniRoute não envia prompts, tráfego, configurações de fornecedores, telemetria de utilização nem o estado local relativo à dispensa de anúncios. Saiba mais sobre a elegibilidade e o catálogo atual em **[radar.omniroute.online/planos](https://radar.omniroute.online/planos)**.
## ✨ Novidades
> Destaques recentes de **v3.8.20 → v3.8.54**. Histórico completo em [`CHANGELOG.md`](CHANGELOG.md).
- **⚖️ Roteamento `quota-weighted`** — a 20.ª estratégia de combinação ignora as contas esgotadas e, em seguida, seleciona entre as restantes na proporção da quota restante ÷ carga em curso, mantendo as conversas existentes fixadas. → [Combinações automáticas](docs/routing/AUTO-COMBO.md)
- **🧰 Modo sem interface** — `omniroute serve --headless` (ou `OMNIROUTE_HEADLESS=1`) executa apenas o motor proxy `/v1/*`, com o painel e os subsistemas exclusivos do painel desativados. → [Modo sem interface](docs/guides/HEADLESS.md)
- **🔎 Descoberta de modelos** — `/v1/models` filtra por capacidade, contexto, tipo e texto, e `POST /v1/models/query` devolve uma lista curta e determinística com a mesma visibilidade por chave. → [Referência da API](docs/reference/API_REFERENCE.md)
- **🔑 Controlo de roteamento por chave** — fixe uma chave de API a um modelo ou combinação com `forcedModel` e adicione ou remova atomicamente os modelos e combinações de uma chave (`/api/keys/{id}/access`). → [Referência da API](docs/reference/API_REFERENCE.md) · [OpenAPI](docs/openapi.yaml)
- **🛡️ Controlos de PII mais refinados** — seleção por tipo, até 20 padrões de mascaramento personalizados validados e contadores de deteção por tipo; o mascaramento continua a ser opcional. → [Medidas de proteção](docs/security/GUARDRAILS.md)
- **🌍 67 idiomas** — painel, réplicas da documentação e CLI, com `npm run i18n:add-locale` a adicionar um idioma em todo o lado com um único comando. → [Guia de i18n](docs/guides/I18N.md)
- **🎛️ OmniConductor** — delegação A2A de entrada para a sua frota de agentes, competências do Conductor no Agent Card e um painel com conversação de voz push-to-talk do Faro. → [Servidor A2A](docs/frameworks/A2A-SERVER.md)
- **🛂 Admissão adaptativa e proteção contra sobrecarga** — os pedidos de chat pesados entram em fila em vez de devolverem 503, com leases de RPM atómicos e deslizantes por ligação. → [Guia de resiliência](docs/architecture/RESILIENCE_GUIDE.md)
- **🗂️ Ordenação canónica de `/v1/models`** — um único bloco contíguo agrupado por fornecedor para cada fornecedor (com as combinações fixadas primeiro), estável em todas as fontes de catálogo. → [Referência da API](docs/reference/API_REFERENCE.md)
- **🗜️ Reforço da compressão** — proteção contra inflação ativada por predefinição, pacotes Caveman para DE / FR / JA + chinês (wényán), filtros RTK para Gradle e .NET. → [Compressão](docs/compression/COMPRESSION_ENGINES.md)
- **💸 Custo honesto de tarifa fixa** — os fornecedores de subscrições / planos de programação apresentam **$0** na análise de custos; o orçamento, a quota e o roteamento continuam a fazer estimativas. → [Referência da API](docs/reference/API_REFERENCE.md)
- **⚖️ Roteamento Quota-Share** — divide equitativamente a quota de uma conta partilhada entre chaves agrupadas, aproveitando os recursos disponíveis para que as fatias inativas possam ser emprestadas. → [Guia de resiliência](docs/architecture/RESILIENCE_GUIDE.md)
- **🤖 Configuração da CLI/agente com um único comando** — 15 comandos `setup-*` registados; `omniroute run` inicia 7 CLIs (Claude Code, Codex, Aider, Goose, OpenCode, Qwen Code, Gemini CLI); `omniroute configure` suporta 11 destinos com um seletor interativo de fornecedor+modelo e favoritos por contexto. → [Integrações da CLI](docs/guides/CLI-INTEGRATIONS.md)
- **🛰️ Modo remoto** — controle um OmniRoute remoto com tokens com âmbito (`connect` / `contexts` / `tokens`) + um auxiliar OAuth `antigravity` para instalações em VPS. → [Modo remoto](docs/guides/REMOTE-MODE.md)
- **🧭 Roteamento automático mais inteligente** — combinações `auto/:`, **Fusion** (painel de modelos + avaliador), roteamento sensível à tarefa e substituições por pedido para modelo / modo / orçamento em USD. → [Combinações automáticas](docs/routing/AUTO-COMBO.md)
- **🗜️ Compressão modular** — 12 motores combináveis + Compression Studios: LLMLingua-2, Ultra em dois níveis, omniglyph, controlo de fidelidade por etapa, GCF v3.2 e editor de arrastar para reordenar. → [Compressão](docs/compression/COMPRESSION_ENGINES.md)
- **🕵️ Desencriptação MITM transparente (TPROXY)** — captura CLIs que ignoram variáveis de ambiente de proxy, com uma CA por SNI + instalador de armazenamento de confiança. → [MITM/TPROXY](docs/security/MITM-TPROXY-DECRYPT.md)
- **💸 Telemetria de custos em todo o lado** — cabeçalhos de custo/utilização `X-OmniRoute-*` em todos os endpoints, cabeçalho de poupança de acertos de cache e quotas de despesas em USD por chave. → [Referência da API](docs/reference/API_REFERENCE.md)
- **🧠 Memória sob o seu controlo** — desativada por predefinição, quantização vetorial int8 opcional + decaimento tipado, `x-omniroute-no-memory` por pedido. → [Memória](docs/frameworks/MEMORY.md)
- **🛡️ Segurança** — proteção contra injeção de prompts em todas as rotas LLM (conjunto de testes red-team), proteção opcional de mascaramento de credenciais (oculta chaves de API/segredos divulgados em ambas as direções), pesquisa Web gratuita de último recurso através do DuckDuckGo e uma barreira de início de sessão OIDC opcional para o painel (o início de sessão por palavra-passe continua sempre disponível). → [Medidas de proteção](docs/security/GUARDRAILS.md)
- **🖼️ Novos endpoints** — `/v1/ocr` (Mistral OCR) e `/v1/audio/translations` (ao estilo do Whisper) completam a superfície multimédia. → [Referência da API](docs/reference/API_REFERENCE.md)
- **🎨 Geração de imagens / vídeo / áudio** — uma API para multimédia: vídeo xAI Grok Imagine e Novita AI, ComfyUI, Magnific, Adobe Firefly, Segmind e fornecedores de voz como ElevenLabs. → [Referência da API](docs/reference/API_REFERENCE.md)
- **🌍 Implementação e operações** — `basePath` de proxy inverso, deteção automática do idioma do navegador, monitorização de dispositivos por chave, confiança MITM sem root e localização zh-TW. → [Ambiente](docs/reference/ENVIRONMENT.md)
- **🤝 Mais fornecedores e agentes** — agentes na cloud (Codex Cloud, Cursor, Devin, Jules), Grok Build (xAI) com início de sessão por navegador + OAuth, cartão de primeira classe do Ollama, Claude Opus 5 e Sonnet 5, parceria oficial com a Kimi (Code/Web/Moonshot), Zed, Requesty, SenseNova, Yuanbao, Agnes AI… e um catálogo de **388 fornecedores** renovado. → [Fornecedores](docs/reference/PROVIDER_REFERENCE.md)
- **📡 Transparência do roteamento** — cada resposta inclui um cabeçalho `X-OmniRoute-Decision` que indica a estratégia/fornecedor/latência que a serviu; uma nova estratégia de combinação `cache-optimized` + o fator `cacheAffinity` das combinações automáticas encaminha os pedidos repetidos de volta para a ligação que contém o prefixo em cache; e um endpoint apenas de leitura `/v1/auto-combo/{channel}/candidates` expõe o conjunto de candidatos ativos de um canal `auto/*`. → [Combinações automáticas](docs/routing/AUTO-COMBO.md)
- **⚡ Desempenho e infraestrutura locais** — Redis local com um clique, implementadores de relay para Cloudflare Workers / Deno Deploy, Bifrost e Mux como serviços incorporados supervisionados. → [Serviços incorporados](docs/frameworks/EMBEDDED-SERVICES.md)
- **🧩 Também incluído** — framework de plugins + marketplace, frameworks de competências Omni/Agent/GitHub, integração com cofres do Obsidian (22 ferramentas MCP), APIs Batch e Files compatíveis com OpenAI, cache semântico de respostas, gamificação com tabelas de classificação, descoberta de agentes ACP (15 agentes integrados), exportação agendada de registos para o BigQuery, distribuição paralela de múltiplos modelos `auto/chaos`, uma ponte para bots do Telegram, um gestor de versões integrado na aplicação e classificações de fornecedores gratuitos LMArena-ELO. → [Documentação](docs/README.md)
## 🤖 CLIs & Agentes de Programação Compatíveis
> Uma configuração — `http://localhost:20128/v1` — e **todas** as IDEs ou CLIs de IA funcionam com modelos gratuitos e de baixo custo.
＋ também funciona com · Agent Deck · Kiro · Command Code · Antigravity · Windsurf · AMP · qualquer ferramenta compatível com OpenAI
📖 Configuração por ferramenta para todas as 39 ferramentas (28 CLI Code's + 11 CLI Agents) → [`docs/reference/CLI-TOOLS.md`](docs/reference/CLI-TOOLS.md) · 🧩 Plugin OpenCode → [`@omniroute/opencode-provider`](https://www.npmjs.com/package/@omniroute/opencode-provider)
**Lance qualquer CLI suportada através do OmniRoute com um único comando** — sem ficheiros de configuração escritos,
credenciais injetadas por processo, Qwen/Gemini recebem um diretório home isolado temporário:
```bash
omniroute run claude --model openai/gpt-5.4 # Claude Code
omniroute run codex --model glm/glm-5.2 # OpenAI Codex CLI
omniroute run aider --model glm/glm-5.2 -- --message "reply OK"
omniroute run goose --model glm/glm-5.2
omniroute run opencode --model glm/glm-5.2 -- run "reply OK"
omniroute run qwen --model glm/glm-5.2 -- -p "reply OK"
omniroute run gemini --model glm/glm-5.2 -- --skip-trust -p "reply OK"
# Ou escolha o fornecedor+modelo interativamente e escreva a configuração própria da ferramenta:
omniroute configure codex # também: claude opencode qwen aider goose gemini cline continue kilo 5dive
```
Todos os comandos respeitam o contexto remoto ativo (`omniroute connect `), `--dry-run`
mostra uma pré-visualização exata do ambiente/argumentos sem executar, e `--api-key-env NAME` mantém segredos fora
do histórico do seu shell. → [Integrações CLI](docs/guides/CLI-INTEGRATIONS.md)
## 🌐 388 fornecedores de IA — 153 marcados como gratuitos no catálogo
> **388 fornecedores registados** nas coleções canónicas de chat, multimédia, pesquisa, locais, agentes na cloud e sistema, incluindo **153 com metadados de descoberta `hasFree: true`**. O registo de modelos de chat abrange **239 fornecedores / 3 059 pares distintos fornecedor-modelo / 1 475 IDs de modelos brutos**; o catálogo separado de orçamentos gratuitos tem **471 linhas por modelo**, **34 grupos recorrentes** e **52 fornecedores gratuitos para sempre, recorrentes e sem chave**. Estes são denominadores diferentes por conceção; as definições e os cálculos deduplicados por grupo estão disponíveis na [Referência de fornecedores](docs/reference/PROVIDER_REFERENCE.md) e nos [Níveis gratuitos](docs/reference/FREE_TIERS.md).
### 🏢 Todos os grandes laboratórios — através de um único endpoint
OpenAI
Anthropic
Gemini
xAI Grok
DeepSeek
Mistral
Qwen
Meta Llama
Groq
NVIDIA
MiniMax
Cohere
Perplexity
HuggingFace
Together
Fireworks
Cloudflare
Baidu
…e mais de 350 — todos os ícones são obtidos em direto do catálogo de fornecedores do dashboard. 📖 [Referência de fornecedores](docs/reference/PROVIDER_REFERENCE.md)
### 🆓 Gratuito para sempre — 0 €, sem cartão
OpenCode Zen DeepSeek V4, Nemotron 3 Sem limite de tokens
Kilo Code Encaminhador automático, Tencent Hy3 Gratuito para sempre
Requesty GPT-OSS 120B, Nemotron Gratuito para sempre
SiliconFlow DeepSeek V3.2 / R1 Escalão gratuito
Z.AI GLM GLM-4.7 / 4.5-Flash Gratuito para sempre
Baidu ERNIE ERNIE 4.0 Gratuito para sempre
Qoder AI Qwen3-Max, Kimi-K2 GRATUITO ilimitado
Pollinations GPT, Llama, Claude Não é necessária nenhuma chave
Cloudflare AI Mais de 50 modelos 10 mil neurónios/dia
NVIDIA NIM GLM, MiniMax ~40 RPM gratuitos
Cerebras GLM 4.7, GPT-OSS Crédito único de $5; cartão necessário
OpenRouter :free models +$10 → RPM mais elevado
📖 Catálogo completo legível por máquina → [`docs/reference/PROVIDER_REFERENCE.md`](docs/reference/PROVIDER_REFERENCE.md)
## 🖥️ Onde OmniRoute é executado - em qualquer
> A mesma aplicação, a sua máquina, as suas regras. De uma instalação npm global para** O seu telefone** através do Termux.
Plataforma
Instalar
Destaques
📦 npm (global)
npm instalar -g omniroute
Um comando, qualquer OS
⚡ Bun (global)
bun add -g omniroute
Mesmo tarball de registo, instalação mais rápida
🐳 Docker
docker executar … diegosouzapw/omniroute
Multi-arco AMD64 + ARM64
🖥️ Ambiente de trabalho (Electron)
npm executar electrão:construir
Janela nativa bandeja + sistema zqm — Windows / macOS / Linux
🎩 Barra de menu (OmniRouteTray)
brew install --cask zoispag/tap/omniroute-tray
Supervisiona & atualiza automaticamente o servidor — macOS
💪 ARM
nativo arm64
Raspberry Pi, servidores ARM, Apple Silicon
📱 Android (Termux)
pkg instalar nodejs && npx -y omniroute
Executa no seu telefone , 24/7, sem root
📲 PWA
"Adicionar ao ecrã inicial"
Ecrã completo, offline, instalável a partir do browser
🧩 OpenCode plugin
@omniroute/opencode-provider
Integração OpenCode
🤖 VS Código Copilot Chat
instalar OmniCopilot extensão
Cada modelo OmniRoute no seletor de chat Copilot nativo — estável & Insiders
🛠️ Da fonte
npm install && npm run dev
Hackeie, contribua com
[Docker](docs/guides/DOCKER_GUIDE.md)📖 zqc · [Ambiente de trabalho](electron/README.md) · [Bandeja da barra de menus](https://github.com/zoispag/omniroute-tray) · [Termux](docs/guides/TERMUX_GUIDE.md) · [PWA](docs/guides/PWA_GUIDE.md) · [OpenCode](docs/frameworks/OPENCODE.md)
### 🧩 Novo: OmniRoute dentro do chat Copilot nativo do VS Code
> Sem nova barra lateral, sem novo chat UI - cada modelo que OmniRoute serve aparece diretamente no** Seletor de modelo Copilot Chat que já utiliza** . Desde o Código VS 1.122, os modelos de fornecedores funcionam sem login GitHub ou assinatura Copilot – modo de agente, chamada de ferramenta e visão, gratuitamente.
Instale o** [OmniCopilot](https://github.com/diegosouzapw/OmniCopilot)** extensão, aponte-o para o servidor OmniRoute (o predefinido é `localhost:20128`) e abra Copilot Chat → model picker →** Gerir modelos…** →**OmniRoute** .
A partir de dentro do editor: abra o** Extensões** visualizar, pesquisar** "OmniRoute"** , clique** Instalar** — funciona da mesma forma em ambas as lojas. Fonte, problemas e o runbook de publicação ao vivo em [diegosouzapw/OmniCopilot](https://github.com/diegosouzapw/OmniCopilot).
📖 [VS Código Copilot Guia de chat](docs/guides/VSCODE-COPILOT.md) - configuração, o que o selector mostra, painel num separador, resolução de problemas
### 🎩 Novo: OmniRouteTray — o seu gateway, localizado na barra de menus
> `omniroute serve` fica mais feliz quando está sempre ligado.** [OmniRouteTray](https://github.com/zoispag/omniroute-tray)** transforma isto numa aplicação de barra de menu do tipo configure e esqueça para macOS: inicia o servidor, mantém-no ativo durante as reinicializações, atualiza-o e coloca o seu orçamento de token ativo a um clique de distância -** sem janela de terminal aberta, sem `npm install -g omniroute` para tomar conta.**
Construído com [Tauri v2](https://v2.tauri.app/) (um núcleo Rust do tamanho de um erro de arredondamento), vem com o seu próprio tempo de execução Node 24 assinado e gere uma instalação OmniRoute de propriedade da aplicação, para que nunca lute contra o seu `node`/`bun` global. Isto** partilha a sua configuração e base de dados `~/.omniroute/` existente** - então é o mesmo OmniRoute que já conduz, só que de chapéu. 🎩
O que faz
Como
🟢 Supervisiona o servidor
Gera omniroute serve , adopta uma instância já em execução em vez de a duplicar
📊 Visão geral do uso ao vivo
Barras de quota do fornecedor, limites Claude session/weekly com contagem regressiva redefinida, detalhe de custos em 30 dias
🔄 Atualizações automáticas em vigor
Instalação por fases, troca atómica, reversão em caso de falha — sempre na versão mais recente
🚀 Iniciar no login
Lançamento opcional no login; apenas bandeja, sem ícone de encaixe
🩺 Doctor & logs
Diagnóstico com um clique e acesso ao log do servidor
```sh
brew install --cask zoispag/tap/omniroute-tray
```
Prefere um download? Obtenha o .dmg mais recente em
Liberta . Fonte, problemas e construção
documentos ao vivo em zoispag/omniroute-tray.
💛 Um projeto comunitário de @zoispag — não é um lançamento oficial OmniRoute.
> Para além do servidor, o OmniRoute é um **cockpit completo de linha de comandos** com **mais de 80 comandos**, além de protocolos de agentes abertos para que um agente de IA o possa controlar **de forma autónoma**.
### ⌨️ Uma CLI a sério (não apenas `start`)
```bash
omniroute # inicia o gateway + painel (porta 20128)
omniroute chat # cliente de chat TUI interativo (atalhos: /model /combo /skill /memory)
omniroute setup # assistente guiado de primeira execução
omniroute doctor # diagnostica fornecedores, portas e dependências nativas
```
### 🛰️ Modo remoto — execute a CLI aqui e o OmniRoute num VPS
Tem o OmniRoute num servidor? Controle-o a partir do seu portátil com a **mesma CLI**. Inicie sessão uma vez
com um token de acesso com âmbito definido; a partir daí, todos os comandos têm como destino o servidor remoto.
```bash
omniroute connect 192.168.0.15 # palavra-passe → token com âmbito definido, guardado como contexto
omniroute models # ← executado no servidor REMOTO
omniroute configure codex # ← escolhe um modelo remoto e cria um perfil Codex local
omniroute tokens create --name ci --scope read # emite tokens mais restritos para outras máquinas
omniroute contexts use default # ← volta ao servidor local
```
Os tokens têm os âmbitos `read` / `write` / `admin`; as rotas que iniciam processos continuam limitadas ao loopback.
📖 [Modo Remoto](docs/guides/REMOTE-MODE.md)
### 🤝 Ligue um agente — e este controla o próprio OmniRoute
Exponha o OmniRoute através de **MCP**, **A2A**, uma **API REST**, **webhooks** ou uma **CLI remota** — qualquer agente compatível (ou o seu próprio código) obtém acesso a todo o gateway: encaminhamento, fornecedores, combinações, cache, compressão e memória — de forma autónoma. Os endpoints HTTP abaixo são disponibilizados em `http://localhost:20128`.
Interface
Endpoint / comando
Utilização
🧰 MCP (stdio)
omniroute --mcp
Integração com o Claude Desktop, Cursor ou qualquer cliente MCP
Agente para agente, JSON-RPC 2.0 + SSE, 6 competências
🌐 API REST
/v1/*
Compatível com OpenAI — chat, embeddings, imagens, áudio e OCR
🔔 Webhooks
/api/webhooks
Envio de eventos de pedidos / quotas para o Slack, Discord, Telegram ou qualquer URL
🛰️ CLI remota
omniroute connect
Controle uma instância remota com tokens de acesso com âmbito definido
```bash
# Dê ao Claude Code o conjunto completo de ferramentas do OmniRoute através de MCP:
claude mcp add-server omniroute --type http --url http://localhost:20128/api/mcp/stream
```
📖 [Servidor MCP](docs/frameworks/MCP-SERVER.md) · [Servidor A2A](docs/frameworks/A2A-SERVER.md) · [Protocolos de Agentes](docs/frameworks/AGENT_PROTOCOLS_GUIDE.md)
## 🗜️ Poupe 15–95% de tokens — automaticamente
### 📖 Como funciona — pipeline, arquitetura e cálculo da poupança
A combinação empilhada predefinida executa `RTK → Caveman`. Quando ambos atuam sobre o mesmo payload de ferramenta/contexto, as poupanças acumulam-se:
```txt
combined = 1 − (1 − RTK) × (1 − Caveman_input)
average = 1 − (1 − 0.80) × (1 − 0.46) = 89.2%
range = 78.4 – 94.6%
```
Os blocos de código, URLs, JSON e dados estruturados estão **sempre protegidos** pelo motor de preservação.
> **Porquê usar muitos tokens quando poucos tokens são suficientes?** Cada pedido passa pelo pipeline de compressão do OmniRoute **de forma transparente** — sem alterações no cliente. É agora uma **pilha de 12 motores combináveis** que são executados por ordem e podem ser combinados por combinação de encaminhamento — com base nas ideias de [RTK](https://github.com/rtk-ai/rtk), [Caveman](https://github.com/JuliusBrussee/caveman) (⭐ 90K+), [LLMLingua-2](https://github.com/microsoft/LLMLingua) e [Troglodita](https://github.com/leninejunior/troglodita) (PT-BR).
### 🧱 A pilha de 12 motores
Os motores são executados pela ordem do pipeline; cada um pode ser ativado ou desativado e configurado de forma independente por combinação:
#
Motor
O que faz
1
Session-Dedup
Remove conteúdo repetido entre turnos (endereçado pelo conteúdo, entre turnos)
2
CCR
Arquiva grandes blocos atrás de marcadores de recuperação, obtidos quando necessário
3
Lite
Redução de espaços em branco + URLs de imagens (baseline com baixa latência)
4
RTK
Filtragem inteligente, eliminação de duplicados e truncagem de resultados de ferramentas (com conhecimento de comandos)
5
Responses Tool Output
JSON com prioridade à ausência de perdas + compressão de diagnóstico limitada para resultados de shell/patch/pesquisa/build (Responses API)
6
Headroom
Compactação sem perdas de matrizes JSON tabulares (~30%) através de um codec GCF incluído no fornecedor
7
Relevance
Pontuação extrativa de frases com base na última consulta do utilizador
8
Caveman
Compressão de prosa baseada em regras (~65–75% no resultado)
9
Aggressive
Sumarização + envelhecimento progressivo de turnos antigos
10
LLMLingua-2
Poda semântica baseada em ML através de MobileBERT ONNX — segura para código, assíncrona
11
Ultra
Poda heurística de tokens com um nível opcional de modelo pequeno (SLM)
12
OmniGlyph
Codificação experimental do contexto como imagem para Claude Fable 5 medida na ligação direta da Anthropic; os transformadores GPT 5.6 permanecem em modo fail-closed enquanto se aguardam comprovativos do fornecedor. Quatro perfis de compressão (agressivo por predefinição, equilibrado, seguro para código, passthrough) (mais agressivo; ativação opcional)
Os blocos de código, URLs e dados estruturados são **sempre preservados** byte a byte. As **predefinições de um clique** combinam os motores:
Modo
Poupança
Mais adequado para
🪶 Lite
~15%
Predefinição segura sempre ativa
🪨 Standard (Caveman)
~30%
Programação diária
⚡ Aggressive
~50%
Sessões longas com muitas ferramentas
🔥 Ultra
~75%
Poupança máxima
🧰 RTK
60–90%
Resultados de shell/test/build/git
🔗 Stacked (RTK → Caveman)
78–95%
Pedidos mistos + registos de ferramentas
**Exemplo real — modo Standard:**
> **Antes (69 tokens):** _"A razão pela qual o seu componente React está a ser renderizado novamente é provavelmente o facto de estar a criar uma nova referência de objeto em cada ciclo de renderização. Quando passa um objeto inline como prop, a comparação superficial do React vê-o como um objeto diferente de cada vez, o que desencadeia uma nova renderização. Recomendo usar useMemo para memorizar o objeto."_
>
> **Depois (19 tokens):** _"Nova referência de objeto em cada renderização. Prop de objeto inline = nova referência = nova renderização. Envolva em useMemo."_
>
> **A mesma resposta. 72% menos tokens. Zero perda de precisão.** ✅
**Exemplo PT-BR — modo [Troglodita](https://github.com/leninejunior/troglodita):**
> **Antes (42 tokens):** _"O problema é que o componente está re-renderizando porque uma nova referência de objeto está sendo criada em cada ciclo de renderização. Eu recomendaria usar useMemo."_
>
> **Depois (12 tokens):** _"Re-render: ref nova cada ciclo (objeto inline recriado). Usar `useMemo`."_
>
> **Mesma resposta. ~70% menos tokens. Precisão técnica intacta.** ✅
### 🎚️ Além dos motores — estilos de saída, o seletor adaptativo e controlo por pedido
Os 12 motores acima reduzem o que **entra**. Três camadas adicionais determinam **como**, **quando** e o que **sai**:
- **🪄 Estilos de saída** _(orientação do eixo de saída)_ — injetam instruções determinísticas e seguras para a cache, que moldam a resposta; podem ser combinados, cada um com intensidade `lite` / `full` / `ultra`. Adicionar um estilo requer uma entrada de uma linha no registo:
- **Prosa concisa** — eliminar texto supérfluo / artigos / ressalvas; manter o conteúdo técnico exato.
- **Menos código** — YAGNI de "programador sénior preguiçoso": a alteração funcional mais pequena, sem estrutura adicional não solicitada.
- **Rabo de cavalo (programador sénior preguiçoso)** — subir na escala YAGNI, corrigir a causa principal, aplicar o diff funcional mais pequeno.
- **Tenho TDAH (primeiro a ação)** — a próxima ação vem primeiro, passos numerados, um passo seguinte concreto, sem preâmbulo.
- **CJK conciso (文言)** — estilo ultraconciso do chinês clássico (limitado ao locale `zh`).
- **🎯 Orçamento de contexto adaptativo** _(o seletor)_ — em vez de um único limiar de tokens ligado/desligado, escalar os motores mais baratos e com menores perdas apenas até ser suficiente para **caber na janela de contexto do modelo**. Política: `reserve-output` (predefinição, com conhecimento do modelo) · `percentage` · `absolute`. Modo: `floor` (garantir que cabe) · `replace-autotrigger` (a sua escolha explícita prevalece) · `off` (limiar legado).
- **🎛️ Onde a compressão é decidida** _(precedência, da mais alta → à mais baixa)_ — cabeçalho `x-omniroute-compression` por pedido › substituição da combinação de encaminhamento › perfil nomeado ativo › acionamento adaptativo / automático › predefinição do painel › desativado. O plano aplicado é devolvido no cabeçalho de resposta `X-OmniRoute-Compression: ; source=`.
Acione automaticamente por limiar de tokens, ative o seletor adaptativo, fixe um perfil nomeado, defina uma configuração única por pedido ou atribua um pipeline a cada combinação de encaminhamento — escolha o que melhor se adequar à carga de trabalho. Um **arnês de avaliação** offline opcional (`npm run eval:compression`) calcula a fidelidade face às poupanças num corpus fixo antes de promover uma alteração.
📖 [`COMPRESSION_GUIDE.md`](docs/compression/COMPRESSION_GUIDE.md) · [`RTK_COMPRESSION.md`](docs/compression/RTK_COMPRESSION.md) · [`COMPRESSION_ENGINES.md`](docs/compression/COMPRESSION_ENGINES.md)
# ⚡ Início rápido
**1) Instalar e executar**
```bash
npm install -g omniroute
omniroute
```
> 💡 Consulte `npm warn ERESOLVE` ou avisos de dependências peer? [São inofensivos](docs/guides/TROUBLESHOOTING.md#npm-install-warnings-eresolve--peer--deprecated).
> **Está a usar npm 11 ou posterior?** O npm pode bloquear os scripts do ciclo de vida dos pacotes, a menos que sejam autorizados. O `postinstall` do OmniRoute (`node scripts/build/postinstall.mjs`) é necessário para preparar os ficheiros nativos do runtime. Autorize os pacotes indicados no aviso do npm ao instalar globalmente. Para o conjunto de pacotes comunicado pelo OmniRoute 3.8.54:
>
> ```bash
> npm install -g --allow-scripts=omniroute,keytar,onnxruntime-node,@parcel/watcher,@swc/core,protobufjs,esbuild omniroute
> ```
>
> Para reutilizar esta lista de permissões em futuras instalações globais, configure-a uma vez e instale normalmente:
>
> ```bash
> npm config set allow-scripts=omniroute,keytar,onnxruntime-node,@parcel/watcher,@swc/core,protobufjs,esbuild --location=user
> npm install -g omniroute
> ```
>
> A lista de dependências pode mudar entre versões; se o npm comunicar uma lista diferente, utilize os nomes dos pacotes presentes nesse aviso. Autorizar um pacote permite a execução dos respetivos scripts de instalação.
> **Está a usar o Gemini Web ou outro fornecedor baseado em cookies da Web?** O pacote npm inclui
> o Playwright, mas não o respetivo binário Chromium. Consulte a nota sobre a
> [configuração do Chromium do Playwright](docs/guides/TROUBLESHOOTING.md#gemini-web-and-playwright-chromium)
> antes de efetuar o primeiro pedido ao fornecedor Web.
Painel em `http://localhost:20128` · API em `http://localhost:20128/v1`.
**2) Ligar um fornecedor elegível utilizando a sua própria conta**
Painel → **Fornecedores** → escolha um fornecedor cujos termos e quota atuais sejam adequados ao seu caso de utilização → adicione a respetiva chave de API ou conclua o fluxo da conta. Os níveis gratuitos podem exigir registo, aprovação ou um método de pagamento. Consulte o [Guia dos níveis gratuitos](docs/getting-started/FREE-TIERS-GUIDE.md); a disponibilidade sem chave não é garantida e os fornecedores marcados com `tos: avoid` são excluídos de `auto` por predefinição.
**3) Configurar a sua ferramenta de programação**
```txt
Base URL: http://localhost:20128/v1
API Key: [copy from Dashboard → Endpoints]
Model: auto (routes among eligible connections — or choose provider/model)
```
**4) Verificar se está a funcionar**
```bash
curl http://localhost:20128/v1/models -H "Authorization: Bearer YOUR_KEY"
```
Deverá ver os seus modelos ligados na lista. 🎉 É tudo — comece a programar e o OmniRoute encaminhará e fará o fallback automaticamente por si.
Se o seu cliente não conseguir enviar cabeçalhos personalizados, o OmniRoute também disponibiliza aliases de compatibilidade tokenizados:
```txt
OpenAI catalog: http://localhost:20128/vscode/YOUR_KEY/
OpenAI models: http://localhost:20128/vscode/YOUR_KEY/models
OpenAI chat: http://localhost:20128/vscode/YOUR_KEY/chat/completions
OpenAI responses: http://localhost:20128/vscode/YOUR_KEY/responses
Ollama chat: http://localhost:20128/vscode/YOUR_KEY/api/chat
Ollama tags: http://localhost:20128/vscode/YOUR_KEY/api/tags
```
Utilize estes aliases apenas com clientes que não conseguem anexar `Authorization: Bearer ...`. A autenticação por cabeçalho continua a ser o modo preferencial.
## 📦 Mais métodos de instalação — Docker, código-fonte, pnpm, Arch
**🐳 Docker**
```bash
docker run -d --name omniroute --restart unless-stopped --stop-timeout 40 \
-p 127.0.0.1:20128:20128 -v omniroute-data:/app/data diegosouzapw/omniroute:latest
```
`:latest` acompanha a versão SemVer estável **publicada** mais elevada. Não acompanha o `main` do git. Fixe `:X.Y.Z` para GitOps. Consulte [Canais de lançamento do Docker](docs/guides/DOCKER_GUIDE.md#release-channels). A imagem fixa **`OMNIROUTE_MEMORY_MB=1024`**. Isto é suficiente para o painel e uma conversa ligeira. Os **agentes de programação** (`POST /v1/responses` do Claude Code, Codex, Grok, …) necessitam de uma heap V8 muito maior, caso contrário o processo termina com `FATAL ERROR` quando atinge ~12 GiB com dois contextos longos sobrepostos. Dimensione o contentor acima do tamanho da heap (os buffers nativos ficam fora do V8):
| Carga de trabalho | Heap (`-e OMNIROUTE_MEMORY_MB`) | Contentor (`--memory`) |
| ----------------------------------------- | ------------------------------- | ---------------------- |
| Painel / conversa ligeira | `1024` (predefinição da imagem) | ≥2 g |
| Um agente de programação | `8192` | ≥10 g |
| Dois `/v1/responses` longos em simultâneo | `10240`–`12288` | ≥12–16 g |
```bash
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
```
Tabela completa: [Guia do Docker — RAM em tempo de execução](docs/guides/DOCKER_GUIDE.md#runtime-ram-for-coding-agents).
> **Canal de pré-lançamento do Docker:** `diegosouzapw/omniroute:next` e
> `diegosouzapw/omniroute:next-web` acompanham o branch `release/v*` predefinido
> atual. Estas etiquetas mutáveis destinam-se apenas a testar correções ainda não lançadas e
> **não são suportadas em produção**. Consulte
> [Canais de lançamento do Docker](docs/guides/DOCKER_GUIDE.md#release-channels).
**🥟 Bun**
O `bun install` padrão e a instalação global (`bun install -g omniroute`) são suportados através da deteção do ambiente de execução Bun:
- **`bun:sqlite` integrado**: o OmniRoute utiliza o controlador `bun:sqlite` integrado do Bun quando é executado no Bun, recorrendo ao `better-sqlite3` no Node.js ou ao `sql.js` como alternativas.
- **Seleção automática do empacotador Webpack em desenvolvimento**: o ambiente de desenvolvimento (`bun run dev`) deteta automaticamente o Bun e desativa o Turbopack em favor do Webpack, para evitar incompatibilidades com bindings nativos do V8. As compilações de produção (`bun run build`) seguem `OMNIROUTE_USE_TURBOPACK` exatamente como no Node: Turbopack por predefinição, `OMNIROUTE_USE_TURBOPACK=0` para compilar com Webpack (`Dockerfile.bun` disponibiliza esta opção como `--build-arg`).
- **Dockerfile dedicado ao Bun**: `Dockerfile.bun` multifase para implementações de produção nativas do Bun (`docker build -f Dockerfile.bun -t omniroute:bun .`).
```bash
# Instalar e executar com o Bun
bun install
bun run dev
```
**🛠️ A partir do código-fonte**
```bash
cp .env.example .env && npm install
PORT=20128 npm run dev
```
**📦 pnpm**
```bash
pnpm add -g omniroute@latest --allow-build=better-sqlite3 --allow-build=@swc/core && omniroute
```
**🐧 Arch Linux (AUR)**
```bash
yay -S omniroute-bin && systemctl --user enable --now omniroute.service
```
**🔧 Nix (Flake)**
```bash
# Utilizar flakes do Nix
nix develop
npm run dev
# Ou utilizar o devbox
devbox run npm run dev
```
📖 [Guia do Docker](docs/guides/DOCKER_GUIDE.md) — perfis do Compose, Caddy HTTPS e túneis do Cloudflare.
**🦭 Podman**
```bash
# 1. Preparar o diretório de dados montado por bind
mkdir -p data
# 2. Apenas Linux + Podman rootless local (nunca um cliente remoto Podman Machine):
podman unshare chown 1000:1000 ./data
# 3. Definir a indicação do ambiente de execução, criar a imagem local do Compose e iniciar
echo "CONTAINER_HOST=podman" >> .env
podman compose --profile base up -d --build
```
No macOS ou Windows, o Podman utiliza uma Podman Machine remota: ignore `podman unshare` e
siga as [orientações para o diretório de dados específicas da topologia](contrib/podman/README.md#data-directory-permissions-by-topology).
📖 [Guia do Podman](contrib/podman/README.md) — compilações do Compose, Podman Machine e
configuração do Quadlet com Linux/systemd.
**⚡ Instalação mais rápida / leve (ignorar a compilação nativa)**
O motor SQLite nativo (`better-sqlite3`) é uma dependência **opcional**, pelo que uma instalação
global nunca fica bloqueada a compilar a partir do código-fonte: utiliza um binário pré-compilado quando existe um compatível
com a sua plataforma/Node e, caso contrário, recorre de forma transparente a um motor JavaScript puro
(`node:sqlite` no Node 22+, ou o WASM `sql.js` incluído) — sem necessidade de ferramentas de compilação.
Para ignorar completamente a preparação nativa pós-instalação (CI, sistemas sem interface gráfica ou máquinas lentas):
```bash
OMNIROUTE_SKIP_POSTINSTALL=1 npm install -g omniroute # CI=1 também a ignora
```
Para instalações mais rápidas, prefira o **pnpm** (armazenamento endereçado por conteúdo + hard links — consulte acima).
Para um ambiente de execução sem painel nem interface gráfica, utilize o perfil `base` do Docker (acima) ou o
[guia do Termux](docs/guides/TERMUX_GUIDE.md). A CLI e o painel Web são disponibilizados pelo
mesmo processo numa única porta, pelo que atualmente não existe um pacote separado apenas para a CLI.
OAuth 2.0 (PKCE) + JWT + chaves de API + autenticação MCP com escopo · AES-256-GCM em repouso · DOMPurify
Camuflagem
wreq-js — personificação de impressões digitais TLS JA3 / JA4, proxy de 3 níveis
Resiliência
Disjuntor, backoff exponencial, prevenção de efeito rebanho, autorrecuperação auto-combo
Registo
pino — registos JSON estruturados com contexto do pedido
Testes
Executor de testes do Node.js + Vitest — mais de 60 000 declarações de testes estáticos em mais de 8 400 ficheiros de testes monitorizados (unitários, integração, E2E, segurança, ecossistema)
Estratégia de cobertura de testes para mais de 60 000 declarações de testes estáticos em mais de 8 400 ficheiros de testes monitorizados
# ⭐ Principais contribuidores
> O OmniRoute é moldado por uma comunidade apaixonada de código aberto. Estas pessoas deram contribuições excecionais que têm um impacto direto na qualidade, estabilidade e alcance do projeto. **Obrigado.**
### Contribuidores externos por pedidos de pull integrados
Censo realizado em 2026-11-03 03:01:19 UTC com a versão ativa de release/v3.8.5305bc048d6c. O censo paginado do GitHub GraphQL contém 9 947 PRs integrados: 4 130 pelo proprietário do repositório, 240 pelo Dependabot, 6 por outros bots/aplicações e 5 571 PRs externos de 883 contribuidores distintos. “Linhas alteradas” corresponde às adições + eliminações do GitHub e inclui ficheiros gerados, ficheiros de bloqueio, catálogos, traduções e documentação; representa alterações, não LOC da autoria. 53 PRs apresentam diferenças do GitHub superiores a 500 000 linhas (por exemplo, o #13399, uma única adição de fornecedor, lista 2 347 ficheiros alterados), o que aumenta vários totais acima. As classificações empatadas são apresentadas em conjunto.
### Commits atribuídos ao GitHub
Verificado novamente em 2026-11-03 02:09:16 UTC: commits atribuídos pelo GitHub, comunicados pela API de Contribuidores do repositório para o branch predefinido release/v3.8.53. A API devolveu 903 identidades (429 utilizadores, 2 bots, 472 anónimos); esta tabela exclui o responsável pela manutenção, os bots e as identidades anónimas, e mantém os empates. É distinta tanto da classificação de PRs integrados acima como do recenseamento de metadados do Git abaixo.
> 🙏 As funcionalidades, correções de erros e melhorias da infraestrutura destes contribuidores são uma **parte essencial** do que torna o OmniRoute fiável e rico em funcionalidades. Cada pull request, cada caso de teste e cada ficheiro de tradução i18n são importantes. O código aberto é criado por pessoas como eles.
---
## 💖 Patrocinadores
Um agradecimento sincero às pessoas que financiam o OmniRoute do seu próprio bolso — cada contribuição mantém o projeto gratuito, independente e em evolução.
… e outras pessoas que preferem manter-se anónimas 💛Os Patrocinadores públicos do GitHub foram revalidados em 2026-10-18 através da API GraphQL do GitHub Sponsors: 11 patrocínios públicos (6 ativos, 5 anteriores) de um total de 14. O estado isActive do GitHub determina as etiquetas de atividade acima; os antigos apoiantes públicos pontuais continuam a ser agradecidos e os patrocinadores privados permanecem anónimos. As doações através do Ko-fi, Buy Me a Coffee, Liberapay, PIX e criptomoedas não estão listadas porque não têm um registo público de patrocinador.💖 Torne-se patrocinador → — cada dólar mantém o OmniRoute gratuito e independente.
## 👥 Mais de 1.000 contribuidores
[](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)
Auditado em 2026-11-02 no tip ativo release/v3.8.531c7135e0fb (7 972 commits): 1 074 identidades Git humanas normalizadas — 759 aparecem como autores de commits (incluindo o responsável pela manutenção) e 315 apenas em trailers explícitos Co-authored-by. O recenseamento aplica .mailmap, compara endereços de e-mail sem distinção entre maiúsculas e minúsculas, associa endereços GitHub noreply numéricos e simples apenas quando codificam o mesmo identificador, exclui 29 identidades de bots/agentes/serviços/placeholders e não associa endereços de e-mail comuns apenas porque os respetivos nomes apresentados coincidem. A auditoria de 2026-08-24 publicou 639; a repetição deste método na base ac02c5b42f dessa auditoria dá 619, pelo que o aumento resulta de novos contribuidores, não de um método menos rigoroso.
### Como contribuir
1. Faça um fork do repositório
2. Crie um branch a partir do tip `release/vX.Y.Z` **ativo** (não de `main`) — consulte [Modelo de Branching e Releases](docs/ops/BRANCHING_MODEL.md)
3. Crie o seu branch de funcionalidade (`git checkout -b feat/amazing-feature`)
4. Faça commit das suas alterações (`git commit -m 'feat: add amazing feature'`)
5. Envie para o branch (`git push origin feat/amazing-feature`)
6. Abra um Pull Request com a **base = esse branch `release/vX.Y.Z`**
Consulte [CONTRIBUTING.md](CONTRIBUTING.md) para obter orientações detalhadas.
### Lançar uma nova versão
```bash
# Criar uma release — a publicação no npm acontece automaticamente
VERSION=x.y.z
gh release create "v${VERSION}" --title "v${VERSION}" --generate-notes
```
## 📊 Estrelas
## 🌍 StarMapper
## 🙏 Agradecimentos
O OmniRoute assenta nos ombros de gigantes. Começou como um fork do **[9router](https://github.com/decolua/9router)** e uma portabilidade para TypeScript do projeto Go **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** — e, a partir daí, cada subsistema abaixo foi inspirado por um projeto de código aberto que chegou primeiro. Cada um moldou uma parte concreta do OmniRoute. Este é o nosso agradecimento a todos eles. 🙏
> ⭐ contagens de estrelas verificadas a partir da API REST do GitHub em 3 de novembro de 2026 — vá dar uma estrela a estes projetos. As contagens são um instantâneo exato datado e irão naturalmente mudar.
### 🧬 Linhagem e gateway
O gateway de IA cujo conjunto de dados público de preços alimenta a nossa sincronização de acompanhamento de custos e cujo modelo de normalização de fornecedores orientou o nosso encaminhamento.
Fonte MIT adaptada para a ponte incluída ChatGPT Web → Codex Responses, incluindo adaptadores de sessão do navegador, enquadramento de respostas, utilização e pesquisa na Web.
Padrões portados para recuperação de streams, aliases sem pensamento, pesquisa na Web alternativa, limites de janela deslizante, redação de registos e fluxos de inicialização reforçados.
Predefinições de transformação compatíveis com Claude Code e comportamento dos cabeçalhos de faturação generalizados na ponte orientada por configuração do OmniRoute.
Os seus mapeamentos de modelos Grok, gerador Statsig de fake-TypeError, predefinições de pedidos e dispositivos e processador de respostas NDJSON foram adaptados de forma substancial para o executor Grok Web do OmniRoute.
A principal fonte de código transitiva por detrás de grok2api-merged; as suas implementações de modelos, cabeçalhos, payloads, Statsig e processadores são preservadas na linhagem do Grok Web.
A fonte MIT subjacente para as predefinições de payload e dispositivos do Grok, o gerador Statsig e o processador result.response transmitido através de TQZHR e grok2api-merged.
Uma fonte transitiva creditada por grok2api-merged pela sua camada de conjunto de proxies; o OmniRoute preserva essa nota de linhagem, mas não reivindica uma portabilidade do conjunto de proxies no seu executor Grok Web delimitado.
A implementação original do Grok Web foi consultada relativamente ao seu design HTTP/browser upstream; o seu caminho HTTP direto deriva do GrokProxy, pelo que não é reivindicada qualquer portabilidade de código independente.
O projeto viral "why use many token when few token do trick" — a sua filosofia de linguagem de homem das cavernas alimenta o nosso modo de compressão padrão e mais de 30 regras de preenchimento/condensação.
Compressão de saída de comandos de alto desempenho — inspirou o nosso motor RTK, a DSL de filtragem JSON, a recuperação de saída em bruto e o pipeline RTK → Caveman empilhado.
Investigação sobre compressão de prompts (LLMLingua / LLMLingua-2) — inspirou o nosso motor llmlingua assíncrono, seguro para código e com falha aberta.
Compressão de tokens PT-BR — alimenta o nosso pacote linguístico pt-BR: redução de pleonasmos e remoção de palavras de preenchimento ajustadas à gramática do português do Brasil.
A competência YAGNI de programação do "programador sénior preguiçoso" viral — inspirou o nosso estilo de saída less-code: orientação para a alteração funcional mais pequena, que reduz o código _gerado_ (o equivalente no eixo da saída à prosa concisa do Caveman).
O seu formato compacto de grafos e o design de perfil genérico contribuíram para a compactação tabular do OmniRoute e para o formato de codec do Headroom.
Compressão de saída sensível ao conteúdo e por tipo de ficheiro, com abandono consciente de falhas — validou o nosso encaminhamento por tipo e a omissão quando o ganho mínimo não é atingido.
"Encontrar os tokens fantasma" — o seu padrão de transferência externa + identificador recuperável contribuiu para a nossa abordagem à transferência CCR.
JSON colunar em Rust + recuperação endereçada por conteúdo + deduplicação entre mensagens — validou o design dos nossos motores headroom/ccr/session-dedup e o invariante estável em cache de que a "forma comprimida é independente da posição".
Kit de ferramentas da API do compilador TypeScript — inspirou a nossa remoção de comentários baseada em analisadores, que preserva literais de strings, templates e expressões regulares.
A interceção/análise MITM do tráfego entre assistentes de programação e LLM informou os requisitos iniciais do Traffic Inspector. Quatro módulos anteriormente derivados — fusão de SSE, normalização de conversas, ocultação de segredos e sanitização de cabeçalhos — foram substituídos por implementações independentes, desenvolvidas num ambiente limpo com base em normas de protocolo públicas. As duas superfícies de passagem direta de anfitrião (passthrough.ts e _internal/bypass.cjs) continuam a ser implementações internas do OmniRoute, classificadas de forma independente; não foram reescritas como parte dessa substituição.
Encaminhamento de proxy transparente por processo — inspirou a desmontagem MITM segura contra falhas, os tempos limite de inatividade dos sockets, a atribuição de processos através de /proc e a captura TPROXY.
Observabilidade de service mesh do Istio — inspirou os nossos indicadores de circuit breaker e os elementos visuais das arestas de erro no Routing/Combo Studio.
Uma lista selecionada de bibliotecas seguras por predefinição que orienta as nossas escolhas de segurança (Helmet.js, DOMPurify, ssrf-req-filter, safe-regex, Google Tink).
Inspirou a desduplicação de pedidos, o fallback de emergência sem custos, as estratégias Auto-Combo ligáveis e a classificação multilingue de intenções.
O seu remapeamento de modelos com conhecimento das contas, a validação de caminhos de executáveis e o comportamento das etiquetas de planos informaram o runtime Antigravity do OmniRoute.
O seu formato compacto de contagem decrescente para a reposição de quotas inspirou a apresentação correspondente dos limites do fornecedor no OmniRoute.
Identificou a superfície de quotas do Grok Build; o OmniRoute verificou e corrigiu posteriormente o formato wire ativo de forma independente.
## 📄 Licença
Licença MIT - consulte [LICENSE](LICENSE) para obter mais detalhes.
---
**[⬆ Voltar ao topo](#-omniroute)** · Criado com ❤️ para a comunidade de IA de código aberto.
Criado por Diego Souza · OmniRoute v3.8.54 · Node ≥22.22.2 · Licença MIT · omniroute.online
> Resumo animado da página `/dashboard/free-tiers` em tempo real. Metodologia completa (deduplicação de pools, níveis de créditos, termos dos fornecedores): **[docs/reference/FREE_TIERS.md](docs/reference/FREE_TIERS.md)**.
>
> Estes valores são reavaliados de duas em duas semanas com base no catálogo em tempo real e **podem variar em ambas as direções** — um fornecedor termina um free tier e o número diminui; surge um novo e aumenta. Publicamos o que o catálogo calcula efetivamente, nunca um cenário otimista arredondado por excesso.
```bash
# Depois de ligar um fornecedor, copie a sua chave do OmniRoute a partir de Painel → Endpoints:
curl http://localhost:20128/v1/chat/completions \
-H "Authorization: Bearer YOUR_OMNIROUTE_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"auto","messages":[{"role":"user","content":"Hello!"}]}'
```
`auto` necessita de uma rota elegível. Uma instalação recente pode não ter destinos elegíveis sem chave, e um fornecedor sem chave pode rejeitar clientes de terceiros. Os fornecedores marcados como `tos: avoid`, incluindo o Kiro, são excluídos do encaminhamento automático por predefinição; ligar uma conta não substitui essa definição. Consulte o [Guia dos Escalões Gratuitos](docs/getting-started/FREE-TIERS-GUIDE.md) antes de escolher um fornecedor.
📦 Scripts de início rápido prontos a copiar e colar para **Python, Node.js, PHP e cURL** → [`examples/quickstart/`](examples/quickstart/)
> Um **combo** é uma cadeia de modelos entre os quais o OmniRoute encaminha pedidos **automaticamente**. Se a quota se esgotar, um fornecedor falhar ou os custos dispararem, o combo pode avançar para o modelo elegível e operacional seguinte. 🛡️
### ⚡ Sem configuração — basta usar `auto`
Não é necessário criar nenhum combo. Defina o seu modelo como `auto` (ou uma variante) e o OmniRoute cria um combo virtual a partir dos fornecedores ligados, avaliados em tempo real:
📖 [Motor Auto-Combo](docs/routing/AUTO-COMBO.md) · [Guia de Resiliência](docs/architecture/RESILIENCE_GUIDE.md)
📊 Metodologia completa e detalhes por funcionalidade face ao 9router, OpenRouter, CLIProxyAPI e LiteLLM → [`docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md`](docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md)
Chave (aleatória): `5d865059-bc44-483a-962d-43ceb80126eb`
Pix para copiar e colar:
```
00020101021126580014br.gov.bcb.pix01365d865059-bc44-483a-962d-43ceb80126eb5204000053039865802BR5922OMNIROUTE CONTRIBUICAO6006BRASIL62070503***630475DD
```
📖 [Autorização](docs/architecture/AUTHZ_GUIDE.md) · [Proteções](docs/security/GUARDRAILS.md) · [Conformidade](docs/security/COMPLIANCE.md)
A combinação empilhada predefinida executa `RTK → Caveman`. Quando ambos atuam sobre o mesmo payload de ferramenta/contexto, as poupanças acumulam-se:
```txt
combined = 1 − (1 − RTK) × (1 − Caveman_input)
average = 1 − (1 − 0.80) × (1 − 0.46) = 89.2%
range = 78.4 – 94.6%
```
Os blocos de código, URLs, JSON e dados estruturados estão **sempre protegidos** pelo motor de preservação.
> **Porquê usar muitos tokens quando poucos tokens são suficientes?** Cada pedido passa pelo pipeline de compressão do OmniRoute **de forma transparente** — sem alterações no cliente. É agora uma **pilha de 12 motores combináveis** que são executados por ordem e podem ser combinados por combinação de encaminhamento — com base nas ideias de [RTK](https://github.com/rtk-ai/rtk), [Caveman](https://github.com/JuliusBrussee/caveman) (⭐ 90K+), [LLMLingua-2](https://github.com/microsoft/LLMLingua) e [Troglodita](https://github.com/leninejunior/troglodita) (PT-BR).
### 🧱 A pilha de 12 motores
Os motores são executados pela ordem do pipeline; cada um pode ser ativado ou desativado e configurado de forma independente por combinação:
