# 🚀 OmniRoute — O gateway de IA gratuito
**Criado por [Diego Souza](https://github.com/diegosouzapw)**
## 💰 ~1,62B de tokens / mês em níveis gratuitos de terceiros
> **Use suas próprias contas de provedores.** Este é um agregado estimado entre níveis gratuitos de terceiros elegíveis separadamente, não uma concessão de tokens da OmniRoute. Cadastre-se, obtenha as credenciais quando necessário e conecte os provedores que você puder usar; cada provedor controla seus limites, disponibilidade e termos.
>
> Acumular níveis gratuitos manualmente é trabalhoso — dezenas de SDKs, dezenas de limites de taxa e nenhuma ideia de quanto você realmente tem. A OmniRoute cataloga **465 entradas de nível gratuito em 34 chaves de pool recorrentes** e calcula o destaque de tokens a partir dos **17 pools com um orçamento mensal positivo publicado, além de cinco limites do Groq por modelo**, deduplicados por pool compartilhado. As cotas que só são liberadas após uma verificação de identidade regional (atualmente: ModelScope) são mostradas separadamente, +~6M após a verificação de identidade regional, e nunca são somadas ao destaque. O resultado permanece visível no painel (`/dashboard/free-tiers`).
> Resumo animado da página `/dashboard/free-tiers` ao vivo. Metodologia completa (deduplicação de pools, níveis de crédito, termos dos provedores): **[docs/reference/FREE_TIERS.md](docs/reference/FREE_TIERS.md)**.
>
> Estes números são reavaliados a cada duas semanas em relação ao catálogo ao vivo e **podem variar nos dois sentidos** — um provedor encerra um nível gratuito e o número diminui; um novo surge e ele aumenta. Publicamos o que o catálogo realmente calcula, nunca um melhor caso arredondado para cima.
⭐ Dê uma estrela ao repositório se a OMNIROUTE ajudou você a economizar dinheiro e facilitou seu trabalho.
[](https://github.com/diegosouzapw/OmniRoute)
[](https://www.star-history.com/diegosouzapw/omniroute)
[](https://olud.ai/project/diegosouzapw-omniroute.html)
### 💬 Participe da comunidade
**👋 Siga o responsável pela manutenção — receba primeiro novos provedores, 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 provedores, 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 Crescendo
| | v3.8.50 | **v3.8.51** | `v3.8.54+` |
| ----------------------------------------- | :----------------------: | :---------: | :---------------------: |
| 🌐 Provedores | 352 | **358** | 388 |
| 🧠 IDs exclusivos de modelos de chat | 1320 | **1374** | 1491 |
| 🖼️ Ponte de modalidades | 🆕 visão + áudio + vídeo | ✓ | ✓ |
| 📡 Catálogo gratuito do Radar | 🆕 adesão opcional | ✓ | ✓ |
| ⚖️ Agendamento com reconhecimento de cota | 🆕 Quota-Share | ✓ | ✓ |
| 📊 Telemetria de cota | 🆕 ao vivo | ✓ | ✓ |
| 🧰 Modo sem interface | — | — | 🆕 `serve --headless` |
| 🛤️ Infraestrutura da linha LTS | — | — | 🆕 canais de lançamento |
| 🔎 API de descoberta de modelos | — | — | 🆕 `/v1/models/query` |
**→ [Roteiro](ROADMAP.md) — seguindo pela linha até `v3.9.0 LTS`**
## 🆓 Instale, conecte um provedor e roteie por um único endpoint
```bash
# Depois de conectar um provedor, copie sua chave do OmniRoute em 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` precisa de uma rota elegível. Uma instalação nova pode não ter destinos elegíveis sem chave, e um provedor sem chave pode rejeitar clientes de terceiros. Provedores marcados como `tos: avoid`, incluindo Kiro, são excluídos do roteamento automático por padrão; conectar uma conta não substitui essa configuração. Consulte o [Guia de Níveis Gratuitos](docs/getting-started/FREE-TIERS-GUIDE.md) antes de escolher um provedor.📦 Scripts de início rápido para copiar e colar em **Python, Node.js, PHP e cURL** → [`examples/quickstart/`](examples/quickstart/)
# 💥 A promessa
# 🤔 Por que o OmniRoute?
## 🤝 Apoiado pelos nossos Amigos de Código Aberto
> **Quer se juntar como um 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. Entre em contato: [diegosouza.pw@outlook.com](mailto:diegosouza.pw@outlook.com)
Kimi Moonshot AI
Agradecemos à Kimi (Moonshot AI), nossa Amiga Fundadora 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-token, visão nativa e codificação de nível de fronteira por uma fração dos preços dos modelos fechados, e funciona perfeitamente com Claude Code, Codex e todas as ferramentas de codificação que o OmniRoute oferece.
O que o suporte da Kimi impulsiona: Os créditos da API da Kimi impulsionam o pipeline de lançamento validado por IA do OmniRoute — o estágio de validação de mesclagem impulsionado pelo Kimi K3 que revisa cada pull request antes de ser enviado — além do desenvolvimento diário de recursos. 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 de API). O OmniRoute também é o primeiro projeto de código aberto brasileiro no programa de suporte da Kimi. Obtenha uma chave de API da Kimi com 15% de créditos extras →
Cheaper Inference cheaperinference.com
Agradecemos à Cheaper Inference, uma Amiga de Código Aberto do OmniRoute, por apoiar este projeto! A Cheaper Inference é um gateway classificado por custo que revende 42 modelos de ponta — Claude, GPT-5.x, Gemini, Kimi K3, GLM, DeepSeek, Grok e MiniMax — por trás de um endpoint compatível com OpenAI, roteando cada solicitação para o provedor elegível mais barato sem nunca cobrar acima do preço de tabela do fabricante do modelo.
Suporte de primeira classe no OmniRoute: Chat Completions, o endpoint nativo /v1/responses, visão, chamada de ferramenta e 3 modelos de imagem (grok-imagine, nano-banana-pro, nano-banana-2, acessíveis como cheaperinference/<model>). Obtenha uma chave de API →
Links marcados com aff=omniroute são links de parceiros. Eles financiam o projeto sem custo extra para você. 🎟️ Promoção de Afiliados — cupons de inscrição gratuitos de provedores que não patrocinamos (clique para expandir)Esta seção é apenas para códigos de referência/cupom. Parcerias patrocinadas estão em 🤝 Apoiado pelos nossos Amigos de Código Aberto acima. O OmniRoute não tem patrocínio ou parceria com os provedores listados aqui — estes são cupons públicos que qualquer pessoa pode usar.
AgentRouter agentrouter.org
AgentRouter — inscrição de afiliado · $100 em créditos grátis 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 wire 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 muito mais. Pegue seus $100 →
⚠️ Link de afiliado — O OmniRoute não tem patrocínio ou parceria com este provedor.
Conhece outro provedor com um generoso cupom de inscrição gratuita que beneficia os usuários do OmniRoute? Abra uma issue e nós o adicionaremos aqui.
## 🎯 Combos — O principal recurso
> Um **combo** é uma cadeia de modelos entre os quais o OmniRoute faz o roteamento **automaticamente**. Se a cota se esgotar, um provedor falhar ou os custos dispararem, o combo poderá avançar para o próximo modelo íntegro e elegível. 🛡️
### ⚡ Configuração zero — basta usar `auto`
Não é preciso criar nenhum combo. Defina seu modelo como `auto` (ou uma variante), e o OmniRoute criará um combo virtual com base nos provedores conectados, com pontuação calculada em tempo real:
ID do modelo
O que ele otimiza
auto
🎯 Padrão equilibrado (LKGP — mantém seu último provedor válido)
auto/coding
🧑💻 Pesos que priorizam a qualidade para geração de código
auto/fast
⚡ Menor latência primeiro
auto/cheap
💰 Menor custo por token primeiro
auto/subscription
🎟️ Somente a cota da assinatura pela qual você já paga — falha de forma restritiva, sem recorrer a uma opção faturável (guia)
auto/thrifty
🪜 Primeiro a cota do plano, depois um degrau por vez até as opções pagas mais baratas — retorna ao plano após a redefinição da cota (guia)
auto/offline
🔋 Maior margem de cota/limite de requisições primeiro
auto/smart
🔭 Prioriza a qualidade + 10% de exploração para descobrir modelos melhores
auto/lkgp
📌 Afinidade explícita com o último provedor válido conhecido
auto/chaos
🧪 Distribuição paralela para um painel de modelos (um por provedor, 5 por padrão), retornando uma única resposta; uma chamada upstream por modelo do painel, sem injeção de falhas
##
### 🔀 Ou crie o seu próprio — 20 estratégias de roteamento
Todas as **20** estratégias — combine-as livremente em cada etapa do combo:
#
Estratégia
O que ela faz
1
priority
Lista ordenada pelo primeiro destino — esgota cada um antes de passar ao próximo 🥇
2
fill-first
Usa integralmente a cota de cada destino antes de avançar
3
weighted
Seleção aleatória ponderada pelo peso de cada destino
4
round-robin
Alterna entre os destinos em 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 duplicatas)
8
strict-random
Seleção aleatória sem remover repetições 🎲
9
cost-optimized
Minimiza o custo por solicitação com base nos preços do catálogo em tempo real 💸
10
headroom
Seleciona o destino com a maior cota restante
11
quota-weighted
Ignora contas esgotadas e seleciona proporcionalmente à cota restante ÷ carga em andamento — as conversas existentes permanecem fixadas ⚖️
12
reset-window
Prefere o destino cuja janela de cota será redefinida primeiro
13
reset-aware
Classifica pelo tempo até a redefinição da cota — 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 atual do contexto
16
cache-optimized
Fixa cada prefixo reutilizável de prompt na mesma conta — maximiza os acertos no cache de prompts 🎯
17
lkgp
Último caminho válido conhecido — fixa no último provedor bem-sucedido e, em seguida, recorre às regras
18
auto
Pontuação em tempo real baseada em 16 fatores para todas as conexões 🤖
19
fusion
Distribui para um painel de modelos + um modelo avaliador sintetiza uma única resposta 🧬
20
pipeline
Encadeia etapas — a saída de cada destino alimenta o próximo 🔗
O mecanismo Auto-Combo pontua cada candidato com base em **16 fatores** (integridade, cota, 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)
📖 [Mecanismo Auto-Combo](docs/routing/AUTO-COMBO.md) · [Guia de Resiliência](docs/architecture/RESILIENCE_GUIDE.md)
## 🏆 O que diferencia o OmniRoute
📊 Metodologia completa e detalhes por recurso em comparação com 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 ele poupa seu tempo ou dinheiro, veja como ajudar a mantê-lo independente — escolha a opção que mais combina com você. O patrocínio nunca afeta a prioridade de roteamento; ele oferece visibilidade, não posição no ranking.
**🇧🇷 PIX** — instantâneo, sem taxas (Brasil)
Chave (aleatória): `5d865059-bc44-483a-962d-43ceb80126eb`
Pix copia e cola:
```
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 somente pela rede indicada — o envio pela rede errada pode resultar na perda dos fundos.
🐛 Encontrou um bug ou tem algum comentário? Abra uma [Discussão](https://github.com/diegosouzapw/OmniRoute/discussions).
Notas para desenvolvedores: O projeto pode gerar um arquivo local .env durante a instalação ou o postinstall do npm para facilitar o trabalho dos desenvolvedores. Esse arquivo é intencionalmente ignorado por meio do .gitignore (consulte .gitignore) e nunca deve ser commitado — se for commitado acidentalmente, substitua todos os segredos expostos e remova o arquivo do histórico. Consulte docs/DEVELOPER-ENVIRONMENT.md para obter orientações sobre como gerenciar arquivos de ambiente locais e segredos.
## 📡 Radar do OmniRoute
O principal destaque do nível gratuito continua sendo **~1,62 bilhão de tokens/mês** do catálogo documentado e com pools sem duplicação acima. Créditos temporários de cadastro de provedores podem, separadamente, elevar o primeiro mês para **~2,22 bilhões**. O Radar é uma sobreposição opcional e assinada do catálogo para quem deseja informações mais atualizadas sobre a disponibilidade de modelos gratuitos entre os lançamentos do OmniRoute; o catálogo da comunidade e todos os recursos gratuitos existentes continuam gratuitos.
Os apoiadores podem receber o catálogo em tempo real e oportunidades adicionais de provedores. Seu limite separado e variável é de **aproximadamente 3 bilhões de tokens/mês, no máximo**, dependendo da disponibilidade dos provedores. Esse limite não é uma garantia: os provedores podem alterar cotas, elegibilidade, modelos ou regiões a qualquer momento.
O Radar é opcional e usa apenas GET. O cliente OmniRoute não envia prompts, tráfego, configuração de provedores, telemetria de uso nem o estado local de dispensa de anúncios. Saiba mais sobre a elegibilidade e o catálogo atual em **[radar.omniroute.online/planos](https://radar.omniroute.online/planos)**.
## ✨ O que há de novo
> 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 contas esgotadas e, em seguida, escolhe entre as restantes na proporção de cota restante ÷ carga em andamento, mantendo as conversas existentes fixadas. → [Auto-Combo](docs/routing/AUTO-COMBO.md)
- **🧰 Modo headless** — `omniroute serve --headless` (ou `OMNIROUTE_HEADLESS=1`) executa apenas o mecanismo proxy `/v1/*`, com o painel e os subsistemas exclusivos do painel desativados. → [Modo headless](docs/guides/HEADLESS.md)
- **🔎 Descoberta de modelos** — `/v1/models` filtra por capacidade, contexto, tipo e texto, e `POST /v1/models/query` retorna uma lista curta e determinística com a mesma visibilidade por chave. → [Referência da API](docs/reference/API_REFERENCE.md)
- **🔑 Controle de roteamento por chave** — fixe uma chave de API em um modelo ou combinação com `forcedModel` e adicione ou remova modelos e combinações de uma chave atomicamente (`/api/keys/{id}/access`). → [Referência da API](docs/reference/API_REFERENCE.md) · [OpenAPI](docs/openapi.yaml)
- **🛡️ Controles de PII mais refinados** — seleção por tipo, até 20 padrões personalizados de mascaramento validados e contadores de detecção por tipo; o mascaramento continua opcional. → [Barreiras de proteção](docs/security/GUARDRAILS.md)
- **🌍 67 idiomas** — painel, espelhos da documentação e CLI, com `npm run i18n:add-locale` adicionando um idioma em todos os lugares com um único comando. → [Guia de i18n](docs/guides/I18N.md)
- **🎛️ OmniConductor** — delegação A2A de entrada para sua frota de agentes, habilidades do Conductor no Agent Card e um painel com chat de voz Faro no modo push-to-talk. → [Servidor A2A](docs/frameworks/A2A-SERVER.md)
- **🛂 Admissão adaptativa e proteção contra sobrecarga** — solicitações de chat pesadas entram em fila em vez de retornarem 503, com leases atômicos de RPM em janela móvel por conexão. → [Guia de resiliência](docs/architecture/RESILIENCE_GUIDE.md)
- **🗂️ Ordenação canônica de `/v1/models`** — um único bloco contíguo agrupado por provedor para cada provedor (combinações fixadas primeiro), estável em todas as fontes do catálogo. → [Referência da API](docs/reference/API_REFERENCE.md)
- **🗜️ Fortalecimento da compressão** — proteção contra inflação ativada por padrã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** — provedores de assinatura / plano de programação aparecem como **$0** nas análises de custos; orçamento, cota e roteamento continuam fazendo estimativas. → [Referência da API](docs/reference/API_REFERENCE.md)
- **⚖️ Roteamento Quota-Share** — divide a cota de uma conta compartilhada de forma justa entre chaves agrupadas, aproveitando toda a capacidade ao emprestar fatias ociosas. → [Guia de resiliência](docs/architecture/RESILIENCE_GUIDE.md)
- **🤖 Configuração de CLI/agente com um único comando** — 15 comandos `setup-*` registrados; `omniroute run` inicia 7 CLIs (Claude Code, Codex, Aider, Goose, OpenCode, Qwen Code, Gemini CLI); `omniroute configure` oferece suporte a 11 destinos, com um seletor interativo de provedor + modelo e favoritos por contexto. → [Integrações de CLI](docs/guides/CLI-INTEGRATIONS.md)
- **🛰️ Modo remoto** — controle um OmniRoute remoto com tokens com escopo (`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 + juiz), roteamento ciente da tarefa, substituições por solicitação de modelo / modo / orçamento em USD. → [Auto-Combo](docs/routing/AUTO-COMBO.md)
- **🗜️ Compressão modular** — 12 mecanismos combináveis + Compression Studios: LLMLingua-2, Ultra de dois níveis, omniglyph, controle de fidelidade por etapa, GCF v3.2, editor com reordenação por arrastar. → [Compressão](docs/compression/COMPRESSION_ENGINES.md)
- **🕵️ Descriptografia MITM transparente (TPROXY)** — capture 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 todos os lugares** — cabeçalhos de custo/uso `X-OmniRoute-*` em todos os endpoints, cabeçalho de economia de cache-HIT e cotas de gastos em USD por chave. → [Referência da API](docs/reference/API_REFERENCE.md)
- **🧠 Memória sob seu controle** — desativada por padrão, quantização vetorial int8 opcional + decaimento tipado, `x-omniroute-no-memory` por solicitação. → [Memória](docs/frameworks/MEMORY.md)
- **🛡️ Segurança** — proteção contra injeção de prompt em todas as rotas de LLM (suíte de red team), proteção opcional de mascaramento de credenciais (remove chaves de API/segredos vazados em ambas as direções), pesquisa web gratuita de último recurso via DuckDuckGo e uma barreira de login OIDC opcional para o painel (o login por senha continua sempre disponível). → [Barreiras de proteção](docs/security/GUARDRAILS.md)
- **🖼️ Novos endpoints** — `/v1/ocr` (Mistral OCR) e `/v1/audio/translations` (no estilo Whisper) completam a superfície de mídia. → [Referência da API](docs/reference/API_REFERENCE.md)
- **🎨 Geração de imagens / vídeos / áudio** — uma API para mídia: xAI Grok Imagine e vídeos da Novita AI, ComfyUI, Magnific, Adobe Firefly, Segmind e provedores de fala como ElevenLabs. → [Referência da API](docs/reference/API_REFERENCE.md)
- **🌍 Implantação e operações** — `basePath` de proxy reverso, detecção automática do idioma do navegador, rastreamento de dispositivos por chave, confiança MITM sem root e localização zh-TW. → [Ambiente](docs/reference/ENVIRONMENT.md)
- **🤝 Mais provedores e agentes** — agentes na nuvem (Codex Cloud, Cursor, Devin, Jules), Grok Build (xAI) com navegador + login 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 provedores** atualizado. → [Provedores](docs/reference/PROVIDER_REFERENCE.md)
- **📡 Transparência do roteamento** — cada resposta traz um cabeçalho `X-OmniRoute-Decision` que identifica a estratégia/provedor/latência que a processou; uma nova estratégia de combinação `cache-optimized` + o fator `cacheAffinity` do Auto-Combo redirecionam solicitações repetidas para a conexão que contém o prefixo em cache; e um endpoint somente leitura `/v1/auto-combo/{channel}/candidates` expõe o conjunto de candidatos ativo de um canal `auto/*`. → [Auto-Combo](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 skills 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 logs para o BigQuery, distribuição paralela de vários modelos com `auto/chaos`, uma ponte para bots do Telegram, um gerenciador de versões integrado ao aplicativo e rankings de provedores gratuitos LMArena-ELO. → [Documentação](docs/README.md)
## 🤖 CLIs & Agentes de Codificaçã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)
**Inicie qualquer CLI suportada pelo OmniRoute com um único comando** — sem arquivos de configuração gravados,
credenciais injetadas por processo, Qwen/Gemini recebem um diretório home isolado e descartável:
```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 provedor+modelo interativamente e escreva a própria configuração da ferramenta:
omniroute configure codex # também: claude opencode qwen aider goose gemini cline continue kilo 5dive
```
Todo comando respeita o contexto remoto ativo (`omniroute connect `), `--dry-run`
exibe uma prévia 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 provedores de IA — 153 marcados como gratuitos no catálogo
> **388 provedores registrados** nas coleções canônicas de chat, mídia, pesquisa, locais, agentes de nuvem e sistema, incluindo **153 com metadados de descoberta `hasFree: true`**. O registro de modelos de chat abrange **239 provedores / 3.059 pares distintos de provedor-modelo / 1.475 IDs de modelo brutos**; o catálogo separado de orçamento gratuito tem **471 linhas por modelo**, **34 pools recorrentes** e **52 provedores gratuitos para sempre, recorrentes e sem chave**. Esses são denominadores diferentes por definição; as definições e os cálculos deduplicados por pool estão disponíveis em [Referência de provedores](docs/reference/PROVIDER_REFERENCE.md) e [Planos gratuitos](docs/reference/FREE_TIERS.md).
### 🏢 Todos os principais laboratórios — por meio 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 — cada ícone é resolvido dinamicamente a partir do catálogo de provedores do painel. 📖 [Referência de provedores](docs/reference/PROVIDER_REFERENCE.md)
### 🆓 Gratuito para sempre — $0, sem cartão
OpenCode Zen DeepSeek V4, Nemotron 3 Sem limite de tokens
Kilo Code Roteador automático, Tencent Hy3 Grátis para sempre
Requesty GPT-OSS 120B, Nemotron Grátis para sempre
SiliconFlow DeepSeek V3.2 / R1 Plano gratuito
Z.AI GLM GLM-4.7 / 4.5-Flash Grátis para sempre
Baidu ERNIE ERNIE 4.0 Grátis para sempre
Qoder AI Qwen3-Max, Kimi-K2 GRÁTIS ilimitado
Pollinations GPT, Llama, Claude Não é necessária uma chave
Cloudflare AI Mais de 50 modelos 10 mil neurônios/dia
NVIDIA NIM GLM, MiniMax ~40 RPM grátis
Cerebras GLM 4.7, GPT-OSS Crédito único de $5; cartão necessário
OpenRouter modelos :free +$10 → RPM maior
📖 Catálogo completo legível por máquina → [`docs/reference/PROVIDER_REFERENCE.md`](docs/reference/PROVIDER_REFERENCE.md)
## 🖥️ Onde OmniRoute é executado - em qualquer lugar
> O mesmo aplicativo, sua máquina, suas regras. De uma instalação npm global para** 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 registro, instalação mais rápida
🐳 Docker
docker executar … diegosouzapw/omniroute
Multi-arco AMD64 + ARM64
🖥️ Desktop (Electron)
npm executar elétron: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 em seu telefone , 24/7, sem root
📲 PWA
"Adicionar à tela inicial"
Tela cheia, offline, instalável a partir do navegador
🧩 OpenCode plugin
@omniroute/opencode-provider
Integração OpenCode nativa
🤖 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 · [Área de trabalho](electron/README.md) · [Bandeja da barra de menu](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
> Nenhuma nova barra lateral, nenhum novo chat UI - cada modelo que OmniRoute atende aparece diretamente no** Seletor de modelo Copilot Chat que você já usa** . Desde o Código VS 1.122, os modelos de provedores 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 padrão é `localhost:20128`) e abra Copilot Chat → model picker →** Gerenciar modelos…** →**OmniRoute** .
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 bate-papo](docs/guides/VSCODE-COPILOT.md) - configuração, o que o seletor mostra, painel em uma guia, solução de problemas
### 🎩 Novo: OmniRouteTray — seu gateway, localizado na barra de menu
> `omniroute serve` fica mais feliz quando está sempre ligado.** [OmniRouteTray](https://github.com/zoispag/omniroute-tray)** transforma isso em um aplicativo de barra de menu do tipo configure e esqueça para macOS: ele inicia o servidor, mantém-no ativo durante as reinicializações, atualiza-o e coloca seu orçamento de token ativo a um clique de distância -** nenhuma janela de terminal aberta, nenhum `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), ele vem com seu próprio tempo de execução Node 24 assinado e gerencia uma instalação OmniRoute de propriedade do aplicativo, para que nunca lute contra seu `node`/`bun` global. Isto** compartilha sua configuração e banco de dados `~/.omniroute/` existente** - então é o mesmo OmniRoute que você já dirige, só que de chapéu. 🎩
O que faz
Como
🟢 Supervisiona o servidor
Gera omniroute serve , adota uma instância já em execução em vez de duplicá-la
📊 Visão geral do uso ao vivo
Barras de cota do provedor, limites Claude session/weekly com contagem regressiva redefinida, detalhamento de custos em 30 dias
🔄 Atualizações automáticas em vigor
Instalação em estágios, troca atômica, reversão em caso de falha — sempre na versão mais recente
🚀 Iniciar no login
Lançamento opcional no login; somente 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
Libera . 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.
> Além do servidor, o OmniRoute é um **cockpit completo de linha de comando** com **mais de 80 comandos**, além de protocolos abertos para agentes, permitindo que um agente de IA o controle **por conta própria**.
### ⌨️ Uma CLI de verdade (não apenas `start`)
```bash
omniroute # inicia o gateway + painel (porta 20128)
omniroute chat # cliente de chat TUI interativo (comandos: /model /combo /skill /memory)
omniroute setup # assistente guiado para a primeira execução
omniroute doctor # diagnostica provedores, portas e dependências nativas
```
### 🛰️ Modo remoto — execute a CLI aqui e o OmniRoute em um VPS
OmniRoute em um servidor? Controle-o pelo seu laptop com a **mesma CLI**. Faça login uma vez
com um token de acesso com escopo; depois disso, todos os comandos serão direcionados ao servidor remoto.
```bash
omniroute connect 192.168.0.15 # senha → token com escopo, salvo como um contexto
omniroute models # ← executa no servidor REMOTO
omniroute configure codex # ← seleciona um modelo remoto e grava um perfil local do Codex
omniroute tokens create --name ci --scope read # gera tokens mais restritos para outras máquinas
omniroute contexts use default # ← volta para o servidor local
```
Os tokens têm os escopos `read` / `write` / `admin`; as rotas que iniciam processos permanecem restritas ao loopback.
📖 [Modo remoto](docs/guides/REMOTE-MODE.md)
### 🤝 Conecte um agente — e ele controlará o próprio OmniRoute
Exponha o OmniRoute por **MCP**, **A2A**, uma **API REST**, **webhooks** ou uma **CLI remota** — qualquer agente compatível (ou seu próprio código) terá acesso a todo o gateway: roteamento, provedores, combos, cache, compressão e memória — de forma autônoma. Os endpoints HTTP abaixo são disponibilizados em `http://localhost:20128`.
Interface
Endpoint / comando
Use para
🧰 MCP (stdio)
omniroute --mcp
Integrar ao Claude Desktop, Cursor ou qualquer cliente MCP
Comunicação entre agentes, JSON-RPC 2.0 + SSE, 6 habilidades
🌐 API REST
/v1/*
Compatível com OpenAI — chat, embeddings, imagens, áudio e OCR
🔔 Webhooks
/api/webhooks
Enviar eventos de solicitações / cotas para Slack, Discord, Telegram ou qualquer URL
🛰️ CLI remota
omniroute connect
Controlar uma instância remota com tokens de acesso com escopo
```bash
# Forneça ao Claude Code o conjunto completo de ferramentas do OmniRoute por 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 para agentes](docs/frameworks/AGENT_PROTOCOLS_GUIDE.md)
## 🗜️ Economize de 15–95% em tokens — automaticamente
### 📖 Como funciona — pipeline, arquitetura e cálculo da economia
A combinação empilhada padrão executa `RTK → Caveman`. Quando ambos atuam sobre o mesmo payload de ferramenta/contexto, a economia se acumula:
```txt
combined = 1 − (1 − RTK) × (1 − Caveman_input)
average = 1 − (1 − 0.80) × (1 − 0.46) = 89.2%
range = 78.4 – 94.6%
```
Blocos de código, URLs, JSON e dados estruturados são **sempre protegidos** pelo mecanismo de preservação.
> **Por que usar muitos tokens quando poucos resolvem?** Cada solicitação passa pelo pipeline de compressão do OmniRoute **de forma transparente** — sem alterações no cliente. Agora ele é uma **pilha de 12 mecanismos combináveis** executados em ordem e combinados conforme cada combinação de roteamento — desenvolvidos 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 mecanismos
Os mecanismos são executados na ordem do pipeline; cada um pode ser ativado ou desativado e configurado independentemente por combinação:
#
Mecanismo
O que ele faz
1
Session-Dedup
Descarta conteúdo repetido entre turnos (endereçado pelo conteúdo, entre turnos)
2
CCR
Arquiva blocos grandes atrás de marcadores de recuperação, buscados sob demanda
3
Lite
Redução de espaços em branco + URLs de imagens (linha de base com baixa latência)
4
RTK
Filtragem inteligente, deduplicação e truncamento de resultados de ferramentas (ciente de comandos)
5
Responses Tool Output
JSON priorizando a ausência de perdas + compressão diagnóstica limitada para saídas de shell/patch/pesquisa/build (Responses API)
6
Headroom
Compactação tabular sem perdas de arrays JSON (~30%) por meio de um codec GCF incorporado
7
Relevance
Pontuação extrativa de sentenças com base na última consulta do usuário
8
Caveman
Compressão de prosa baseada em regras (~65–75% na saída)
9
Aggressive
Sumarização + envelhecimento progressivo de turnos antigos
10
LLMLingua-2
Poda semântica baseada em ML via MobileBERT ONNX — segura para código, assíncrona
11
Ultra
Poda heurística de tokens com uma camada opcional de modelo pequeno (SLM)
12
OmniGlyph
Codificação experimental do contexto como imagem para o Claude Fable 5 medida no canal direto da Anthropic; os transformadores GPT 5.6 permanecem com falha fechada enquanto aguardam comprovantes do provedor. Quatro perfis de compressão (agressivo por padrão, equilibrado, seguro para código, passthrough) (mais agressivo; ativação opcional)
Blocos de código, URLs e dados estruturados são **sempre preservados** byte a byte. **Predefinições de um clique** combinam os mecanismos:
Modo
Economia
Ideal para
🪶 Lite
~15%
Padrão seguro sempre ativado
🪨 Standard (Caveman)
~30%
Programação diária
⚡ Aggressive
~50%
Sessões longas com muitas ferramentas
🔥 Ultra
~75%
Economia máxima
🧰 RTK
60–90%
Saídas de shell/testes/build/git
🔗 Stacked (RTK → Caveman)
78–95%
Prompts mistos + logs de ferramentas
**Exemplo real — modo Standard:**
> **Antes (69 tokens):** _"O motivo pelo qual seu componente React está sendo renderizado novamente provavelmente é que você está criando uma nova referência de objeto a cada ciclo de renderização. Quando você passa um objeto embutido como prop, a comparação superficial do React o considera um objeto diferente todas as vezes, o que aciona uma nova renderização. Eu recomendaria usar useMemo para memorizar o objeto."_
>
> **Depois (19 tokens):** _"Nova referência de objeto a cada renderização. Prop de objeto embutido = nova referência = nova renderização. Encapsule em useMemo."_
>
> **Mesma resposta. 72% menos tokens. Zero perda de precisão.** ✅
**Exemplo em 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 mecanismos — estilos de saída, o seletor adaptativo e controle por solicitação
Os 12 mecanismos acima reduzem o que **entra**. Mais três camadas moldam **como**, **quando** e o que **sai**:
- **🪄 Estilos de saída** _(direcionamento do eixo de saída)_ — injetam instruções determinísticas e seguras para o cache, que moldam as respostas; podem ser combinados, cada um com intensidade `lite` / `full` / `ultra`. Adicionar um estilo requer uma entrada de registro de uma linha:
- **Prosa concisa** — remover preenchimentos / artigos / ressalvas; manter o conteúdo técnico exato.
- **Menos código** — YAGNI de "desenvolvedor sênior preguiçoso": menor alteração funcional, sem estrutura adicional não solicitada.
- **Rabo de cavalo (desenvolvedor sênior preguiçoso)** — subir a escada do YAGNI, corrigir a causa raiz, menor diff funcional.
- **Tenho TDAH (ação primeiro)** — a próxima ação vem primeiro, etapas numeradas, um próximo passo concreto, sem introdução.
- **CJK conciso (文言)** — estilo ultraconciso do chinês clássico (limitado pela localidade a `zh`).
- **🎯 Orçamento de contexto adaptativo** _(o seletor)_ — em vez de um único limite de tokens ligado/desligado, escalar os mecanismos mais baratos e com menos perda somente até o necessário para **caber na janela de contexto do modelo**. Política: `reserve-output` (padrão, consciente do modelo) · `percentage` · `absolute`. Modo: `floor` (garantir que caiba) · `replace-autotrigger` (sua escolha explícita vence) · `off` (limite legado).
- **🎛️ Onde a compressão é decidida** _(precedência, alta → baixa)_ — cabeçalho por solicitação `x-omniroute-compression` › substituição da combinação de roteamento › perfil nomeado ativo › acionamento adaptativo / automático › padrão do painel › desativado. O plano aplicado é refletido no cabeçalho de resposta `X-OmniRoute-Compression: ; source=`.
Acione automaticamente por limite de tokens, ative o seletor adaptativo, fixe um perfil nomeado, defina uma configuração específica para uma solicitação ou atribua um pipeline por combinação de roteamento — o que melhor se adequar à carga de trabalho. Um **harness de avaliação** offline opcional (`npm run eval:compression`) calcula a fidelidade em relação à economia em um corpus fixado antes que você promova 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) Instale e execute**
```bash
npm install -g omniroute
omniroute
```
> 💡 Viu `npm warn ERESOLVE` ou avisos de dependências peer? [Eles são inofensivos](docs/guides/TROUBLESHOOTING.md#npm-install-warnings-eresolve--peer--deprecated).
> **Usando npm 11 ou posterior?** O npm pode bloquear scripts do ciclo de vida dos pacotes, a menos que eles sejam permitidos. O `postinstall` do OmniRoute (`node scripts/build/postinstall.mjs`) é necessário para preparar os arquivos nativos do runtime. Permita os pacotes mencionados no aviso do npm ao instalar globalmente. Para o conjunto de pacotes informado pelo OmniRoute 3.8.54:
>
> ```bash
> npm install -g --allow-scripts=omniroute,keytar,onnxruntime-node,@parcel/watcher,@swc/core,protobufjs,esbuild omniroute
> ```
>
> Para reutilizar essa 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 informar uma lista diferente, use os nomes dos pacotes presentes nesse aviso. Permitir um pacote autoriza a execução dos scripts de instalação.
> **Usando Gemini Web ou outro provedor baseado em cookies da web?** O pacote npm inclui
> Playwright, mas não o binário do Chromium. Consulte a observação sobre a
> [configuração do Chromium do Playwright](docs/guides/TROUBLESHOOTING.md#gemini-web-and-playwright-chromium)
> antes de fazer a primeira solicitação a um provedor web.
Painel em `http://localhost:20128` · API em `http://localhost:20128/v1`.
**2) Conecte um provedor elegível usando sua própria conta**
Painel → **Provedores** → escolha um provedor cujos termos e cota atuais sejam adequados ao seu caso de uso → adicione sua chave de API ou conclua o fluxo da conta. Os níveis gratuitos podem exigir cadastro, aprovação ou um método de pagamento. Consulte o [Guia de níveis gratuitos](docs/getting-started/FREE-TIERS-GUIDE.md); a disponibilidade sem chave não é garantida, e os provedores marcados com `tos: avoid` são excluídos de `auto` por padrão.
**3) Aponte sua ferramenta de programação**
```txt
URL base: http://localhost:20128/v1
Chave de API: [copie do Painel → Endpoints]
Modelo: auto (roteia entre conexões elegíveis — ou escolha provedor/modelo)
```
**4) Verifique se está funcionando**
```bash
curl http://localhost:20128/v1/models -H "Authorization: Bearer YOUR_KEY"
```
Você deverá ver seus modelos conectados listados. 🎉 É só isso — comece a programar, e o OmniRoute fará o roteamento e o fallback automaticamente.
Se o seu cliente não puder enviar cabeçalhos personalizados, o OmniRoute também disponibiliza aliases de compatibilidade tokenizados:
```txt
Catálogo OpenAI: http://localhost:20128/vscode/YOUR_KEY/
Modelos OpenAI: http://localhost:20128/vscode/YOUR_KEY/models
Chat OpenAI: http://localhost:20128/vscode/YOUR_KEY/chat/completions
Respostas OpenAI: http://localhost:20128/vscode/YOUR_KEY/responses
Chat Ollama: http://localhost:20128/vscode/YOUR_KEY/api/chat
Tags Ollama: http://localhost:20128/vscode/YOUR_KEY/api/tags
```
Use-os somente para clientes que não conseguem anexar `Authorization: Bearer ...`. A autenticação por cabeçalho continua sendo 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 estável SemVer **publicada** mais alta. Ela não acompanha a `main` do git. Fixe em `: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`**. Isso é suficiente para o painel e um chat leve. **Agentes de programação** (`POST /v1/responses` do Claude Code, Codex, Grok, …) precisam de um heap V8 muito maior, caso contrário o processo apresenta `FATAL ERROR` com aproximadamente 12 GiB durante dois contextos longos sobrepostos. Dimensione o contêiner acima do tamanho do heap (os buffers nativos ficam fora do V8):
| Carga de trabalho | Heap (`-e OMNIROUTE_MEMORY_MB`) | Contêiner (`--memory`) |
| --------------------------------------- | ------------------------------- | ---------------------- |
| Painel / chat leve | `1024` (padrão da imagem) | ≥2 g |
| Um agente de programação | `8192` | ≥10 g |
| Duas `/v1/responses` longas simultâneas | `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 a ramificação padrão atual `release/v*`.
> Essas tags mutáveis destinam-se apenas a testar correções ainda não lançadas e
> **não são compatíveis com ambientes de 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 compatíveis por meio da detecção do runtime Bun:
- **`bun:sqlite` integrado**: o OmniRoute usa o driver `bun:sqlite` integrado do Bun quando executado no Bun, recorrendo ao `better-sqlite3` no Node.js ou ao `sql.js`.
- **Seleção automática do empacotador Webpack em desenvolvimento**: o desenvolvimento (`bun run dev`) detecta automaticamente o Bun e desativa o Turbopack em favor do Webpack para evitar incompatibilidades com bindings nativos do V8. As builds de produção (`bun run build`) seguem `OMNIROUTE_USE_TURBOPACK` exatamente como no Node: Turbopack por padrão, `OMNIROUTE_USE_TURBOPACK=0` para compilar com Webpack (`Dockerfile.bun` o disponibiliza como um `--build-arg`).
- **Dockerfile dedicado ao Bun**: `Dockerfile.bun` multiestágio para implantações nativas de produção com Bun (`docker build -f Dockerfile.bun -t omniroute:bun .`).
```bash
# Instale e execute com 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
# Usando flakes do Nix
nix develop
npm run dev
# Ou usando devbox
devbox run npm run dev
```
📖 [Guia do Docker](docs/guides/DOCKER_GUIDE.md) — perfis do Compose, HTTPS com Caddy e túneis do Cloudflare.
**🦭 Podman**
```bash
# 1. Prepare o diretório de dados montado por bind
mkdir -p data
# 2. Somente Linux + Podman rootless local (nunca um cliente remoto do Podman Machine):
podman unshare chown 1000:1000 ./data
# 3. Defina a indicação de runtime, compile a imagem local do Compose e inicie
echo "CONTAINER_HOST=podman" >> .env
podman compose --profile base up -d --build
```
No macOS ou Windows, o Podman usa um Podman Machine remoto: ignore `podman unshare` e
siga as [orientações de diretório de dados específicas para cada topologia](contrib/podman/README.md#data-directory-permissions-by-topology).
📖 [Guia do Podman](contrib/podman/README.md) — builds do Compose, Podman Machine e
configuração do Quadlet com Linux/systemd.
**⚡ Instalação mais rápida / enxuta (ignore a build nativa)**
O mecanismo SQLite nativo (`better-sqlite3`) é uma dependência **opcional**, portanto uma
instalação global nunca fica bloqueada compilando a partir do código-fonte: ela usa um binário pré-compilado quando há um compatível
com sua plataforma/Node e, caso contrário, recorre de forma transparente a um mecanismo JavaScript puro
(`node:sqlite` no Node 22+, ou então o WASM `sql.js` incluído) — nenhuma ferramenta de build é necessária.
Para ignorar completamente a preparação nativa pós-instalação (CI, ambientes 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 + links físicos — veja acima).
Para um runtime sem painel e sem interface gráfica, use o perfil `base` do Docker (acima) ou o
[guia do Termux](docs/guides/TERMUX_GUIDE.md). A CLI e o painel web são servidos pelo
mesmo processo em uma única porta, portanto atualmente não há um pacote separado somente para CLI.
OAuth 2.0 (PKCE) + JWT + chaves de API + autenticação com escopo MCP · AES-256-GCM em repouso · DOMPurify
Furtividade
wreq-js — personificação de impressões digitais TLS JA3 / JA4, proxy de 3 níveis
Resiliência
Disjuntor, recuo exponencial, prevenção de efeito manada, autocorreção automática de combinações
Logging
pino — logs JSON estruturados com contexto da solicitação
Testes
Executor de testes do Node.js + Vitest — mais de 60.000 declarações de testes estáticos em mais de 8.400 arquivos de teste monitorados (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 arquivos de teste monitorados
# ⭐ Principais contribuidores
> O OmniRoute é moldado por uma apaixonada comunidade de código aberto. Essas pessoas fizeram contribuições excepcionais que impactam diretamente a qualidade, a estabilidade e o alcance do projeto. **Obrigado.**
### Contribuidores externos por pull requests incorporados
Censo realizado em 2026-11-03 03:01:19 UTC com o estado atual de release/v3.8.53 em 05bc048d6c. O censo paginado do GitHub GraphQL contém 9.947 PRs incorporados: 4.130 pelo proprietário do repositório, 240 pelo Dependabot, 6 por outros bots/aplicativos e 5.571 PRs externos de 883 contribuidores distintos. “Linhas alteradas” corresponde às adições + exclusões do GitHub e inclui arquivos gerados, lockfiles, catálogos, traduções e documentação; trata-se de churn, não de LOC de autoria. 53 PRs apresentam diferenças do GitHub acima de 500.000 linhas (por exemplo, o #13399, uma única adição de provedor, lista 2.347 arquivos alterados), o que infla vários totais acima. Empates são classificados juntos.
### Commits atribuídos ao GitHub
Verificado novamente em 2026-11-03 02:09:16 UTC: commits atribuídos pelo GitHub informados pela API de contribuidores do repositório para o branch padrão release/v3.8.53. A API retornou 903 identidades (429 usuários, 2 bots, 472 anônimas); esta tabela exclui o mantenedor, os bots e as identidades anônimas, e mantém os empates. Ela é distinta tanto do ranking de PRs mesclados acima quanto do censo de metadados do Git abaixo.
> 🙏 Os recursos, as correções de bugs e as melhorias de infraestrutura desses contribuidores são uma **parte essencial** do que torna o OmniRoute confiável e completo em recursos. Cada pull request, cada caso de teste e cada arquivo de tradução i18n são importantes. O código aberto é construído por pessoas como eles.
---
## 💖 Patrocinadores
Um agradecimento de coração às pessoas que financiam o OmniRoute do próprio bolso — cada contribuição mantém o projeto gratuito, independente e em constante evolução.
… e outros que preferem permanecer anônimos 💛Os GitHub Sponsors públicos foram revalidados em 2026-10-18 por meio da API GraphQL do GitHub Sponsors: 11 patrocínios públicos (6 ativos e 5 anteriores), de um total de 14. O status isActive do GitHub determina os rótulos de ativo acima; apoiadores públicos pontuais anteriores continuam sendo reconhecidos, e patrocinadores privados permanecem anônimos. Doações via Ko-fi, Buy Me a Coffee, Liberapay, PIX e criptomoedas não estão listadas porque não possuem um registro público de patrocinador.💖 Torne-se um patrocinador → — cada dólar mantém o OmniRoute gratuito e independente.
## 👥 Mais de 1.000 colaboradores
[](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)
Auditado em 2026-11-02 no tip ativo de release/v3.8.531c7135e0fb (7.972 commits): 1.074 identidades humanas normalizadas do Git — 759 aparecem como autores de commits (incluindo o mantenedor) e 315 apenas em trailers explícitos Co-authored-by. O censo aplica .mailmap, compara endereços de e-mail sem diferenciar maiúsculas de minúsculas, associa endereços numéricos e simples do GitHub noreply somente quando eles codificam o mesmo identificador, exclui 29 identidades de bots/agentes/serviços/placeholder e não mescla endereços de e-mail comuns apenas porque seus nomes de exibição coincidem. A auditoria de 2026-08-24 publicou 639; a execução novamente deste método na base ac02c5b42f dessa auditoria resulta em 619, portanto o aumento vem de novos colaboradores, não de um método menos rigoroso.
### Como contribuir
1. Faça um fork do repositório
2. Crie uma branch a partir do tip **ativo** de `release/vX.Y.Z` (não de `main`) — consulte [Modelo de Branching e Releases](docs/ops/BRANCHING_MODEL.md)
3. Crie sua 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 as alterações para a branch (`git push origin feat/amazing-feature`)
6. Abra um Pull Request com **base = aquela branch `release/vX.Y.Z`**
Consulte [CONTRIBUTING.md](CONTRIBUTING.md) para obter orientações detalhadas.
### Lançando uma nova versão
```bash
# Crie um release — npm publish acontece automaticamente
VERSION=x.y.z
gh release create "v${VERSION}" --title "v${VERSION}" --generate-notes
```
## 📊 Estrelas
## 🌍 StarMapper
## 🙏 Agradecimentos
O OmniRoute se apoia no trabalho de gigantes. Ele começou como um fork do **[9router](https://github.com/decolua/9router)** e uma adaptação para TypeScript do projeto em 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 lá primeiro. Cada um deles moldou uma parte concreta do OmniRoute. Este é o nosso agradecimento a todos eles. 🙏
> ⭐ contagens de estrelas verificadas pela API REST do GitHub em 3 de novembro de 2026 — vá dar uma estrela a esses projetos. As contagens são um instantâneo exato com data definida e naturalmente mudarão.
### 🧬 Linhagem e gateway
O gateway de IA cujo conjunto de dados público de preços alimenta nossa sincronização de acompanhamento de custos e cujo modelo de normalização de provedores orientou nosso roteamento.
Fonte MIT adaptada para a ponte incorporada ChatGPT Web → Codex Responses, incluindo adaptadores de sessão do navegador, enquadramento de respostas, uso e pesquisa na Web.
Padrões incorporados à recuperação de streams, aliases sem raciocínio, pesquisa na Web alternativa, limites de janela deslizante, redação de logs e fluxos de inicialização reforçados.
Configurações padrão de transformação compatíveis com Claude Code e comportamento de cabeçalhos de cobrança generalizados na ponte orientada por configuração do OmniRoute.
Seus mapeamentos de modelos Grok, gerador de Statsig de fake-TypeError, padrões padrão de solicitação e dispositivo e processador de respostas NDJSON foram adaptados de forma substancial ao executor Grok Web do OmniRoute.
A principal fonte de código transitiva por trás de grok2api-merged; suas implementações de modelo, cabeçalho, payload, Statsig e processador são preservadas na linhagem do Grok Web.
A fonte MIT subjacente para os padrões de payload e dispositivo do Grok, o gerador de Statsig e o processador result.response mantidos por TQZHR e grok2api-merged.
Uma fonte transitiva creditada por grok2api-merged por sua camada de pool de proxies; o OmniRoute preserva esse aviso de linhagem, mas não reivindica uma adaptação de pool de proxies em seu executor Grok Web limitado.
A implementação original do Grok Web foi consultada para o design do upstream HTTP/navegador; seu caminho HTTP direto deriva do GrokProxy, portanto nenhuma adaptação de código independente é reivindicada.
### 🗜️ Compressão de contexto e tokens — mecanismosores
O projeto viral da filosofia “por que usar muitos tokens quando poucos tokens resolvem” — sua filosofia de fala de homem das cavernas alimenta 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 nosso mecanismo RTK, a DSL de filtros JSON, a recuperação de saída bruta e o pipeline empilhado RTK → Caveman.
Compressão de tokens em PT-BR — alimenta nosso pacote de idioma pt-BR: redução de pleonasmos e remoção de palavras de preenchimento ajustadas à gramática do português brasileiro.
A habilidade viral de codificação YAGNI do “desenvolvedor sênior preguiçoso” — inspirou nosso estilo de saída less-code: direcionamento para a menor alteração funcional que reduz o código _gerado_ (o equivalente no eixo de saída à prosa concisa do Caveman).
Compressão de saída sensível ao conteúdo e por tipo de arquivo, com desistência consciente de falhas — validou nosso despacho por tipo e a ignorância quando o ganho é mínimo.
JSON colunar em Rust + recuperação endereçada por conteúdo + deduplicação entre mensagens — validou o design dos nossos mecanismos headroom/ccr/session-dedup e o invariante estável de cache de que a “forma comprimida é independente da posição”.
Toolkit da API do compilador TypeScript — inspirou nossa remoção de comentários baseada em parser, que preserva literais de string, template e expressão regular.
A interceptação/análise MITM do tráfego entre assistentes de programação e LLMs orientou os primeiros requisitos do Traffic Inspector. Quatro módulos anteriormente derivados — mesclagem de SSE, normalização de conversas, mascaramento de segredos e sanitização de cabeçalhos — foram substituídos por implementações independentes em ambiente isolado, baseadas em padrões públicos de protocolo. As duas superfícies de passagem direta de host (passthrough.ts e _internal/bypass.cjs) continuam sendo implementações internas do OmniRoute, classificadas de forma independente; elas não foram reescritas como parte dessa substituição.
Roteamento de proxy transparente por processo — inspirou nossa desmontagem MITM segura contra falhas, tempos limite de inatividade de socket, atribuição de processos via /proc e captura TPROXY.
### 📚 Dados de modelos, observabilidade e interface
Uma lista selecionada de bibliotecas seguras por padrão que orienta nossas escolhas de segurança (Helmet.js, DOMPurify, ssrf-req-filter, safe-regex, Google Tink).
Inspirou a deduplicação de solicitações, o fallback emergencial sem custo, as estratégias Auto-Combo conectáveis e a classificação multilíngue de intenções.
Seu remapeamento de modelos com reconhecimento de contas, validação de caminhos de executáveis e comportamento de rótulos de planos orientaram o runtime Antigravity do OmniRoute.
Identificou a superfície de cota do Grok Build; o OmniRoute então verificou e corrigiu o formato ativo na rede de forma independente.
## 📄 Licença
Licença MIT - consulte [LICENSE](LICENSE) para obter 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` ao vivo. Metodologia completa (deduplicação de pools, níveis de crédito, termos dos provedores): **[docs/reference/FREE_TIERS.md](docs/reference/FREE_TIERS.md)**.
>
> Estes números são reavaliados a cada duas semanas em relação ao catálogo ao vivo e **podem variar nos dois sentidos** — um provedor encerra um nível gratuito e o número diminui; um novo surge e ele aumenta. Publicamos o que o catálogo realmente calcula, nunca um melhor caso arredondado para cima.
```bash
# Depois de conectar um provedor, copie sua chave do OmniRoute em 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` precisa de uma rota elegível. Uma instalação nova pode não ter destinos elegíveis sem chave, e um provedor sem chave pode rejeitar clientes de terceiros. Provedores marcados como `tos: avoid`, incluindo Kiro, são excluídos do roteamento automático por padrão; conectar uma conta não substitui essa configuração. Consulte o [Guia de Níveis Gratuitos](docs/getting-started/FREE-TIERS-GUIDE.md) antes de escolher um provedor.
📦 Scripts de início rápido para copiar e colar em **Python, Node.js, PHP e cURL** → [`examples/quickstart/`](examples/quickstart/)
> Um **combo** é uma cadeia de modelos entre os quais o OmniRoute faz o roteamento **automaticamente**. Se a cota se esgotar, um provedor falhar ou os custos dispararem, o combo poderá avançar para o próximo modelo íntegro e elegível. 🛡️
### ⚡ Configuração zero — basta usar `auto`
Não é preciso criar nenhum combo. Defina seu modelo como `auto` (ou uma variante), e o OmniRoute criará um combo virtual com base nos provedores conectados, com pontuação calculada em tempo real:
📖 [Mecanismo Auto-Combo](docs/routing/AUTO-COMBO.md) · [Guia de Resiliência](docs/architecture/RESILIENCE_GUIDE.md)
📊 Metodologia completa e detalhes por recurso em comparação com 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 copia e cola:
```
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 padrão executa `RTK → Caveman`. Quando ambos atuam sobre o mesmo payload de ferramenta/contexto, a economia se acumula:
```txt
combined = 1 − (1 − RTK) × (1 − Caveman_input)
average = 1 − (1 − 0.80) × (1 − 0.46) = 89.2%
range = 78.4 – 94.6%
```
Blocos de código, URLs, JSON e dados estruturados são **sempre protegidos** pelo mecanismo de preservação.
> **Por que usar muitos tokens quando poucos resolvem?** Cada solicitação passa pelo pipeline de compressão do OmniRoute **de forma transparente** — sem alterações no cliente. Agora ele é uma **pilha de 12 mecanismos combináveis** executados em ordem e combinados conforme cada combinação de roteamento — desenvolvidos 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 mecanismos
Os mecanismos são executados na ordem do pipeline; cada um pode ser ativado ou desativado e configurado independentemente por combinação:
