## 💰 ~1,62 bi de tokens/mês em níveis gratuitos de terceiros
> **Use suas próprias contas de provedores.** Esta é uma estimativa agregada de níveis gratuitos de terceiros com elegibilidade independente, 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.
>
> Combinar níveis gratuitos manualmente é trabalhoso — dezenas de SDKs, dezenas de limites de taxa e nenhuma ideia de quanto você realmente tem. A OmniRoute cataloga **489 entradas de níveis gratuitos em 35 chaves de pools recorrentes** e calcula o total de tokens a partir dos **17 pools com um orçamento mensal positivo publicado, além de cinco limites da Groq por modelo**, eliminando duplicidades por pool compartilhado. As cotas liberadas somente após uma verificação regional de identidade (atualmente: ModelScope) são exibidas separadamente, +~6 mi mediante verificação regional de identidade, e nunca são incluídas no total em destaque. O resultado permanece visível no painel (`/dashboard/free-tiers`).
> Resumo animado da página `/dashboard/free-tiers` em tempo real. Metodologia completa (eliminação de duplicidades por pool, níveis de crédito, termos dos provedores): **[docs/reference/FREE_TIERS.md](docs/reference/FREE_TIERS.md)**.
>
> Esses números são auditados novamente a cada duas semanas em relação ao catálogo em tempo real e **variam nos dois sentidos** — se um provedor encerra um nível gratuito, o número diminui; se um novo é adicionado, ele aumenta. Publicamos o que o catálogo realmente calcula, nunca um melhor cenário 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 mantenedor — receba primeiro novidades sobre provedores, versões 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.52+` |
| ------------------------------------------ | :----------------------: | :---------: | :---------------------: |
| 🌐 Provedores | 352 | **358** | 372 |
| 🧠 IDs exclusivos de modelos de chat | 1320 | **1374** | 1443 |
| 🖼️ Ponte de modalidades | 🆕 visão + áudio + vídeo | ✓ | ✓ |
| 📡 Catálogo gratuito do Radar | 🆕 adesão opcional | ✓ | ✓ |
| ⚖️ Agendamento com reconhecimento de cotas | 🆕 Quota-Share | ✓ | ✓ |
| 📊 Telemetria de cotas | 🆕 em tempo real | ✓ | ✓ |
| 🧰 Modo headless | — | — | 🆕 `serve --headless` |
| 🛤️ Infraestrutura da linha LTS | — | — | 🆕 canais de lançamento |
**→ [Roteiro](ROADMAP.md) — seguindo nos trilhos rumo à `v3.9.0 LTS`**
## 🧩 Disponível
[](https://www.npmjs.com/package/omniroute)
[](https://hub.docker.com/r/diegosouzapw/omniroute)
[](LICENSE)
## 🆓 Instale, conecte um provedor e roteie por um único endpoint
```bash
# Após conectar um provedor, copie sua chave do OmniRoute em Dashboard → 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 OpenCode Free e 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 Planos 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 carro-chefe
> 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á passar para o próximo modelo íntegro elegível. 🛡️
### ⚡ Configuração zero — basta usar `auto`
Não é necessário criar um combo. Defina seu modelo como `auto` (ou uma variante), e o OmniRoute criará um combo virtual com base nos provedores conectados, pontuados em tempo real:
ID do modelo
O que ele otimiza
auto
🎯 Padrão equilibrado (LKGP — mantém seu último provedor que funcionou)
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/offline
🔋 Maior margem de cota/limite de taxa primeiro
auto/smart
🔭 Qualidade primeiro + 10% de exploração para descobrir modelos melhores
auto/lkgp
📌 Afinidade explícita com o último provedor que funcionou
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, não é injeção de falhas
##
### 🔀 Ou crie o seu próprio — 19 estratégias de roteamento
Todas as **19** 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 totalmente a cota de cada destino antes de prosseguir
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 com o método de duas escolhas
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 em $ 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
reset-window
Prioriza o destino cuja janela de cota será redefinida primeiro
12
reset-aware
Classifica pelo tempo de redefinição da cota — janelas curtas primeiro 📊
13
context-relay
Transfere o contexto entre destinos em conversas longas 🧠
14
context-optimized
Seleciona a opção mais adequada ao tamanho atual do contexto
15
cache-optimized
Fixa cada prefixo reutilizável de prompt na mesma conta — maximiza os acertos do cache de prompts 🎯
16
lkgp
Último caminho conhecido como funcional — fixa no último provedor bem-sucedido e, em seguida, recorre às regras
17
auto
Pontuação em tempo real baseada em 16 fatores para cada conexão 🤖
18
fusion
Distribui a solicitação para um painel de modelos + um juiz sintetiza uma única resposta 🧬
19
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 é integrada (3 camadas independentes)
📖 [Mecanismo de combinação automática](docs/routing/AUTO-COMBO.md) · [Guia de resiliência](docs/architecture/RESILIENCE_GUIDE.md)
## 🏆 O que diferencia o OmniRoute
📊 Metodologia completa e detalhes por funcionalidade 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)**.
## ✨ Novidades
> Destaques recentes da **v3.8.20 → v3.8.50**. Histórico completo em [`CHANGELOG.md`](CHANGELOG.md).
- **🎛️ OmniConductor** — delegação A2A de entrada para sua frota de agentes, habilidades do Conductor no Agent Card e um painel no dashboard com chat por voz push-to-talk do Faro. → [Servidor A2A](docs/frameworks/A2A-SERVER.md)
- **🛂 Admissão adaptativa e proteção contra sobrecarga** — solicitações pesadas de chat entram em fila em vez de retornarem 503, com concessões contínuas e atômicas de RPM por conexão. → [Guia de Resiliência](docs/architecture/RESILIENCE_GUIDE.md)
- **🗂️ Ordenação canônica de `/v1/models`** — um bloco contíguo agrupado por provedor para cada provedor (combos fixados 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 expansã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 de tarifa fixa transparente** — provedores por assinatura / plano de programação exibem **$0** nas análises de custo; orçamento, cota e roteamento continuam fazendo estimativas. → [Referência da API](docs/reference/API_REFERENCE.md)
- **⚖️ Roteamento Quota-Share** — distribui de forma justa a cota de uma conta compartilhada entre chaves agrupadas, preservando o trabalho para que parcelas ociosas sejam emprestadas. → [Guia de Resiliência](docs/architecture/RESILIENCE_GUIDE.md)
- **🤖 Configuração de CLI/agente com um único comando** — 13 comandos `setup-*` registrados; `omniroute run` inicia 7 CLIs (Claude Code, Codex, Aider, Goose, OpenCode, Qwen Code, Gemini CLI); `omniroute configure` oferece suporte a 10 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 de escopo limitado (`connect` / `contexts` / `tokens`) + um auxiliar OAuth `antigravity` para instalações em VPS. → [Modo Remoto](docs/guides/REMOTE-MODE.md)
- **🧭 Roteamento automático mais inteligente** — combos `auto/:`, **Fusion** (painel de modelos + avaliador), roteamento sensível à tarefa e substituições por solicitação de modelo / modo / orçamento em USD. → [Auto-Combo](docs/routing/AUTO-COMBO.md)
- **🗜️ Compressão conectável** — 12 mecanismos combináveis + Compression Studios: LLMLingua-2, Ultra de dois níveis, omniglyph, controle de fidelidade por etapa, GCF v3.2 e 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 para o repositório 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 por 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), mecanismo opcional de mascaramento de credenciais (censura chaves de API/segredos vazados em ambas as direções), pesquisa web gratuita no DuckDuckGo como último recurso e uma barreira opcional de login OIDC para o dashboard (o login por senha continua sempre disponível). → [Proteções](docs/security/GUARDRAILS.md)
- **🖼️ Novos endpoints** — `/v1/ocr` (Mistral OCR) e `/v1/audio/translations` (estilo Whisper) completam a superfície de mídia. → [Referência da API](docs/reference/API_REFERENCE.md)
- **🎨 Geração de imagem / vídeo / áudio** — uma única API para mídia: vídeos com xAI Grok Imagine e Novita AI, ComfyUI, Magnific, Adobe Firefly, Segmind e provedores de voz como ElevenLabs. → [Referência da API](docs/reference/API_REFERENCE.md)
- **🌍 Implantação e operações** — `basePath` para 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 dedicado 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 renovado com 352 provedores**. → [Provedores](docs/reference/PROVIDER_REFERENCE.md)
- **📡 Transparência no roteamento** — cada resposta inclui um cabeçalho `X-OmniRoute-Decision` que identifica a estratégia/provedor/latência responsável por atendê-la, uma nova estratégia de combo `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 ativo de candidatos de um canal `auto/*`. → [Auto-Combo](docs/routing/AUTO-COMBO.md)
- **⚡ Desempenho e infraestrutura locais** — Redis local com um clique, implantadores 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 habilidades 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 classificações, descoberta de agentes ACP (15 agentes integrados), exportação agendada de logs para BigQuery, distribuição paralela para vários modelos com `auto/chaos`, uma ponte para bots do Telegram, um gerenciador de versões no aplicativo e classificações de provedores gratuitos do LMArena-ELO. → [Documentação](docs/README.md)
## 🤖 CLIs e agentes de programação compatíveis
> Uma configuração — `http://localhost:20128/v1` — e **todos** os IDEs ou CLIs de IA são executados 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 36 ferramentas (26 CLIs de código + 10 agentes de CLI) → [`docs/reference/CLI-TOOLS.md`](docs/reference/CLI-TOOLS.md) · 🧩 Plugin do OpenCode → [`@omniroute/opencode-provider`](https://www.npmjs.com/package/@omniroute/opencode-provider)
**Inicie qualquer CLI compatível por meio do OmniRoute com um único comando** — nenhum arquivo de configuração é gravado,
as credenciais são injetadas por processo e 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 e o modelo interativamente e grave a configuração da própria ferramenta:
omniroute configure codex # também: claude opencode qwen aider goose gemini cline continue kilo
```
Todos os comandos respeitam o contexto remoto ativo (`omniroute connect `), `--dry-run`
mostra uma prévia exata das variáveis de ambiente e dos argumentos sem executar nada, e `--api-key-env NAME` mantém os segredos fora
do histórico do seu shell. → [Integrações com CLIs](docs/guides/CLI-INTEGRATIONS.md)
## 🌐 372 provedores de IA — 154 marcados no catálogo como gratuitos
> **372 provedores registrados** nas coleções canônicas de chat, mídia, pesquisa, execução local, agentes de nuvem e sistema, incluindo **154 com metadados de descoberta `hasFree: true`**. O registro de modelos de chat abrange **237 provedores / 3.009 pares distintos de provedor-modelo / 1.443 IDs de modelo brutos**; o catálogo separado de orçamentos gratuitos tem **491 entradas por modelo**, **35 pools recorrentes** e **54 provedores gratuitos para sempre, recorrentes/sem necessidade de chave**. Esses denominadores são diferentes por definição; as definições e os cálculos com pools desduplicados estão na [Referência de Provedores](docs/reference/PROVIDER_REFERENCE.md) e nos [Níveis 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 330 — todos os ícones são carregados em tempo real a partir do catálogo de provedores do painel. 📖 [Referência de Provedores](docs/reference/PROVIDER_REFERENCE.md)
### 🆓 Gratuito para sempre — US$ 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 e ilimitado
Pollinations GPT, Llama, Claude Nenhuma chave necessária
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 US$ 5; cartão obrigatório
OpenRouter Modelos :free +US$ 10 → RPM mais alto
📖 Catálogo completo legível por máquina → [`docs/reference/PROVIDER_REFERENCE.md`](docs/reference/PROVIDER_REFERENCE.md)
## 🖥️ Onde o OmniRoute roda — em qualquer lugar
> O mesmo aplicativo, sua máquina, suas regras. De uma instalação global via npm até **seu celular** via Termux.
Plataforma
Instalação
Destaques
📦 npm (global)
npm install -g omniroute
Um comando, qualquer sistema operacional
🐳 Docker
docker run … diegosouzapw/omniroute
Multiarquitetura AMD64 + ARM64
🖥️ Desktop (Electron)
npm run electron:build
Janela nativa + bandeja do sistema — Windows / macOS / Linux
🎩 Barra de menus (OmniRouteTray)
brew install --cask zoispag/tap/omniroute-tray
Supervisiona e atualiza automaticamente o servidor — macOS
💪 ARM
nativo em arm64
Raspberry Pi, servidores ARM, Apple Silicon
📱 Android (Termux)
pkg install nodejs && npx -y omniroute
Roda no seu celular, 24 horas por dia, 7 dias por semana, sem root
📲 PWA
"Adicionar à tela inicial"
Tela cheia, offline e instalável pelo navegador
🧩 Plugin do OpenCode
@omniroute/opencode-provider
Integração nativa com o OpenCode
🤖 VS Code Copilot Chat
instale a extensão OmniCopilot
Todos os modelos do OmniRoute no seletor nativo do Copilot Chat — versões estável e Insiders
🛠️ A partir do código-fonte
npm install && npm run dev
Modifique e contribua
📖 [Guia do Docker](docs/guides/DOCKER_GUIDE.md) · [Desktop](electron/README.md) · [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 Copilot Chat nativo do VS Code
> Sem uma nova barra lateral, sem uma nova interface de chat — todos os modelos disponibilizados pelo OmniRoute aparecem diretamente no
> **seletor de modelos do Copilot Chat que você já usa**. Desde o VS Code 1.122, os modelos de provedores funcionam
> sem login no GitHub nem assinatura do Copilot — modo agente, chamadas de ferramentas e visão, tudo
> gratuitamente.
Instale a extensão **[OmniCopilot](https://github.com/diegosouzapw/OmniCopilot)**, aponte-a
para seu servidor OmniRoute (o padrão é `localhost:20128`) e abra Copilot Chat → seletor de modelos
→ **Gerenciar modelos…** → **OmniRoute**.
Dentro do editor: abra a visualização **Extensões**, pesquise por **"OmniRoute"** e clique em **Instalar**
— funciona da mesma maneira nas duas lojas. O código-fonte, as issues e o guia do processo de publicação estão em
[diegosouzapw/OmniCopilot](https://github.com/diegosouzapw/OmniCopilot).
📖 [Guia do VS Code Copilot Chat](docs/guides/VSCODE-COPILOT.md) — configuração, o que o seletor exibe, painel em uma aba e solução de problemas
### 🎩 Novo: OmniRouteTray — seu gateway na barra de menus
> `omniroute serve` funciona melhor quando está sempre ativo. O **[OmniRouteTray](https://github.com/zoispag/omniroute-tray)**
> transforma isso em um aplicativo para a barra de menus do macOS que você configura e esquece: ele inicia o servidor, mantém o serviço ativo
> após reinicializações, atualiza-o no próprio local e deixa seu orçamento de tokens em tempo real a apenas um clique — **sem
> deixar uma janela do terminal aberta e sem precisar cuidar de `npm install -g omniroute`.**
Desenvolvido com [Tauri v2](https://v2.tauri.app/) (um núcleo em Rust minúsculo), ele inclui
seu próprio runtime assinado do Node 24 e gerencia uma instalação do OmniRoute pertencente ao aplicativo, portanto nunca entra em conflito com seu
`node`/`bun` global. Ele **compartilha sua configuração e seu banco de dados existentes em `~/.omniroute/`** — portanto, é o
mesmo OmniRoute que você já executa, só que de chapéu. 🎩
O que ele faz
Como
🟢 Supervisiona o servidor
Inicia omniroute serve e adota uma instância já em execução em vez de duplicá-la
📊 Uso em tempo real de relance
Barras de cota dos provedores, limites de sessão/semanais do Claude com contagens regressivas para redefinição e detalhamento de custos dos últimos 30 dias
🔄 Atualiza-se automaticamente no próprio local
Instalação em etapas, substituição atômica e reversão em caso de falha — sempre na versão mais recente
🚀 Inicia ao fazer login
Inicialização opcional ao fazer login; somente na barra de menus, sem ícone no Dock
🩺 Diagnóstico e logs
Diagnósticos com um clique e acesso aos logs do servidor
```sh
brew install --cask zoispag/tap/omniroute-tray
```
Prefere baixar? Obtenha o .dmg mais recente em
Releases. O código-fonte, as issues e a documentação de compilação
estão disponíveis em zoispag/omniroute-tray.
💛 Um projeto da comunidade criado por @zoispag — não é uma versão oficial do 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 opere **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 (barra: /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 uma 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 terão como destino a instância remota.
```bash
omniroute connect 192.168.0.15 # senha → token com escopo, salvo como um contexto
omniroute models list # ← executado 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 continuam 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) recebe as chaves para controlar 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
Agente para agente, 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ção / cota para Slack, Discord, Telegram ou qualquer URL
🛰️ CLI remota
omniroute connect
Controlar uma instância remota com tokens de acesso com escopo
```bash
# Disponibilize 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 de agentes](docs/frameworks/AGENT_PROTOCOLS_GUIDE.md)
## 🗜️ Economize de 15% a 95% dos 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 é composta:
```txt
combinada = 1 − (1 − RTK) × (1 − Caveman_input)
média = 1 − (1 − 0.80) × (1 − 0.46) = 89.2%
intervalo = 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 tokens dão conta do recado?** Cada requisição passa pelo pipeline de compactaçã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 de diferentes maneiras para cada combinação de roteamento — com base em ideias do [RTK](https://github.com/rtk-ai/rtk), [Caveman](https://github.com/JuliusBrussee/caveman) (⭐ mais de 90 mil), [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, desativado e configurado de forma independente para cada combinação:
#
Mecanismo
O que faz
1
Session-Dedup
Remove conteúdo repetido entre turnos (endereçado por conteúdo, entre turnos)
2
CCR
Arquiva blocos grandes por trás de marcadores de recuperação, buscados sob demanda
3
Lite
Remoção de espaços em branco + URLs de imagens (base de baixa latência)
4
RTK
Filtragem, desduplicação e truncamento inteligentes de resultados de ferramentas (com reconhecimento de comandos)
5
Responses Tool Output
JSON priorizando a ausência de perdas + compactação limitada de diagnósticos 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 frases em relação à última consulta do usuário
8
Caveman
Compactação de texto baseada em regras (~65–75% na saída)
9
Aggressive
Resumo + envelhecimento progressivo de turnos antigos
10
LLMLingua-2
Poda semântica por ML via MobileBERT ONNX — segura para código e assíncrona
11
Ultra
Poda heurística de tokens com uma camada opcional de modelo pequeno (SLM)
12
OmniGlyph
Codificação experimental de contexto como imagem para o Claude Fable 5 medido na conexão direta com a Anthropic; os transformers do GPT 5.6 continuam bloqueados por padrão enquanto aguardam confirmações dos provedores. Quatro perfis de compactação (agressivo por padrão, equilibrado, seguro para programação, passagem direta) (mais agressivo; adesã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 ativo
🪨 Padrão (Caveman)
~30%
Programação cotidiana
⚡ Agressivo
~50%
Sessões longas com uso intenso de ferramentas
🔥 Ultra
~75%
Economia máxima
🧰 RTK
60–90%
Saídas de shell/test/build/git
🔗 Empilhado (RTK → Caveman)
78–95%
Prompts mistos + logs de ferramentas
**Exemplo real — modo Padrão:**
> **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 inline como prop, a comparação superficial do React o identifica como 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. Objeto inline como prop = nova referência = nova renderização. Envolva em useMemo."_
>
> **Mesma resposta. 72% menos tokens. Nenhuma 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, ajuste adaptativo e controle por requisição
Os 12 mecanismos acima reduzem o que entra. Outras três camadas definem **como**, **quando** e o que sai:
- **🪄 Estilos de saída** _(direcionamento no eixo de saída)_ — injetam instruções determinísticas e seguras para cache que moldam as respostas; são combináveis, cada uma com intensidade `lite` / `full` / `ultra`. Adicionar um estilo exige apenas uma linha no registro:
- **Prosa concisa** — remove preenchimento / artigos / ressalvas; mantém a substância técnica exata.
- **Menos código** — YAGNI de "dev sênior preguiçoso": a menor alteração funcional, sem estruturas não solicitadas.
- **Ponytail (dev sênior preguiçoso)** — sobe a escada do YAGNI, corrige a causa raiz, produz o menor diff funcional.
- **Tenho TDAH (ação primeiro)** — começa pela próxima ação, enumera as etapas, apresenta uma próxima etapa concreta, sem preâmbulo.
- **CJK conciso (文言)** — estilo ultraconciso em chinês clássico (restrito à localidade `zh`).
- **🎯 Orçamento de contexto adaptativo** _(o ajuste)_ — em vez de um único limite de tokens ligado/desligado, escala os mecanismos mais econômicos e com menor perda apenas até onde for necessário para **caber na janela de contexto do modelo**. Política: `reserve-output` (padrão, considera o modelo) · `percentage` · `absolute`. Modo: `floor` (garante que caiba) · `replace-autotrigger` (sua escolha explícita prevalece) · `off` (limite legado).
- **🎛️ Onde a compressão é decidida** _(precedência, alta → baixa)_ — cabeçalho `x-omniroute-compression` por requisição › substituição da combinação de roteamento › perfil nomeado ativo › adaptativo / acionamento automático › padrão do painel › desativada. O plano aplicado é retornado no cabeçalho de resposta `X-OmniRoute-Compression: ; source=`.
Configure o acionamento automático por limite de tokens, ative o ajuste adaptativo, fixe um perfil nomeado, defina uma configuração pontual por requisição ou atribua um pipeline por combinação de roteamento — o que melhor se adequar à carga de trabalho. Um **harness de avaliação** offline e opcional (`npm run eval:compression`) pontua fidelidade versus economia em um corpus fixado antes de você 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) 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).
> **Está usando npm 11 ou posterior?** O npm pode bloquear scripts de ciclo de vida de pacotes, a menos que sejam permitidos. O `postinstall` do OmniRoute (`node scripts/build/postinstall.mjs`) é necessário para preparar seus arquivos nativos de runtime. Ao instalar globalmente, permita os pacotes mencionados no aviso do npm. Para o conjunto de pacotes informado pelo OmniRoute 3.8.51:
>
> ```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 depois 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 de seus scripts de instalação.
> **Está usando o Gemini Web ou outro provedor baseado em cookies da web?** O pacote npm inclui
> o Playwright, mas não seu binário do Chromium. Consulte a observação sobre a
> [configuração do Chromium para Playwright](docs/guides/TROUBLESHOOTING.md#gemini-web-and-playwright-chromium)
> antes de fazer a primeira requisição ao 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 planos gratuitos podem exigir cadastro, aprovação ou um método de pagamento. Consulte o [Guia de planos 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 em Painel → Endpoints]
Modelo: auto (roteia entre conexões elegíveis — ou escolha o 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 na lista. 🎉 Pronto — comece a programar, e o OmniRoute fará o roteamento automático e usará alternativas quando necessário.
Se seu cliente não puder enviar cabeçalhos personalizados, o OmniRoute também disponibiliza aliases de compatibilidade com tokens:
```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 MCP com escopo · AES-256-GCM para dados em repouso · DOMPurify
Furtividade
wreq-js — simulação de impressão digital TLS JA3 / JA4, proxy de 3 níveis
Resiliência
Disjuntor, backoff exponencial, prevenção contra thundering herd, autorrecuperação por combinação automática
Registro de logs
pino — logs JSON estruturados com contexto da requisição
Testes
Executor de testes do Node.js + Vitest — mais de 39.000 declarações estáticas de testes em mais de 5.100 arquivos de teste rastreados (unitários, integração, E2E, segurança, ecossistema)
Estratégia de cobertura de testes para mais de 39.000 declarações estáticas de testes em mais de 5.100 arquivos de teste rastreados
# ⭐ Principais colaboradores
> O OmniRoute é moldado por uma comunidade apaixonada por código aberto. Essas pessoas fizeram contribuições excepcionais que afetam diretamente a qualidade, a estabilidade e o alcance do projeto. **Obrigado.**
### Colaboradores externos por pull requests mesclados
Dados congelados na ponta ativa de release/v3.8.50, no commit dafb4ae808, com merges até 2026-08-24 05:26:03 UTC. O censo paginado do GitHub GraphQL contém 5.911 PRs mesclados: 2.707 pelo proprietário do repositório, 179 pelo Dependabot e 3.025 PRs externos de 535 colaboradores distintos. “Linhas alteradas” corresponde às adições + exclusões do GitHub e inclui arquivos gerados, lockfiles, catálogos, traduções e documentação; representa a rotatividade do código, não as LOC de autoria. Empates no limite de corte são mantidos.
### Commits atribuídos pelo GitHub
Bob.Hou 🏅 51 commits atribuídos pelo GitHub · empate em 10º lugar
Xiangzhe 🏅 51 commits atribuídos pelo GitHub · empate em 10º lugar
Verificado novamente em 2026-08-24 06:14:31 UTC: commits atribuídos pelo GitHub, conforme informados pela API de Colaboradores do repositório para a branch padrão release/v3.8.50. A API retornou 525 identidades (415 usuários, 2 bots e 108 anônimas); esta tabela exclui o mantenedor, os bots e as identidades anônimas e preserva os empates na classificação. Ela é distinta tanto da classificação de PRs mesclados acima quanto do censo de 639 pessoas baseado nos metadados do Git abaixo.
> 🙏 Os recursos, as correções de bugs e as melhorias de infraestrutura feitos por esses colaboradores são uma **parte essencial** do que torna o OmniRoute confiável e rico em recursos. Cada pull request, cada caso de teste e cada arquivo de tradução i18n importa. O código aberto é construído por pessoas como eles.
---
## 💖 Patrocinadores
Um agradecimento especial às pessoas que financiam o OmniRoute do próprio bolso — cada contribuição mantém o projeto gratuito, independente e em constante evolução.
longtao 💛 Apoiador anterior com contribuição única
… e outras pessoas que preferem permanecer anônimas 💛Patrocinadores públicos do GitHub revalidados em 2026-08-24. O status activeOnly do GitHub determina os rótulos de atividade acima; apoiadores públicos com contribuições únicas divulgados anteriormente continuam sendo reconhecidos, e patrocinadores privados permanecem anônimos.💖 Torne-se um patrocinador → — cada dólar mantém o OmniRoute gratuito e independente.
## 👥 Mais de 600 colaboradores
[](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)
Auditado em 2026-08-24 na base congelada ac02c5b42f e verificado novamente na ponta ativa de release/v3.8.50, dafb4ae808: 639 identidades humanas normalizadas do Git — 407 aparecem como autores de commits (incluindo o mantenedor) e 232 aparecem apenas em trailers explícitos de Co-authored-by. O levantamento normaliza identificadores noreply do GitHub, exclui 26 identidades de bots/agentes/serviços/placeholders e não mescla endereços de e-mail comuns apenas porque seus nomes de exibição coincidem.
### Como contribuir
1. Faça um fork do repositório
2. Crie a branch a partir da ponta **ativa** de `release/vX.Y.Z` (não de `main`) — consulte [Modelo de branches e releases](docs/ops/BRANCHING_MODEL.md)
3. Crie sua branch de funcionalidade (`git checkout -b feat/amazing-feature`)
4. Faça o commit das suas alterações (`git commit -m 'feat: add amazing feature'`)
5. Envie para a branch (`git push origin feat/amazing-feature`)
6. Abra um Pull Request com a **base = essa branch `release/vX.Y.Z`**
Consulte [CONTRIBUTING.md](CONTRIBUTING.md) para obter diretrizes detalhadas.
### Publicando uma nova versão
```bash
# Crie uma release — npm publish acontece automaticamente
VERSION=x.y.z
gh release create "v${VERSION}" --title "v${VERSION}" --generate-notes
```
## 📊 Estrelas
## 🌍 StarMapper
## 🙏 Agradecimentos
O OmniRoute apoia-se sobre os ombros de gigantes. Ele começou como um fork do **[9router](https://github.com/decolua/9router)** e uma versão em 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 ajudou a moldar uma parte concreta do OmniRoute. Este é o nosso agradecimento a todos eles. 🙏
> ⭐ contagens de estrelas verificadas pela API REST do GitHub em 24 de agosto de 2026 — dê uma estrela a esses projetos. As contagens são um retrato exato daquela data e mudarão naturalmente.
### 🧬 Linhagem e gateway
O gateway de IA cujo conjunto público de dados de preços alimenta nossa sincronização de rastreamento de custos e cujo modelo de normalização de provedores serviu de base para nosso roteamento.
Código-fonte MIT adaptado para a ponte ChatGPT Web → Codex Responses incorporada, incluindo adaptadores de sessão do navegador, enquadramento de respostas, uso e pesquisa na web.
Padrões portados para recuperação de streaming, aliases sem raciocínio, pesquisa na web de contingência, limites de janela deslizante, ocultação de dados em logs e fluxos de inicialização reforçados.
Valores padrão de transformação compatíveis com o 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 Statsig de TypeError simulado, valores padrão de solicitação e dispositivo e processador de respostas NDJSON foram substancialmente adaptados para o executor Grok Web do OmniRoute.
A principal fonte transitiva de código por trás do grok2api-merged; suas implementações de modelo, cabeçalho, payload, Statsig e processador são preservadas na linhagem do Grok Web.
O código-fonte MIT subjacente para os valores padrão de payload e dispositivo do Grok, o gerador Statsig e o processador result.response, incorporado por meio do TQZHR e do grok2api-merged.
Uma fonte transitiva creditada pelo grok2api-merged por sua camada de pool de proxies; o OmniRoute preserva esse aviso de linhagem, mas não alega ter portado um pool de proxies em seu executor Grok Web de escopo limitado.
A implementação original do Grok Web consultou seu design upstream de HTTP/navegador; seu caminho HTTP direto deriva do GrokProxy, portanto não se alega uma portabilidade de código independente.
Seus esquemas Rust ChatOptions e de envelope de resposta serviram de base para os tipos TypeScript de solicitação e resposta de streaming do Grok no OmniRoute.
### 🗜️ Compressão de contexto e tokens — mecanismos
O projeto viral do tipo "por que usar muitos token se poucos token resolvem" — sua filosofia de fala das cavernas impulsiona nosso modo de compressão padrão e mais de 30 regras de remoção de palavras supérfluas/condensação.
Compressão de alto desempenho da saída de comandos — inspirou nosso mecanismo RTK, a DSL de filtros JSON, a recuperação da saída bruta e o pipeline encadeado RTK → Caveman.
Pesquisa sobre compressão de prompts (LLMLingua / LLMLingua-2) — inspirou nosso mecanismo llmlingua assíncrono, seguro para código e com tolerância a falhas.
Compressão de tokens em PT-BR — impulsiona nosso pacote de idioma pt-BR: redução de pleonasmos e remoção de palavras supérfluas ajustadas à gramática do português brasileiro.
A habilidade viral de programação YAGNI do "dev 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 de Caveman no eixo de saída para uma prosa concisa).
Compressão de saída sensível ao conteúdo e por tipo de arquivo, com interrupção em caso de falha — validou nosso despacho por tipo e a omissão quando o ganho é mínimo.
JSON colunar em Rust + recuperação endereçada por conteúdo + desduplicação entre mensagens — validou o design dos nossos mecanismos headroom/ccr/session-dedup e a invariante estável para cache de que a "forma comprimida independe da posição".
Kit de ferramentas da API do Compilador TypeScript — inspirou nossa remoção de comentários baseada em parser, que preserva literais de string, template e expressões regulares.
A interceptação/análise MITM do tráfego entre assistentes de programação ↔ LLM orientou os requisitos iniciais do Inspetor de Tráfego. Quatro módulos derivados anteriormente — mesclagem de SSE, normalização de conversas, mascaramento de segredos e sanitização de cabeçalhos — foram substituídos por implementações independentes de sala limpa, baseadas em padrões públicos de protocolo. As duas superfícies de passagem direta para o 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 transparente de proxy por processo — inspirou nosso encerramento de MITM seguro contra falhas, tempos limite de inatividade de soquetes, atribuição de processos via /proc e captura TPROXY.
### 📚 Dados de modelos, observabilidade e interface
Observabilidade da malha de serviços do Istio — inspirou nossos indicadores de disjuntor e elementos visuais de arestas com erro no Estúdio de Roteamento/Combinação.
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 desduplicação de solicitações, o fallback emergencial de custo zero, as estratégias conectáveis de Auto-Combo e a classificação multilíngue de intenções.
Seu remapeamento de modelos com reconhecimento de conta, a validação do caminho do executável e o comportamento dos rótulos de plano serviram de referência para o runtime Antigravity do OmniRoute.
Identificou a superfície de cota do Grok Build; em seguida, o OmniRoute verificou e corrigiu de forma independente o formato real dos dados transmitidos.
## 📄 Licença
Licença MIT — consulte [LICENSE](LICENSE) para mais detalhes.
---
**[⬆ Voltar ao topo](#-omniroute)** · Feito com ❤️ para a comunidade de IA de código aberto.
OmniRoute v3.8.52 · Node ≥22.22.2 · Licença MIT · omniroute.online
> Resumo animado da página `/dashboard/free-tiers` em tempo real. Metodologia completa (eliminação de duplicidades por pool, níveis de crédito, termos dos provedores): **[docs/reference/FREE_TIERS.md](docs/reference/FREE_TIERS.md)**.
>
> Esses números são auditados novamente a cada duas semanas em relação ao catálogo em tempo real e **variam nos dois sentidos** — se um provedor encerra um nível gratuito, o número diminui; se um novo é adicionado, ele aumenta. Publicamos o que o catálogo realmente calcula, nunca um melhor cenário arredondado para cima.
```bash
# Após conectar um provedor, copie sua chave do OmniRoute em Dashboard → 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 OpenCode Free e 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 Planos 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á passar para o próximo modelo íntegro elegível. 🛡️
### ⚡ Configuração zero — basta usar `auto`
Não é necessário criar um combo. Defina seu modelo como `auto` (ou uma variante), e o OmniRoute criará um combo virtual com base nos provedores conectados, pontuados em tempo real:
📖 [Mecanismo de combinação automática](docs/routing/AUTO-COMBO.md) · [Guia de resiliência](docs/architecture/RESILIENCE_GUIDE.md)
📊 Metodologia completa e detalhes por funcionalidade 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 é composta:
```txt
combinada = 1 − (1 − RTK) × (1 − Caveman_input)
média = 1 − (1 − 0.80) × (1 − 0.46) = 89.2%
intervalo = 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 tokens dão conta do recado?** Cada requisição passa pelo pipeline de compactaçã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 de diferentes maneiras para cada combinação de roteamento — com base em ideias do [RTK](https://github.com/rtk-ai/rtk), [Caveman](https://github.com/JuliusBrussee/caveman) (⭐ mais de 90 mil), [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, desativado e configurado de forma independente para cada combinação:
