## 💰 ~1,62 bi de tokens/mês em camadas gratuitas de terceiros
> **Traga suas próprias contas de provedores.** Esta é uma estimativa agregada de camadas gratuitas de terceiros elegíveis separadamente, não uma concessão de tokens da OmniRoute. Cadastre-se, obtenha credenciais quando necessário e conecte os provedores que você puder usar; cada provedor controla seus limites, disponibilidade e termos.
>
> Empilhar camadas gratuitas manualmente é doloroso — dezenas de SDKs, dezenas de limites de taxa e nenhuma ideia de quanto você realmente tem. A OmniRoute cataloga **467 entradas de camadas gratuitas em 34 chaves de pool recorrentes** e calcula o número principal de tokens a partir dos **17 pools com orçamento mensal positivo publicado, mais cinco limites por modelo da Groq**, deduplicados por pool compartilhado. Cotas que só são liberadas após uma verificação de identidade regional (hoje: ModelScope) são exibidas à parte, +~6M por trás da verificação de identidade regional, e nunca somadas ao número principal. O resultado permanece visível no dashboard (`/dashboard/free-tiers`).
> Resumo animado da página ao vivo `/dashboard/free-tiers`. Metodologia completa (deduplicação de pool, níveis de crédito, termos dos provedores): **[docs/reference/FREE_TIERS.md](docs/reference/FREE_TIERS.md)**.
>
> Esses números são reauditados a cada duas semanas em relação ao catálogo ao vivo e **mudam nos dois sentidos** — um provedor encerra uma camada gratuita e o número cai; um novo entra e ele sobe. Publicamos o que o catálogo realmente calcula, nunca um melhor cenário arredondado para cima.
⭐ Dê uma estrela no repositório se o OMNIROUTE ajudou você a economizar dinheiro e tornar seu trabalho mais fácil.
[](https://github.com/diegosouzapw/OmniRoute)
[](https://www.star-history.com/diegosouzapw/omniroute)
[](https://olud.ai/project/diegosouzapw-omniroute.html)
### 💬 Junte-se à comunidade
**👋 Siga o mantenedor — receba novos provedores, lançamentos e dicas primeiro:**
[](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)
**Perguntas, dicas de 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
## 🧩 Disponível
[](https://www.npmjs.com/package/omniroute)
[](https://hub.docker.com/r/diegosouzapw/omniroute)
[](LICENSE)
## 🆓 Instale, conecte um provedor e, em seguida, 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 nenhum destino sem chave elegível, e um provedor sem chave pode rejeitar clientes de terceiros. Provedores marcados como `tos: avoid`, incluindo o 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)**.
## ✨ Novidades
> Destaques recentes da **v3.8.20 → v3.8.53**. Histórico completo em [`CHANGELOG.md`](CHANGELOG.md).
- **⚖️ Roteamento `quota-weighted`** — a 20ª estratégia de combo ignora contas com a cota esgotada e, em seguida, escolhe entre as demais proporcionalmente à 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 de 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 a um modelo ou combo com `forcedModel` e adicione ou remova, de forma atômica, os modelos e combos de uma chave (`/api/keys/{id}/access`). → [Referência da API](docs/reference/API_REFERENCE.md) · [OpenAPI](docs/openapi.yaml)
- **🛡️ Controles de PII mais granulares** — seleção por tipo, até 20 padrões personalizados de mascaramento validados e contadores de detecção por tipo; o mascaramento em si continua sendo opcional. → [Proteções](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 Cartão do Agente e um painel com conversa 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 (com 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 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 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** — divide de forma justa a cota de uma conta compartilhada entre chaves agrupadas, preservando a utilização ao emprestar as parcelas 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 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 ciente da tarefa e 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 em duas camadas, 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 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), proteção opcional de mascaramento de credenciais (oculta 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 painel (o login por senha permanece sempre disponível). → [Proteções](docs/security/GUARDRAILS.md)
- **🖼️ Novos endpoints** — `/v1/ocr` (Mistral OCR) e `/v1/audio/translations` (estilo Whisper) completam a interface 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: xAI Grok Imagine e vídeo da 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` de proxy reverso, detecção automática do idioma do navegador, rastreamento de dispositivos por chave, confiança em MITM sem root, localização zh-TW. → [Ambiente](docs/reference/ENVIRONMENT.md)
- **🤝 Mais provedores e agentes** — agentes de nuvem (Codex Cloud, Cursor, Devin, Jules), Grok Build (xAI) com navegador + login OAuth, cartão de primeira classe para 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 375 provedores**. → [Provedores](docs/reference/PROVIDER_REFERENCE.md)
- **📡 Transparência de roteamento** — cada resposta inclui um cabeçalho `X-OmniRoute-Decision` que identifica a estratégia/provedor/latência responsável, uma nova estratégia de combo `cache-optimized` + o fator `cacheAffinity` do Auto-Combo direcionam solicitações repetidas de volta à 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 local e infraestrutura** — um Redis local, implantadores de relay no 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 cofre Obsidian (22 ferramentas MCP), APIs Batch e Files compatíveis com OpenAI, cache semântico de respostas, gamificação com rankings, descoberta de agentes ACP (15 agentes integrados), exportação agendada de logs para o BigQuery, fan-out paralelo multimodelo `auto/chaos`, uma ponte de bot do Telegram, um gerenciador de versões no aplicativo e rankings de provedores gratuitos LMArena-ELO. → [Documentação](docs/README.md)
## 🤖 CLIs e agentes de programação compatíveis
> Uma única configuração — `http://localhost:20128/v1` — e **todos** os 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 específica de cada uma das 37 ferramentas (27 CLI Code + 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** — sem gravar arquivos de configuração,
com credenciais injetadas por processo e um diretório inicial isolado e descartável para Qwen/Gemini:
```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 5dive
```
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 shell. → [Integrações de CLI](docs/guides/CLI-INTEGRATIONS.md)
## 🌐 375 provedores de IA — 153 marcados no catálogo como gratuitos
> **375 provedores registrados** nas coleções canônicas de chat, mídia, busca, local, agente em nuvem e sistema, incluindo **153 que carregam os 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 **467 linhas por modelo**, **34 pools recorrentes** e **51 provedores gratuitos para sempre, recorrentes/sem chave**. Esses são denominadores diferentes por design; as definições e os cálculos com deduplicação de pools estão em [Referência de Provedores](docs/reference/PROVIDER_REFERENCE.md) e [Camadas Gratuitas](docs/reference/FREE_TIERS.md).
### 🏢 Todos os principais laboratórios — por 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 ao vivo a partir do catálogo de provedores do dashboard. 📖 [Referência de Provedores](docs/reference/PROVIDER_REFERENCE.md)
### 🆓 Grátis para sempre — US$ 0, sem cartão
OpenCode Zen DeepSeek V4, Nemotron 3 Sem limite de tokens
Kilo Code Auto-router, Tencent Hy3 Grátis para sempre
Requesty GPT-OSS 120B, Nemotron Grátis para sempre
SiliconFlow DeepSeek V3.2 / R Nível 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 Sem necessidade de chave
Cloudflare AI 50+ modelos 10K neurônios/dia
NVIDIA NIM GLM, MiniMax ~40 RPM grátis
Cerebras GLM 4.7, GPT-OSS Crédito único de $5
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 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 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 15–95% de Tokens — Automaticamente
### 📖 Como funciona — pipeline, arquitetura e a matemática da economia
O combo empilhado padrão executa `RTK → Caveman`. Quando ambos atuam sobre o mesmo payload de ferramenta/contexto, as economias se acumulam:
```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 motor de preservação.
> **Por que usar muitos tokens quando poucos tokens resolvem?** Toda requisição passa pelo pipeline de compressão do OmniRoute **de forma transparente** — sem alterações no cliente. Agora é uma **pilha de 12 motores combináveis** que rodam em ordem e se misturam e combinam por combo de roteamento — construída sobre ideias do [RTK](https://github.com/rtk-ai/rtk), do [Caveman](https://github.com/JuliusBrussee/caveman) (⭐ 90K+), do [LLMLingua-2](https://github.com/microsoft/LLMLingua) e do [Troglodita](https://github.com/leninejunior/troglodita) (PT-BR).
### 🧱 A pilha de 12 motores
Os motores rodam na ordem do pipeline; cada um é ativável e configurável de forma independente por combo:
#
Motor
O que faz
1
Session-Dedup
Descarta conteúdo repetido entre turnos (endereçado por conteúdo, entre turnos)
2
CCR
Arquiva blocos grandes atrás de marcadores de recuperação, buscados sob demanda
3
Lite
Aparo de espaços em branco + URLs de imagem (linha de base de baixa latência)
4
RTK
Filtragem inteligente de resultados de ferramentas, dedup e truncamento (ciente do comando)
5
Responses Tool Output
JSON com prioridade a lossless + compressão diagnóstica limitada para saídas de shell/patch/search/build (Responses API)
6
Headroom
Compactação tabular sem perdas de arrays JSON (~30%) via um codec GCF vendorizado
7
Relevance
Pontuação extrativa de frases em relação à ú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 por 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 de contexto como imagem, medida no Claude Fable 5 no fio direto da Anthropic; os transformers do GPT 5.6 permanecem fail-closed até o recebimento de comprovantes do provedor. Quatro perfis de compressão (aggressive como padrão, balanced, coding-safe, passthrough) (o mais agressivo; opt-in)
Blocos de código, URLs e dados estruturados são **sempre preservados** byte a byte. **Presets de um clique** combinam os motores:
Modo
Economia
Melhor para
🪶 Lite
~15%
Padrão seguro sempre ativo
🪨 Standard (Caveman)
~30%
Programação do dia a dia
⚡ Aggressive
~50%
Sessões longas com muitas ferramentas
🔥 Ultra
~75%
Economia máxima
🧰 RTK
60–90%
Saída de shell/test/build/git
🔗 Stacked (RTK → Caveman)
78–95%
Prompts variados + logs de ferramentas
**Exemplo real — modo Standard:**
> **Antes (69 tokens):** _"The reason your React component is re-rendering is likely because you're creating a new object reference on each render cycle. When you pass an inline object as a prop, React's shallow comparison sees it as a different object every time, which triggers a re-render. I would recommend using useMemo to memoize the object."_
>
> **Depois (19 tokens):** _"New object ref each render. Inline object prop = new ref = re-render. Wrap in useMemo."_
>
> **Mesma resposta. 72% menos tokens. Zero perda de precisão.** ✅
**Exemplo PT-BR — modo [Troglodita](https://github.com/leninejunior/troglodita):**
> **Antes (42 tokens):** _"O problema é que o componente está re-renderizando porque uma nova referência de objeto está sendo criada em cada ciclo de renderização. Eu recomendaria usar useMemo."_
>
> **Depois (12 tokens):** _"Re-render: ref nova cada ciclo (objeto inline recriado). Usar `useMemo`."_
>
> **Mesma resposta. ~70% menos tokens. Precisão técnica intacta.** ✅
### 🎚️ Além dos engines — estilos de saída, o dial adaptativo e controle por requisição
Os 12 engines acima reduzem o que **entra**. Mais três camadas moldam **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 a resposta; combináveis, cada uma com intensidade `lite` / `full` / `ultra`. Adicionar um estilo é uma entrada de uma linha no registro:
- **Terse prose** — elimina enrolação / artigos / hedging; mantém a substância técnica exata.
- **Less code** — YAGNI de "dev sênior preguiçoso": menor mudança funcional, sem scaffolding não solicitado.
- **Ponytail (lazy senior dev)** — sobe a escada YAGNI, corrige a causa raiz, menor diff funcional.
- **I have ADHD (action-first)** — a próxima ação vem primeiro, passos numerados, um próximo passo concreto, sem preâmbulo.
- **Terse CJK (文言)** — estilo ultraconciso em chinês clássico (com locale restrito a `zh`).
- **🎯 Orçamento de contexto adaptativo** _(o dial)_ — em vez de um único limite de tokens on/off, escala apenas os engines mais baratos e com menor perda até o necessário para **caber na janela de contexto do modelo**. Política: `reserve-output` (padrão, ciente do modelo) · `percentage` · `absolute`. Modo: `floor` (garante o encaixe) · `replace-autotrigger` (sua escolha explícita prevalece) · `off` (limite legado).
- **🎛️ Onde a compressão é decidida** _(precedência, da maior para a menor)_ — header `x-omniroute-compression` por requisição › override do combo de roteamento › perfil nomeado ativo › adaptativo / auto-trigger › padrão do painel › desligado. O plano aplicado é ecoado no header de resposta `X-OmniRoute-Compression: ; source=`.
Auto-trigger por limite de tokens, ativar o dial adaptativo, fixar um perfil nomeado, definir algo pontual por requisição ou atribuir um pipeline por combo de roteamento — o que se encaixar melhor na carga de trabalho. Um **harness de avaliação** offline opcional (`npm run eval:compression`) pontua fidelidade vs. economia em um corpus fixo antes de você promover uma mudança.
📖 [`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
```
> 💡 Está vendo `npm warn ERESOLVE` ou avisos de peer-dep? [Eles são inofensivos](docs/guides/TROUBLESHOOTING.md#npm-install-warnings-eresolve--peer--deprecated).
> **Usando npm 11 ou posterior?** O npm pode bloquear scripts de ciclo de vida de pacotes a menos que eles sejam permitidos. O `postinstall` do OmniRoute (`node scripts/build/postinstall.mjs`) é necessário para preparar seus arquivos nativos de runtime. Permita os pacotes indicados no aviso do npm ao instalar globalmente. Para o conjunto de pacotes reportado pelo OmniRoute 3.8.53:
>
> ```bash
> npm install -g --allow-scripts=omniroute,keytar,onnxruntime-node,@parcel/watcher,@swc/core,protobufjs,esbuild omniroute
> ```
>
> Para reutilizar esta allowlist 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 reportar uma lista diferente, use os nomes de pacote daquele aviso. Permitir um pacote autoriza a execução de seus scripts de instalação.
> **Usando Gemini Web ou outro provedor de cookie web?** O pacote npm inclui
> o Playwright, mas não o binário do Chromium. Consulte a
> nota de [configuração do Chromium no Playwright](docs/guides/TROUBLESHOOTING.md#gemini-web-and-playwright-chromium)
> antes de fazer a primeira requisição a um provedor web.
Dashboard em `http://localhost:20128` · API em `http://localhost:20128/v1`.
**2) Conecte um provedor elegível usando sua própria conta**
Dashboard → **Providers** → escolha um provedor cujos termos e cota atuais se encaixem no seu caso de uso → adicione a chave de API ou conclua o fluxo de conta dele. Níveis gratuitos podem exigir cadastro, aprovação ou meio de pagamento. Consulte o [Guia de Níveis Gratuitos](docs/getting-started/FREE-TIERS-GUIDE.md); a disponibilidade sem chave não é garantida, e provedores marcados como `tos: avoid` são excluídos do `auto` por padrão.
**3) Aponte sua ferramenta de programação**
```txt
Base URL: http://localhost:20128/v1
API Key: [copy from Dashboard → Endpoints]
Model: auto (routes among eligible connections — or choose provider/model)
```
**4) Verifique se está funcionando**
```bash
curl http://localhost:20128/v1/models -H "Authorization: Bearer YOUR_KEY"
```
Você deve ver seus modelos conectados listados. 🎉 É isso — comece a programar, e o OmniRoute faz o roteamento automático e o fallback para você.
Se seu cliente não consegue enviar headers personalizados, o OmniRoute também expõe aliases de compatibilidade com token:
```txt
OpenAI catalog: http://localhost:20128/vscode/YOUR_KEY/
OpenAI models: http://localhost:20128/vscode/YOUR_KEY/models
OpenAI chat: http://localhost:20128/vscode/YOUR_KEY/chat/completions
OpenAI responses: http://localhost:20128/vscode/YOUR_KEY/responses
Ollama chat: http://localhost:20128/vscode/YOUR_KEY/api/chat
Ollama tags: http://localhost:20128/vscode/YOUR_KEY/api/tags
```
Use esses aliases apenas para clientes que não conseguem anexar `Authorization: Bearer ...`. A autenticação por header continua sendo o modo preferido.
## 📦 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 + API Keys + autenticação com escopo MCP · AES-256-GCM em repouso · DOMPurify
Furtividade
wreq-js — impersonação de fingerprint TLS JA3 / JA4, proxy de 3 níveis
Resiliência
Circuit breaker, backoff exponencial, anti-thundering-herd, auto-combo com autocura
Registro de logs
pino — logs JSON estruturados com contexto de requisição
Testes
Node.js test runner + Vitest — 56.000+ declarações estáticas de teste em 7.800+ arquivos de teste rastreados (unidade, integração, E2E, segurança, ecossistema)
Estratégia de cobertura de testes para mais de 56.000 declarações de teste estáticas em mais de 7.800 arquivos de teste rastreados
# ⭐ Principais Contribuidores
> O OmniRoute é moldado por uma comunidade open-source apaixonada. Essas pessoas fizeram contribuições excepcionais que impactam diretamente a qualidade, a estabilidade e o alcance do projeto. **Obrigado.**
### Contribuidores externos por pull requests mesclados
Censo realizado em 2026-10-18 15:09:09 UTC com a ponta ativa de release/v3.8.52656f01cb43. O censo paginado do GitHub GraphQL contém 9.191 PRs mesclados: 3.834 do proprietário do repositório, 229 do Dependabot, 6 de outros bots/apps e 5.122 PRs externos de 835 contribuidores distintos. “Linhas alteradas” é a soma de adições + exclusões do GitHub e inclui arquivos gerados, lockfiles, catálogos, traduções e documentação; é churn, não LOC de autoria. 49 PRs relatam diffs do GitHub acima de 500.000 linhas (por exemplo, #13399, uma única adição de provedor, lista 2.347 arquivos alterados), o que infla vários totais acima. Empates são classificados em conjunto.
### Commits atribuídos ao GitHub
Verificado novamente em 2026-10-18 14:44:45 UTC: commits atribuídos pelo GitHub e informados pela API de Colaboradores do repositório para a branch padrão release/v3.8.52. A API retornou 849 identidades (429 usuários, 2 bots, 418 anônimas); esta tabela exclui o mantenedor, bots e identidades anônimas e mantém os empates na classificação. Ela é diferente tanto da classificação 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 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 elas.
---
## 💖 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 900 colaboradores
[](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)
Auditado em 2026-10-18 na ponta ativa de release/v3.8.52, commit ad160ab2d1 (6.826 commits): 993 identidades humanas normalizadas do Git — 707 aparecem como autores de commits (incluindo o mantenedor) e 286 apenas em trailers explícitos de Co-authored-by. O levantamento aplica o .mailmap, compara endereços de e-mail sem diferenciar maiúsculas de minúsculas, une endereços noreply numéricos e simples do GitHub somente quando codificam o mesmo identificador, 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. A auditoria de 2026-08-24 publicou 639; uma nova execução deste método sobre a base ac02c5b42f daquela 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 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 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 = aquela branch `release/vX.Y.Z`**
Consulte [CONTRIBUTING.md](CONTRIBUTING.md) para obter diretrizes detalhadas.
### Lançando uma nova versão
```bash
# Crie uma release — a publicação no npm acontece automaticamente
VERSION=x.y.z
gh release create "v${VERSION}" --title "v${VERSION}" --generate-notes
```
## 📊 Estrelas
## 🌍 StarMapper
## 🙏 Agradecimentos
O OmniRoute se apoia sobre os ombros de gigantes. Ele começou como um fork do **[9router](https://github.com/decolua/9router)** e como 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 moldou uma parte concreta do OmniRoute. Este é o nosso agradecimento a todos eles. 🙏
> ⭐ contagens de estrelas verificadas por meio da API REST do GitHub em 18 de outubro de 2026 — dê uma estrela a esses projetos. As contagens são um retrato exato daquela data e naturalmente mudarão.
### 🧬 Linhagem e gateway
O gateway de IA cujo conjunto público de dados de preços alimenta nossa sincronização de monitoramento de custos e cujo modelo de normalização de provedores orientou nosso roteamento.
Código-fonte MIT adaptado para a ponte incorporada ChatGPT Web → Codex Responses, incluindo adaptadores de sessão do navegador, estruturação de respostas, uso e pesquisa na web.
Padrões portados para recuperação de streams, aliases sem raciocínio, pesquisa na web alternativa, limites de janela deslizante, ocultação de dados em logs e fluxos reforçados de inicialização.
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 com TypeError simulado, padrões de requisição e dispositivo e processador de respostas NDJSON foram substancialmente adaptados ao executor Grok Web do OmniRoute.
A principal fonte transitiva de código por trás do grok2api-merged; suas implementações de modelos, cabeçalhos, payloads, Statsig e processadores são preservadas na linhagem do Grok Web.
O código-fonte MIT subjacente para os padrões de payload e dispositivo do Grok, o gerador Statsig e o processador result.response, incorporados 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 reivindica uma adaptação do pool de proxies em seu executor Grok Web de escopo limitado.
A implementação original do Grok Web consultou seu design de upstream via HTTP/navegador; seu caminho HTTP direto deriva do GrokProxy, portanto não se reivindica nenhuma adaptação independente de código.
### 🗜️ Contexto e compactação de tokens — mecanismos
O projeto viral "por que usar muitos token quando poucos token resolvem" — sua filosofia de fala de homem das cavernas é a base do nosso modo de compressão padrão e de mais de 30 regras de remoção de termos supérfluos e condensação.
Compressão de saída de comandos de alto desempenho — inspirou nosso mecanismo RTK, a DSL de filtros JSON, a recuperação da saída bruta e o pipeline empilhado RTK → Caveman.
Pesquisa sobre compressão de prompts (LLMLingua / LLMLingua-2) — inspirou nosso mecanismo llmlingua assíncrono, seguro para código e com continuidade em caso de falha.
Compressão de tokens em PT-BR — é a base do nosso pacote de idioma pt-BR: redução de pleonasmos e remoção de termos supérfluos ajustadas à gramática do português brasileiro.
A habilidade viral de programação YAGNI do "desenvolvedor sênior preguiçoso" — inspirou nosso Estilo de Saída less-code: orientação para a menor alteração funcional, que reduz o código _gerado_ (a contraparte no eixo da saída à prosa concisa do Caveman).
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 é inferior ao mínimo.
JSON colunar em Rust + recuperação endereçada por conteúdo + desduplicação entre mensagens — validou o design de 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 embasou 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 ao 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 MITM seguro em caso de falhas, tempos limite de inatividade de sockets, atribuição de processos via /proc e captura TPROXY.
### 📚 Dados de modelos, observabilidade e interface
Observabilidade da malha de serviços Istio — inspirou nossos indicadores de disjuntores e elementos visuais de arestas com erro no Routing/Combo Studio.
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 de custo zero, as estratégias plugáveis de Auto-Combo e a classificação multilíngue de intenções.
Seu remapeamento de modelos baseado em contas, a validação de caminhos de executáveis e o comportamento dos rótulos de planos embasaram o runtime Antigravity do OmniRoute.
Identificou a superfície de cotas 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 obter detalhes.
---
**[⬆ Voltar ao topo](#-omniroute)** · Feito com ❤️ para a comunidade de IA de código aberto.
OmniRoute v3.8.53 · Node ≥22.22.2 · Licença MIT · omniroute.online
> Resumo animado da página ao vivo `/dashboard/free-tiers`. Metodologia completa (deduplicação de pool, níveis de crédito, termos dos provedores): **[docs/reference/FREE_TIERS.md](docs/reference/FREE_TIERS.md)**.
>
> Esses números são reauditados a cada duas semanas em relação ao catálogo ao vivo e **mudam nos dois sentidos** — um provedor encerra uma camada gratuita e o número cai; um novo entra e ele sobe. 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 nenhum destino sem chave elegível, e um provedor sem chave pode rejeitar clientes de terceiros. Provedores marcados como `tos: avoid`, incluindo o 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)
O combo empilhado padrão executa `RTK → Caveman`. Quando ambos atuam sobre o mesmo payload de ferramenta/contexto, as economias se acumulam:
```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 motor de preservação.
> **Por que usar muitos tokens quando poucos tokens resolvem?** Toda requisição passa pelo pipeline de compressão do OmniRoute **de forma transparente** — sem alterações no cliente. Agora é uma **pilha de 12 motores combináveis** que rodam em ordem e se misturam e combinam por combo de roteamento — construída sobre ideias do [RTK](https://github.com/rtk-ai/rtk), do [Caveman](https://github.com/JuliusBrussee/caveman) (⭐ 90K+), do [LLMLingua-2](https://github.com/microsoft/LLMLingua) e do [Troglodita](https://github.com/leninejunior/troglodita) (PT-BR).
### 🧱 A pilha de 12 motores
Os motores rodam na ordem do pipeline; cada um é ativável e configurável de forma independente por combo:
