## 💰 ~1.62B de tokens/mês em níveis gratuitos de terceiros
> **Use as suas próprias contas de fornecedores.** Este é um total agregado estimado de níveis gratuitos de terceiros, para os quais existe elegibilidade separada, e não uma atribuição de tokens da OmniRoute. Registe-se, obtenha credenciais quando necessário e ligue os fornecedores que pode utilizar; cada fornecedor controla os respetivos limites, disponibilidade e termos.
>
> Combinar manualmente níveis gratuitos é penoso — dezenas de SDKs, dezenas de limites de pedidos e nenhuma noção da quantidade realmente disponível. A OmniRoute cataloga **471 entradas de níveis gratuitos em 34 chaves de pools recorrentes** e calcula o total de tokens apresentado a partir dos **17 pools com um orçamento mensal positivo publicado, mais cinco limites da Groq por modelo**, com desduplicação por pool partilhado. As quotas que só ficam disponíveis após uma verificação de identidade regional (atualmente: ModelScope) são apresentadas separadamente, +~6M após verificação de identidade regional, e nunca são adicionadas ao total apresentado. O resultado permanece visível no painel (`/dashboard/free-tiers`).
> Resumo animado da página dinâmica `/dashboard/free-tiers`. Metodologia completa (desduplicação de pools, níveis de créditos, termos dos fornecedores): **[docs/reference/FREE_TIERS.md](docs/reference/FREE_TIERS.md)**.
>
> Estes valores são novamente auditados a cada duas semanas em comparação com o catálogo em produção e **podem variar em ambos os sentidos** — se um fornecedor terminar um nível gratuito, o número desce; se surgir um novo, aumenta. Publicamos aquilo que o catálogo realmente calcula, nunca um cenário otimista arredondado por excesso.
⭐ Dê uma estrela ao repositório se a OMNIROUTE o ajudou a poupar dinheiro e a facilitar o seu trabalho.
[](https://github.com/diegosouzapw/OmniRoute)
[](https://www.star-history.com/diegosouzapw/omniroute)
[](https://olud.ai/project/diegosouzapw-omniroute.html)
### 💬 Junte-se à comunidade
**👋 Siga o responsável pela manutenção — seja o primeiro a receber novidades sobre fornecedores, versões e sugestões:**
[](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, sugestões de fornecedores, roteiro e apoio → [Discord](https://discord.gg/U47eFqAXCn) · [Telegram](https://t.me/omnirouteOficial) · WhatsApp [🌍 Global](https://chat.whatsapp.com/FvuCbrpZmQ6I85n2vW5QIC?s=cl&p=a&mlu=4) / [🇧🇷 Brasil](https://chat.whatsapp.com/KWgatljAjmbELQory59Oti?s=cl&p=a&mlu=4) / [Portal](https://portal.sthub.com.br/communities/groups/st-hub/channels/Omniroute-World-8kRjmK)**
## 📈 O Gateway continua a crescer
| | v3.8.50 | **v3.8.51** | `v3.8.53+` |
| ------------------------------------------- | :----------------------: | :---------: | :---------------------: |
| 🌐 Fornecedores | 352 | **358** | 375 |
| 🧠 IDs únicos de modelos de chat | 1320 | **1374** | 1475 |
| 🖼️ Ponte de modalidades | 🆕 visão + áudio + vídeo | ✓ | ✓ |
| 📡 Catálogo gratuito do Radar | 🆕 adesão opcional | ✓ | ✓ |
| ⚖️ Agendamento com reconhecimento de quotas | 🆕 Quota-Share | ✓ | ✓ |
| 📊 Telemetria de quotas | 🆕 em tempo real | ✓ | ✓ |
| 🧰 Modo headless | — | — | 🆕 `serve --headless` |
| 🛤️ Infraestrutura de via LTS | — | — | 🆕 canais de lançamento |
| 🔎 API de descoberta de modelos | — | — | 🆕 `/v1/models/query` |
**→ [Roteiro](ROADMAP.md) — a seguir a via até `v3.9.0 LTS`**
## 🧩 Disponível
[](https://www.npmjs.com/package/omniroute)
[](https://hub.docker.com/r/diegosouzapw/omniroute)
[](LICENSE)
## 🆓 Instale, ligue um fornecedor e depois encaminhe através de um único endpoint
```bash
# Depois de ligar um fornecedor, copie a sua chave 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 sem chave elegíveis, e um fornecedor sem chave pode rejeitar clientes de terceiros. Os fornecedores marcados como `tos: avoid`, incluindo o Kiro, são excluídos do encaminhamento automático por predefinição; ligar uma conta não substitui essa definição. Consulte o [Guia de Planos Gratuitos](docs/getting-started/FREE-TIERS-GUIDE.md) antes de escolher um fornecedor.📦 Scripts de início rápido para copiar e colar em **Python, Node.js, PHP e cURL** → [`examples/quickstart/`](examples/quickstart/)
# 💥 A Promessa
# 🤔 Porquê o OmniRoute?
## 🤝 Apoiado pelos nossos Amigos de Código Aberto
> **Quer juntar-se como Amigo de Código Aberto?** Estas são as empresas que apoiam o código aberto e ajudam a manter o OmniRoute em movimento — e nós dizemos publicamente para onde vai cada token que nos dão. Contacte-nos: [diegosouza.pw@outlook.com](mailto:diegosouza.pw@outlook.com)
Kimi Moonshot AI
Obrigado à Kimi (Moonshot AI), o nosso Amigo Fundador de Código Aberto, por apoiar este projeto! A Kimi é o laboratório de IA por trás das famílias de modelos de peso aberto K2 e K3 — o Kimi K3 oferece uma janela de contexto de 1M de tokens, visão nativa e codificação de nível de fronteira a uma fração dos preços dos modelos fechados, e funciona de imediato com Claude Code, Codex e todas as ferramentas de codificação que o OmniRoute serve.
O que o apoio da Kimi impulsiona: Os créditos da API da Kimi alimentam o pipeline de lançamento validado por IA do OmniRoute — a fase de validação de fusão impulsionada pelo Kimi K3 que revê cada pull request antes de ser enviada — além do desenvolvimento diário de funcionalidades. O suporte de primeira classe da Kimi é enviado em ambas as vias: a API direta da Kimi (kimi-k3) e o plano de codificação Kimi Code (OAuth e chave API). O OmniRoute é também o primeiro projeto de código aberto brasileiro no programa de apoio da Kimi. Obtenha uma chave API da Kimi com 15% de créditos extra →
Cheaper Inference cheaperinference.com
Obrigado à Cheaper Inference, um Amigo de Código Aberto do OmniRoute, por apoiar este projeto! A Cheaper Inference é um gateway classificado por custo que revende 42 modelos de fronteira — Claude, GPT-5.x, Gemini, Kimi K3, GLM, DeepSeek, Grok e MiniMax — por trás de um único endpoint compatível com OpenAI, encaminhando cada pedido para o fornecedor elegível mais barato sem nunca cobrar acima do preço de tabela do criador do modelo.
Suporte de primeira classe no OmniRoute: Chat Completions, o endpoint nativo /v1/responses, visão, chamada de ferramentas e 3 modelos de imagem (grok-imagine, nano-banana-pro, nano-banana-2, acessíveis como cheaperinference/<model>). Obtenha uma chave API →
Os links marcados com aff=omniroute são links de parceiros. Eles financiam o projeto sem custo adicional para si. 🎟️ Promoção de Afiliados — cupões de inscrição gratuitos de fornecedores que não patrocinamos (clique para expandir)Esta secção destina-se apenas a códigos de referência/cupão. As parcerias patrocinadas encontram-se em 🤝 Apoiado pelos nossos Amigos de Código Aberto acima. O OmniRoute não tem patrocínio ou parceria com os fornecedores aqui listados — estes são cupões públicos que qualquer pessoa pode usar.
AgentRouter agentrouter.org
AgentRouter — inscrição de afiliado · $100 em créditos gratuitos na inscrição (servidor gratuito, espere maior latência — melhor para testes, não para produção). Suporte de primeira classe no OmniRoute desde a v3.8.50: Chat Completions, o formato de comunicação compatível com Anthropic e o caminho compatível com OpenAI. Os modelos disponíveis incluem claude-opus-4-8, claude-opus-5, gpt-5.6-sol e mais. Agarre os seus $100 →
⚠️ Link de afiliado — O OmniRoute não tem patrocínio ou parceria com este fornecedor.
Conhece outro fornecedor com um cupão de inscrição gratuito generoso que beneficie os utilizadores do OmniRoute? Abra uma issue e nós adicioná-lo-emos aqui.
## 🎯 Combos — A Funcionalidade Principal
> Um **combo** é uma cadeia de modelos entre os quais o OmniRoute encaminha pedidos **automaticamente**. Se a quota se esgotar, um fornecedor falhar ou os custos dispararem, o combo pode avançar para o modelo elegível e operacional seguinte. 🛡️
### ⚡ Sem configuração — basta usar `auto`
Não é necessário criar nenhum combo. Defina o seu modelo como `auto` (ou uma variante) e o OmniRoute cria um combo virtual a partir dos fornecedores ligados, avaliados em tempo real:
ID do modelo
O que otimiza
auto
🎯 Predefinição equilibrada (LKGP — mantém o último fornecedor que funcionou corretamente)
auto/coding
🧑💻 Ponderações que dão prioridade à qualidade na geração de código
auto/fast
⚡ Menor latência em primeiro lugar
auto/cheap
💰 Menor custo por token em primeiro lugar
auto/subscription
🎟️ Apenas a quota da subscrição que já paga — falha de forma fechada, sem nunca recorrer a uma alternativa faturável (guia)
auto/thrifty
🪜 Primeiro a quota do plano e, depois, um nível de cada vez até às opções pagas mais baratas — regressa ao plano após a reposição da quota (guia)
auto/offline
🔋 Maior margem de quota/limite de pedidos em primeiro lugar
auto/smart
🔭 Prioridade à qualidade + 10% de exploração para descobrir modelos melhores
auto/lkgp
📌 Afinidade explícita com o último fornecedor que funcionou corretamente
auto/chaos
🧪 Distribuição paralela por um painel de modelos (um por fornecedor, 5 por predefinição), devolvendo uma resposta; uma chamada a montante por modelo do painel, não se trata de injeção de falhas
##
### 🔀 Ou crie o seu próprio combo — 20 estratégias de encaminhamento
Todas as **20** estratégias — combine-as livremente em cada etapa do combo:
#
Estratégia
O que faz
1
priority
Lista ordenada pelo primeiro destino — esgota cada um antes de avançar para o seguinte 🥇
2
fill-first
Utiliza totalmente a quota de cada destino antes de avançar
3
weighted
Seleção aleatória ponderada pelo peso de cada destino
4
round-robin
Percorre ciclicamente os destinos por ordem
5
p2c
Balanceamento de carga aleatório pelo método de escolha entre duas opções
6
least-used
Seleciona o destino com a menor carga atual
7
random
Seleção aleatória uniforme (sem duplicados)
8
strict-random
Seleção aleatória sem eliminar repetições 🎲
9
cost-optimized
Minimiza o custo por pedido com base nos preços do catálogo em tempo real 💸
10
headroom
Seleciona o destino com a maior quota restante
11
quota-weighted
Ignora contas esgotadas e, depois, seleciona proporcionalmente à quota restante ÷ carga em curso — as conversas existentes permanecem fixadas ⚖️
12
reset-window
Prefere o destino cuja janela de quota é reposta mais cedo
13
reset-aware
Ordena pela hora de reposição da quota — janelas curtas primeiro 📊
14
context-relay
Transfere o contexto entre destinos em conversas longas 🧠
15
context-optimized
Seleciona a opção mais adequada ao tamanho do contexto atual
16
cache-optimized
Fixa cada prefixo reutilizável do pedido à mesma conta — maximiza as correspondências na cache de pedidos 🎯
17
lkgp
Último Caminho Conhecido como Funcional — fixa o último fornecedor bem-sucedido e, depois, recorre às regras como alternativa
18
auto
Avaliação em tempo real com 16 fatores para todas as ligações 🤖
19
fusion
Distribui o pedido por um painel de modelos + um avaliador sintetiza uma única resposta 🧬
20
pipeline
Encadeia etapas — a saída de cada destino alimenta o seguinte 🔗
O motor Auto-Combo classifica cada candidato com base em **16 fatores** (estado, quota, custo, latência, adequação à tarefa, qualidade, disponibilidade da sessão…) — consulte [`docs/routing/AUTO-COMBO.md`](docs/routing/AUTO-COMBO.md).
##
### 🧱 A resiliência está integrada (3 camadas independentes)
📖 [Motor Auto-Combo](docs/routing/AUTO-COMBO.md) · [Guia de Resiliência](docs/architecture/RESILIENCE_GUIDE.md)
## 🏆 O Que Distingue o OmniRoute
📊 Metodologia completa e detalhes por funcionalidade face ao 9router, OpenRouter, CLIProxyAPI e LiteLLM → [`docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md`](docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md)
## 💚 Apoie o OmniRoute
O OmniRoute tem licença MIT e é mantido de forma aberta. Se lhe poupar tempo ou dinheiro, veja como pode ajudar a mantê-lo independente — escolha a opção mais adequada para si. O patrocínio nunca afeta a prioridade de encaminhamento; proporciona visibilidade, não uma posição superior.
⭐ Dê uma estrela ao repositório
Grátis — ajuda genuinamente a aumentar a visibilidade
**🇧🇷 PIX** — instantâneo, sem taxas (Brasil)
Chave (aleatória): `5d865059-bc44-483a-962d-43ceb80126eb`
Pix para copiar e colar:
```
00020101021126580014br.gov.bcb.pix01365d865059-bc44-483a-962d-43ceb80126eb5204000053039865802BR5922OMNIROUTE CONTRIBUICAO6006BRASIL62070503***630475DD
```
₿ Criptomoedas — BTC · ETH · USDT-TRC20 · USDC-Solana (clique para expandir)
₿ BTC
Bitcoin (SegWit)
bc1qh00smz004sy85wyl28v77tenkt3ckl6eaep7fd
Ξ ETH
Ethereum (ERC20)
0x64Cf6B68A6Ff34288e89172950a2d00102337a84
₮ USDT
Tron (TRC20)
TKAF41JpuQrHbKTnsQa9svJE2T192Hvsc2
$ USDC
Solana
2emNNZzVVWQc3FQ2wk9M6qXUQmW8AKdjjL174fXR28Tu
⚠️ Envie cada moeda apenas através da rede indicada — o envio através da rede errada pode resultar na perda dos fundos.
🐛 Encontrou um erro ou tem algum comentário? Abra uma [Discussão](https://github.com/diegosouzapw/OmniRoute/discussions).
Notas para programadores: O projeto pode gerar um ficheiro .env local durante npm install/postinstall, para conveniência dos programadores. Este ficheiro é intencionalmente ignorado através de .gitignore (consulte .gitignore) e nunca deve ser incluído num commit — se for incluído acidentalmente, substitua quaisquer segredos expostos e remova o ficheiro do histórico. Consulte docs/DEVELOPER-ENVIRONMENT.md para obter orientações sobre a gestão de ficheiros de ambiente locais e segredos.
## 📡 OmniRoute Radar
O valor principal do nível gratuito continua a ser **~1,62 mil milhões de tokens/mês**, com base no catálogo documentado e sem duplicações entre pools apresentado acima. Os créditos temporários de registo dos fornecedores podem aumentar separadamente o total do primeiro mês para **~2,22 mil milhões**. O Radar é uma sobreposição opcional e assinada do catálogo, destinada a quem pretende informações mais atualizadas sobre a disponibilidade de modelos gratuitos entre lançamentos do OmniRoute; o catálogo da comunidade e todas as funcionalidades gratuitas existentes continuam a ser gratuitos.
Os apoiantes podem receber o catálogo em tempo real e oportunidades adicionais de fornecedores. O respetivo limite máximo, separado e variável, é de **aproximadamente 3 mil milhões de tokens/mês, no máximo**, dependendo da disponibilidade dos fornecedores. Este limite máximo não constitui uma garantia: os fornecedores podem alterar as quotas, os critérios de elegibilidade, os modelos ou as regiões a qualquer momento.
O Radar é opcional e utiliza apenas pedidos GET. O cliente OmniRoute não envia prompts, tráfego, configurações de fornecedores, telemetria de utilização nem o estado local relativo à dispensa de anúncios. Saiba mais sobre a elegibilidade e o catálogo atual em **[radar.omniroute.online/planos](https://radar.omniroute.online/planos)**.
## ✨ Novidades
> Destaques recentes da **v3.8.20 → v3.8.53**. Histórico completo em [`CHANGELOG.md`](CHANGELOG.md).
- **⚖️ Encaminhamento `quota-weighted`** — a 20.ª estratégia de combo ignora contas esgotadas e depois distribui entre as restantes em proporção à quota restante ÷ carga em curso, mantendo as conversas existentes fixadas. → [Auto-Combo](docs/routing/AUTO-COMBO.md)
- **🧰 Modo headless** — `omniroute serve --headless` (ou `OMNIROUTE_HEADLESS=1`) executa apenas o motor de proxy `/v1/*`, com o dashboard e os subsistemas exclusivos do dashboard desativados. → [Headless Mode](docs/guides/HEADLESS.md)
- **🔎 Descoberta de modelos** — `/v1/models` filtra por capacidade, contexto, tipo e texto, e `POST /v1/models/query` devolve uma lista curta determinística com a mesma visibilidade por chave. → [API Reference](docs/reference/API_REFERENCE.md)
- **🔑 Controlo de encaminhamento por chave** — fixe uma chave API a um modelo ou combo com `forcedModel`, e adicione ou remova modelos e combos de uma chave de forma atómica (`/api/keys/{id}/access`). → [API Reference](docs/reference/API_REFERENCE.md) · [OpenAPI](docs/openapi.yaml)
- **🛡️ Controlos de PII mais finos** — seleção por tipo, até 20 padrões de mascaramento personalizados validados e contadores de deteção por tipo; o mascaramento continua a ser opt-in. → [Guardrails](docs/security/GUARDRAILS.md)
- **🌍 67 idiomas** — dashboard, espelhos da documentação e CLI, com `npm run i18n:add-locale` a adicionar um idioma em todo o lado num único comando. → [i18n Guide](docs/guides/I18N.md)
- **🎛️ OmniConductor** — delegação A2A de entrada para a sua frota de agentes, competências do Conductor no Agent Card, e um painel no dashboard com chat por voz push-to-talk do Faro. → [A2A Server](docs/frameworks/A2A-SERVER.md)
- **🛂 Admissão adaptativa e proteção contra sobrecarga** — pedidos de chat pesados entram em fila em vez de devolver 503, com leases rotativos de RPM atómicos por ligação. → [Resilience Guide](docs/architecture/RESILIENCE_GUIDE.md)
- **🗂️ Ordenação canónica de `/v1/models`** — um bloco contíguo agrupado por fornecedor por cada fornecedor (combos fixados primeiro), estável em todas as fontes de catálogo. → [API Reference](docs/reference/API_REFERENCE.md)
- **🗜️ Reforço da compressão** — proteção contra inflação ativa por omissão, pacotes Caveman para DE / FR / JA + chinês (wényán), filtros RTK para Gradle e .NET. → [Compression](docs/compression/COMPRESSION_ENGINES.md)
- **💸 Custo fixo honesto** — os fornecedores de subscrição / planos de programação aparecem como **$0** nas análises de custo; o orçamento, a quota e o encaminhamento continuam a estimar. → [API Reference](docs/reference/API_REFERENCE.md)
- **⚖️ Encaminhamento Quota-Share** — divide a quota de uma conta partilhada de forma justa pelas chaves em pool, de modo work-conserving, para que as frações inativas sejam emprestadas. → [Resilience Guide](docs/architecture/RESILIENCE_GUIDE.md)
- **🤖 Configuração de CLI/agente com um comando** — 15 comandos `setup-*` registados; `omniroute run` lança 7 CLIs (Claude Code, Codex, Aider, Goose, OpenCode, Qwen Code, Gemini CLI); `omniroute configure` suporta 11 destinos com um seletor interativo de fornecedor+modelo e favoritos por contexto. → [CLI Integrations](docs/guides/CLI-INTEGRATIONS.md)
- **🛰️ Modo remoto** — controle um OmniRoute remoto com tokens com âmbito (`connect` / `contexts` / `tokens`) + um auxiliar OAuth `antigravity` para instalações em VPS. → [Remote Mode](docs/guides/REMOTE-MODE.md)
- **🧭 Auto-encaminhamento mais inteligente** — combos `auto/:`, **Fusion** (painel de modelos + juiz), encaminhamento consciente da tarefa, substituições por pedido de modelo / modo / orçamento em USD. → [Auto-Combo](docs/routing/AUTO-COMBO.md)
- **🗜️ Compressão plugável** — 12 motores composáveis + Compression Studios: LLMLingua-2, Ultra de dois níveis, omniglyph, porta de fidelidade por passo, GCF v3.2, editor com arrastar para reordenar. → [Compression](docs/compression/COMPRESSION_ENGINES.md)
- **🕵️ Desencriptação MITM transparente (TPROXY)** — capture CLIs que ignoram as variáveis de ambiente do proxy, com uma AC por SNI + instalador de trust-store. → [MITM/TPROXY](docs/security/MITM-TPROXY-DECRYPT.md)
- **💸 Telemetria de custos em todo o lado** — cabeçalhos de custo/utilização `X-OmniRoute-*` em todos os endpoints, cabeçalho de poupança em HIT de cache, quotas de despesa em USD por chave. → [API Reference](docs/reference/API_REFERENCE.md)
- **🧠 Memória sob o seu controlo** — desativada por omissão, quantização vetorial int8 opt-in + decaimento tipado, `x-omniroute-no-memory` por pedido. → [Memory](docs/frameworks/MEMORY.md)
- **🛡️ Segurança** — proteção contra prompt-injection em todas as rotas de LLM (suite de red-team), guardrail opt-in de mascaramento de credenciais (redige chaves/segredos de API expostos em ambos os sentidos), pesquisa web de último recurso gratuita via DuckDuckGo, e uma porta de login OIDC opcional para o dashboard (o login por palavra-passe permanece sempre disponível). → [Guardrails](docs/security/GUARDRAILS.md)
- **🖼️ Novos endpoints** — `/v1/ocr` (Mistral OCR) e `/v1/audio/translations` (estilo Whisper) completam a superfície de media. → [API Reference](docs/reference/API_REFERENCE.md)
- **🎨 Geração de imagem / vídeo / áudio** — uma única API para media: xAI Grok Imagine e vídeo Novita AI, ComfyUI, Magnific, Adobe Firefly, Segmind, e fornecedores de fala como ElevenLabs. → [API Reference](docs/reference/API_REFERENCE.md)
- **🌍 Implementação e operações** — `basePath` de proxy reverso, deteção automática do idioma do navegador, rastreio de dispositivos por chave, confiança MITM sem root, localização zh-TW. → [Environment](docs/reference/ENVIRONMENT.md)
- **🤝 Mais fornecedores e agentes** — agentes cloud (Codex Cloud, Cursor, Devin, Jules), Grok Build (xAI) com login por navegador + OAuth, cartão Ollama de primeira classe, Claude Opus 5 e Sonnet 5, parceria oficial Kimi (Code/Web/Moonshot), Zed, Requesty, SenseNova, Yuanbao, Agnes AI… e um **catálogo de 375 fornecedores** renovado. → [Providers](docs/reference/PROVIDER_REFERENCE.md)
- **📡 Transparência no encaminhamento** — cada resposta transporta um cabeçalho `X-OmniRoute-Decision` que indica a estratégia/fornecedor/latência que a serviu, uma nova estratégia de combo `cache-optimized` + fator `cacheAffinity` do Auto-Combo encaminham pedidos repetidos de volta para a ligação que detém o prefixo em cache, e um endpoint só de leitura `/v1/auto-combo/{channel}/candidates` expõe o conjunto de candidatos em direto de um canal `auto/*`. → [Auto-Combo](docs/routing/AUTO-COMBO.md)
- **⚡ Desempenho e infraestrutura locais** — Redis local com um clique, deployers de relay Cloudflare Workers / Deno Deploy, Bifrost e Mux como serviços embebidos supervisionados. → [Serviços Embebidos](docs/frameworks/EMBEDDED-SERVICES.md)
- **🧩 Também incluído** — framework de plugins + marketplace, frameworks de skills Omni/Agent/GitHub, integração com o vault do Obsidian (22 ferramentas MCP), APIs Batch e Files compatíveis com OpenAI, cache semântico de respostas, gamificação com tabelas de classificação, descoberta de agentes ACP (15 agentes incorporados), exportação agendada de logs para BigQuery, fan-out paralelo multi-modelo `auto/chaos`, uma ponte de bot do Telegram, um gestor de versões integrado na aplicação e rankings LMArena-ELO de fornecedores gratuitos. → [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 com IA funcionam com modelos gratuitos e de baixo custo.
＋ também funciona com · Agent Deck · Kiro · Command Code · Antigravity · Windsurf · AMP · qualquer ferramenta compatível com OpenAI
📖 Configuração por ferramenta para todas as 37 ferramentas (27 CLI de código + 10 agentes CLI) → [`docs/reference/CLI-TOOLS.md`](docs/reference/CLI-TOOLS.md) · 🧩 Plugin OpenCode → [`@omniroute/opencode-provider`](https://www.npmjs.com/package/@omniroute/opencode-provider)
**Inicie qualquer CLI suportada através do OmniRoute com um único comando** — sem escrever ficheiros de configuração,
com credenciais injetadas por processo e um diretório pessoal isolado e descartável para o 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"
# Em alternativa, escolha o fornecedor+modelo interativamente e escreva 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`
pré-visualiza as variáveis de ambiente/argumentos exatos sem executar, e `--api-key-env NAME` mantém os segredos fora
do histórico da shell. → [Integrações CLI](docs/guides/CLI-INTEGRATIONS.md)
## 🌐 375 fornecedores de IA — 153 assinalados como gratuitos no catálogo
> **375 fornecedores registados** nas coleções canónicas de chat, multimédia, pesquisa, execução local, agentes na nuvem e sistema, incluindo **153 com metadados de descoberta `hasFree: true`**. O registo de modelos de chat abrange **239 fornecedores / 3 059 pares distintos de fornecedor-modelo / 1 475 IDs de modelos em bruto**; o catálogo separado de orçamentos gratuitos tem **471 entradas por modelo**, **34 fundos recorrentes** e **51 fornecedores gratuitos para sempre, recorrentes/sem chave**. Estes denominadores são diferentes por definição; as definições e os cálculos com fundos desduplicados encontram-se na [Referência de Fornecedores](docs/reference/PROVIDER_REFERENCE.md) e nos [Planos Gratuitos](docs/reference/FREE_TIERS.md).
### 🏢 Todos os principais laboratórios — através de um único endpoint
OpenAI
Anthropic
Gemini
xAI Grok
DeepSeek
Mistral
Qwen
Meta Llama
Groq
NVIDIA
MiniMax
Cohere
Perplexity
HuggingFace
Together
Fireworks
Cloudflare
Baidu
…e mais de 350 — cada ícone é obtido em tempo real a partir do catálogo de fornecedores do painel. 📖 [Referência de Fornecedores](docs/reference/PROVIDER_REFERENCE.md)
### 🆓 Gratuito para sempre — $0, sem cartão
OpenCode Zen DeepSeek V4, Nemotron 3 Sem limite de tokens
Kilo Code Encaminhamento automático, Tencent Hy3 Gratuito para sempre
Requesty GPT-OSS 120B, Nemotron Gratuito para sempre
SiliconFlow DeepSeek V3.2 / R1 Plano gratuito
Z.AI GLM GLM-4.7 / 4.5-Flash Gratuito para sempre
Baidu ERNIE ERNIE 4.0 Gratuito para sempre
Qoder AI Qwen3-Max, Kimi-K2 GRATUITO e ilimitado
Pollinations GPT, Llama, Claude Não é necessária uma chave
Cloudflare AI Mais de 50 modelos 10 mil neurónios/dia
NVIDIA NIM GLM, MiniMax ~40 RPM grátis
Cerebras GLM 4.7, GPT-OSS Crédito único de $5; cartão obrigatório
OpenRouter Modelos :free +$10 → RPM mais elevado
📖 Catálogo completo legível por máquina → [`docs/reference/PROVIDER_REFERENCE.md`](docs/reference/PROVIDER_REFERENCE.md)
## 🖥️ Onde o OmniRoute funciona — em qualquer lugar
> A mesma aplicação, a sua máquina, as suas regras. Desde uma instalação global via npm até ao **seu telemóvel** através do Termux.
Plataforma
Instalação
Destaques
📦 npm (global)
npm install -g omniroute
Um comando, qualquer sistema operativo
🐳 Docker
docker run … diegosouzapw/omniroute
Multiarquitetura AMD64 + ARM64
🖥️ Ambiente de trabalho (Electron)
npm run electron:build
Janela nativa + área de notificação — Windows / macOS / Linux
🎩 Barra de menus (OmniRouteTray)
brew install --cask zoispag/tap/omniroute-tray
Supervisiona e atualiza automaticamente o servidor — macOS
💪 ARM
arm64 nativo
Raspberry Pi, servidores ARM, Apple Silicon
📱 Android (Termux)
pkg install nodejs && npx -y omniroute
Funciona no seu telemóvel, 24 horas por dia, 7 dias por semana, sem root
📲 PWA
"Adicionar ao ecrã principal"
Ecrã inteiro, funcionamento offline, instalável a partir do 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-o, contribua
📖 [Guia do Docker](docs/guides/DOCKER_GUIDE.md) · [Ambiente de trabalho](electron/README.md) · [Ícone da barra de menus](https://github.com/zoispag/omniroute-tray) · [Termux](docs/guides/TERMUX_GUIDE.md) · [PWA](docs/guides/PWA_GUIDE.md) · [OpenCode](docs/frameworks/OPENCODE.md)
### 🧩 Novo: OmniRoute integrado no Copilot Chat nativo do VS Code
> Sem uma nova barra lateral nem uma nova interface de chat — todos os modelos disponibilizados pelo OmniRoute aparecem diretamente no
> **seletor de modelos do Copilot Chat que já utiliza**. Desde o VS Code 1.122, os modelos de fornecedores funcionam
> sem iniciar sessão no GitHub nem ter uma subscrição do Copilot — modo de agente, chamada de ferramentas e visão,
> gratuitamente.
Instale a extensão **[OmniCopilot](https://github.com/diegosouzapw/OmniCopilot)**, configure-a
para utilizar o seu servidor OmniRoute (a predefinição é `localhost:20128`) e, em seguida, abra o Copilot Chat → seletor de modelos
→ **Gerir modelos…** → **OmniRoute**.
No editor: abra a vista **Extensões**, procure **"OmniRoute"** e clique em **Instalar**
— funciona da mesma forma em ambas as lojas. O código-fonte, as ocorrências e o guia de publicação estão disponíveis em
[diegosouzapw/OmniCopilot](https://github.com/diegosouzapw/OmniCopilot).
📖 [Guia do VS Code Copilot Chat](docs/guides/VSCODE-COPILOT.md) — configuração, o que é apresentado no seletor, painel num separador, resolução de problemas
### 🎩 Novo: OmniRouteTray — o seu gateway, sempre presente na barra de menus
> O `omniroute serve` funciona melhor quando está sempre ativo. O **[OmniRouteTray](https://github.com/zoispag/omniroute-tray)**
> transforma-o numa aplicação para a barra de menus do macOS que basta configurar e esquecer: inicia o servidor, mantém-no em funcionamento
> após reinícios, atualiza-o localmente e coloca o seu orçamento de tokens em tempo real à distância de um clique — **sem
> deixar uma janela do terminal aberta nem ter de cuidar do `npm install -g omniroute`.**
Desenvolvido com [Tauri v2](https://v2.tauri.app/) (um núcleo em Rust com um tamanho praticamente insignificante), inclui
o seu próprio runtime Node 24 assinado e gere uma instalação do OmniRoute pertencente à aplicação, pelo que nunca entra em conflito com o seu
`node`/`bun` global. **Partilha a configuração e a base de dados existentes em `~/.omniroute/`** — portanto, é o
mesmo OmniRoute que já utiliza, mas agora com um chapéu. 🎩
O que faz
Como
🟢 Supervisiona o servidor
Inicia omniroute serve e adota uma instância que já esteja em execução, em vez de a duplicar
📊 Utilização em tempo real num relance
Barras de quotas dos fornecedores, limites de sessão/semanais do Claude com contagens decrescentes até à reposição e discriminação dos custos de 30 dias
🔄 Atualiza-se automaticamente no local
Instalação faseada, substituição atómica e reversão em caso de falha — sempre na versão mais recente
🚀 Inicia ao iniciar sessão
Arranque opcional ao iniciar sessão; apenas na barra de menus, sem ícone na Dock
🩺 Diagnósticos e registos
Diagnósticos com um clique e acesso aos registos do servidor
```sh
brew install --cask zoispag/tap/omniroute-tray
```
Prefere uma transferência? Obtenha o ficheiro .dmg mais recente em
Versões. O código-fonte, os problemas e a documentação
de compilação encontram-se em zoispag/omniroute-tray.
💛 Um projeto da comunidade por @zoispag — não é uma versão oficial do OmniRoute.
> Para além do servidor, o OmniRoute é um **cockpit completo de linha de comandos** com **mais de 80 comandos**, além de protocolos de agentes abertos para que um agente de IA o possa controlar **de forma autónoma**.
### ⌨️ Uma CLI a sério (não apenas `start`)
```bash
omniroute # inicia o gateway + painel (porta 20128)
omniroute chat # cliente de chat TUI interativo (atalhos: /model /combo /skill /memory)
omniroute setup # assistente guiado de primeira execução
omniroute doctor # diagnostica fornecedores, portas e dependências nativas
```
### 🛰️ Modo remoto — execute a CLI aqui e o OmniRoute num VPS
Tem o OmniRoute num servidor? Controle-o a partir do seu portátil com a **mesma CLI**. Inicie sessão uma vez
com um token de acesso com âmbito definido; a partir daí, todos os comandos têm como destino o servidor remoto.
```bash
omniroute connect 192.168.0.15 # palavra-passe → token com âmbito definido, guardado como contexto
omniroute models # ← executado no servidor REMOTO
omniroute configure codex # ← escolhe um modelo remoto e cria um perfil Codex local
omniroute tokens create --name ci --scope read # emite tokens mais restritos para outras máquinas
omniroute contexts use default # ← volta ao servidor local
```
Os tokens têm os âmbitos `read` / `write` / `admin`; as rotas que iniciam processos continuam limitadas ao loopback.
📖 [Modo Remoto](docs/guides/REMOTE-MODE.md)
### 🤝 Ligue um agente — e este controla o próprio OmniRoute
Exponha o OmniRoute através de **MCP**, **A2A**, uma **API REST**, **webhooks** ou uma **CLI remota** — qualquer agente compatível (ou o seu próprio código) obtém acesso a todo o gateway: encaminhamento, fornecedores, combinações, cache, compressão e memória — de forma autónoma. Os endpoints HTTP abaixo são disponibilizados em `http://localhost:20128`.
Interface
Endpoint / comando
Utilização
🧰 MCP (stdio)
omniroute --mcp
Integração com o Claude Desktop, Cursor ou qualquer cliente MCP
Agente para agente, JSON-RPC 2.0 + SSE, 6 competências
🌐 API REST
/v1/*
Compatível com OpenAI — chat, embeddings, imagens, áudio e OCR
🔔 Webhooks
/api/webhooks
Envio de eventos de pedidos / quotas para o Slack, Discord, Telegram ou qualquer URL
🛰️ CLI remota
omniroute connect
Controle uma instância remota com tokens de acesso com âmbito definido
```bash
# Dê ao Claude Code o conjunto completo de ferramentas do OmniRoute através de MCP:
claude mcp add-server omniroute --type http --url http://localhost:20128/api/mcp/stream
```
📖 [Servidor MCP](docs/frameworks/MCP-SERVER.md) · [Servidor A2A](docs/frameworks/A2A-SERVER.md) · [Protocolos de Agentes](docs/frameworks/AGENT_PROTOCOLS_GUIDE.md)
## 🗜️ Poupe 15–95% de tokens — automaticamente
### 📖 Como funciona — pipeline, arquitetura e matemática das poupanças
O combo empilhado predefinido executa `RTK → Caveman`. Quando ambos atuam sobre o mesmo payload de ferramenta/contexto, as poupanças compõem-se:
```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 estão **sempre protegidos** pelo motor de preservação.
> **Porquê usar muitos tokens quando poucos tokens bastam?** Cada pedido passa pelo pipeline de compressão do OmniRoute de forma **transparente** — sem alterações no cliente. É agora uma **pilha de 12 motores combináveis** que correm em ordem e se misturam e combinam por combo de encaminhamento — com base em ideias de [RTK](https://github.com/rtk-ai/rtk), [Caveman](https://github.com/JuliusBrussee/caveman) (⭐ 90K+), [LLMLingua-2](https://github.com/microsoft/LLMLingua) e [Troglodita](https://github.com/leninejunior/troglodita) (PT-BR).
### 🧱 A pilha de 12 motores
Os motores correm pela ordem do pipeline; cada um é ativável/desativá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, obtidos a pedido
3
Lite
Aparo de espaços em branco + URLs de imagens (linha de base leve em latência)
4
RTK
Filtragem inteligente de resultados de ferramentas, deduplicação e truncagem (consciente dos comandos)
5
Responses Tool Output
JSON sem perdas primeiro + compressão de diagnóstico limitada para saídas de shell/patch/search/build (API Responses)
6
Headroom
Compactação tabular sem perdas de arrays JSON (~30%) através de um codec GCF incorporado
7
Relevance
Pontuação extrativa de frases em relação à última consulta do utilizador
8
Caveman
Compressão de prosa baseada em regras (~65–75% na saída)
9
Aggressive
Sumarização + envelhecimento progressivo dos 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 um nível opcional de modelo pequeno (SLM)
12
OmniGlyph
Codificação experimental de contexto como imagem para o Claude Fable 5 medido no fio direto da Anthropic; os transformers GPT 5.6 permanecem em fail-closed à espera de confirmações do fornecedor. Quatro perfis de compressão (predefinição agressiva, equilibrado, seguro para código, passthrough) (o mais agressivo; opt-in)
Blocos de código, URLs e dados estruturados são **sempre preservados** ao byte. **Predefinições com um clique** combinam os motores:
Modo
Poupança
Melhor para
🪶 Lite
~15%
Predefinição segura sempre ativa
🪨 Standard (Caveman)
~30%
Programação diária
⚡ Aggressive
~50%
Sessões longas com muita ferramenta
🔥 Ultra
~75%
Poupança máxima
🧰 RTK
60–90%
Saída de shell/test/build/git
🔗 Stacked (RTK → Caveman)
78–95%
Prompts mistos + registos 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. Menos 72% de 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á a ser novamente renderizado porque é criada uma nova referência de objeto em cada ciclo de renderização. Recomendaria utilizar useMemo."_
>
> **Depois (12 tokens):** _"Nova renderização: nova ref. em cada ciclo (objeto inline recriado). Utilizar `useMemo`."_
>
> **Mesma resposta. ~70% menos tokens. Precisão técnica intacta.** ✅
### 🎚️ Para além dos motores — estilos de saída, ajuste adaptativo e controlo por pedido
Os 12 motores acima reduzem o que **entra**. Três camadas adicionais determinam **como**, **quando** e o que **sai**:
- **🪄 Estilos de saída** _(orientação do eixo de saída)_ — injetam instruções determinísticas e compatíveis com cache para moldar as respostas; são combináveis, cada uma com intensidade `lite` / `full` / `ultra`. Adicionar um estilo requer apenas uma linha no registo:
- **Prosa concisa** — remove texto supérfluo / artigos / hesitações; mantém a substância técnica exata.
- **Menos código** — YAGNI de «programador sénior preguiçoso»: a menor alteração funcional, sem estruturas não solicitadas.
- **Rabo de cavalo (programador sénior preguiçoso)** — sobe a escada YAGNI, corrige a causa principal e produz o menor diff funcional.
- **Tenho PHDA (ação primeiro)** — começa pela ação seguinte, passos numerados, um próximo passo concreto, sem preâmbulo.
- **CJK conciso (文言)** — estilo ultraconciso de chinês clássico (limitado à região `zh`).
- **🎯 Orçamento de contexto adaptativo** _(o ajuste)_ — em vez de um único limiar de tokens para ativar/desativar, aumenta apenas os motores mais económicos e com menor perda, até ser possível **caber na janela de contexto do modelo**. Política: `reserve-output` (predefinição, consciente do modelo) · `percentage` · `absolute`. Modo: `floor` (garante que cabe) · `replace-autotrigger` (prevalece a sua escolha explícita) · `off` (limiar antigo).
- **🎛️ Onde é decidida a compressão** _(precedência, da mais alta para a mais baixa)_ — cabeçalho `x-omniroute-compression` por pedido › substituição da combinação de encaminhamento › perfil nomeado ativo › adaptativo / acionamento automático › predefinição do painel › desativado. O plano aplicado é devolvido no cabeçalho de resposta `X-OmniRoute-Compression: ; source=`.
Acione automaticamente através de um limiar de tokens, ative o ajuste adaptativo, fixe um perfil nomeado, defina uma configuração pontual por pedido ou atribua um pipeline por combinação de encaminhamento — consoante o que melhor se adequar à carga de trabalho. Um **sistema de avaliação** offline opcional (`npm run eval:compression`) avalia a fidelidade face à poupança num corpus fixo antes de promover uma alteração.
📖 [`COMPRESSION_GUIDE.md`](docs/compression/COMPRESSION_GUIDE.md) · [`RTK_COMPRESSION.md`](docs/compression/RTK_COMPRESSION.md) · [`COMPRESSION_ENGINES.md`](docs/compression/COMPRESSION_ENGINES.md)
# ⚡ Início rápido
**1) Instalar e executar**
```bash
npm install -g omniroute
omniroute
```
> 💡 Vê `npm warn ERESOLVE` ou avisos relativos a dependências peer? [São inofensivos](docs/guides/TROUBLESHOOTING.md#npm-install-warnings-eresolve--peer--deprecated).
> **Está a utilizar o npm 11 ou posterior?** O npm pode bloquear scripts do ciclo de vida dos pacotes, salvo se forem permitidos. O `postinstall` do OmniRoute (`node scripts/build/postinstall.mjs`) é necessário para preparar os respetivos ficheiros nativos de runtime. Ao instalar globalmente, permita os pacotes indicados no aviso do npm. Para o conjunto de pacotes indicado 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 lista de permissões em futuras instalações globais, configure-a uma vez e, em seguida, 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 indicar uma lista diferente, utilize os nomes dos pacotes presentes nesse aviso. Permitir um pacote autoriza a execução dos respetivos scripts de instalação.
> **Está a utilizar o Gemini Web ou outro fornecedor baseado em cookies da Web?** O pacote npm inclui
> o Playwright, mas não o respetivo binário do Chromium. Consulte a nota sobre a
> [configuração do Chromium para o Playwright](docs/guides/TROUBLESHOOTING.md#gemini-web-and-playwright-chromium)
> antes de efetuar o primeiro pedido ao fornecedor Web.
Painel em `http://localhost:20128` · API em `http://localhost:20128/v1`.
**2) Ligar um fornecedor elegível utilizando a sua própria conta**
Painel → **Fornecedores** → escolha um fornecedor cujos termos e quota atuais sejam adequados ao seu caso de utilização → adicione a respetiva chave de API ou conclua o fluxo de conta. Os níveis gratuitos podem exigir registo, aprovação ou um método de pagamento. Consulte o [Guia de níveis gratuitos](docs/getting-started/FREE-TIERS-GUIDE.md); a disponibilidade sem chave não é garantida e os fornecedores assinalados com `tos: avoid` são excluídos de `auto` por predefinição.
**3) Configurar a sua ferramenta de programação**
```txt
URL base: http://localhost:20128/v1
Chave de API: [copiar de Painel → Endpoints]
Modelo: auto (encaminha entre ligações elegíveis — ou escolha fornecedor/modelo)
```
**4) Verificar se está a funcionar**
```bash
curl http://localhost:20128/v1/models -H "Authorization: Bearer YOUR_KEY"
```
Deverá ver os modelos ligados na lista. 🎉 É tudo — comece a programar e o OmniRoute fará automaticamente o encaminhamento e utilizará alternativas quando necessário.
Se o seu cliente não conseguir 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
Etiquetas Ollama: http://localhost:20128/vscode/YOUR_KEY/api/tags
```
Utilize-os apenas em clientes que não consigam anexar `Authorization: Bearer ...`. A autenticação por cabeçalho continua a ser o modo preferencial.
## 📦 Mais métodos de instalação — Docker, código-fonte, pnpm, Arch
**🐳 Docker**
```bash
docker run -d --name omniroute --restart unless-stopped --stop-timeout 40 \
-p 127.0.0.1:20128:20128 -v omniroute-data:/app/data diegosouzapw/omniroute:latest
```
`:latest` acompanha a versão SemVer estável **publicada** mais elevada. Não acompanha o `main` do git. Fixe `:X.Y.Z` para GitOps. Consulte [Canais de lançamento do Docker](docs/guides/DOCKER_GUIDE.md#release-channels). A imagem fixa **`OMNIROUTE_MEMORY_MB=1024`**. Isto é suficiente para o painel e uma conversa ligeira. Os **agentes de programação** (`POST /v1/responses` do Claude Code, Codex, Grok, …) necessitam de uma heap V8 muito maior, caso contrário o processo termina com `FATAL ERROR` quando atinge ~12 GiB com dois contextos longos sobrepostos. Dimensione o contentor acima do tamanho da heap (os buffers nativos ficam fora do V8):
| Carga de trabalho | Heap (`-e OMNIROUTE_MEMORY_MB`) | Contentor (`--memory`) |
| ----------------------------------------- | ------------------------------- | ---------------------- |
| Painel / conversa ligeira | `1024` (predefinição da imagem) | ≥2 g |
| Um agente de programação | `8192` | ≥10 g |
| Dois `/v1/responses` longos em simultâneo | `10240`–`12288` | ≥12–16 g |
```bash
docker run -d --name omniroute --restart unless-stopped --stop-timeout 40 \
-e OMNIROUTE_MEMORY_MB=8192 --memory=10g \
-p 127.0.0.1:20128:20128 -v omniroute-data:/app/data diegosouzapw/omniroute:latest
```
Tabela completa: [Guia do Docker — RAM em tempo de execução](docs/guides/DOCKER_GUIDE.md#runtime-ram-for-coding-agents).
> **Canal de pré-lançamento do Docker:** `diegosouzapw/omniroute:next` e
> `diegosouzapw/omniroute:next-web` acompanham o branch `release/v*` predefinido
> atual. Estas etiquetas mutáveis destinam-se apenas a testar correções ainda não lançadas e
> **não são suportadas em produção**. Consulte
> [Canais de lançamento do Docker](docs/guides/DOCKER_GUIDE.md#release-channels).
**🥟 Bun**
O `bun install` padrão e a instalação global (`bun install -g omniroute`) são suportados através da deteção do ambiente de execução Bun:
- **`bun:sqlite` integrado**: o OmniRoute utiliza o controlador `bun:sqlite` integrado do Bun quando é executado no Bun, recorrendo ao `better-sqlite3` no Node.js ou ao `sql.js` como alternativas.
- **Seleção automática do empacotador Webpack em desenvolvimento**: o ambiente de desenvolvimento (`bun run dev`) deteta automaticamente o Bun e desativa o Turbopack em favor do Webpack, para evitar incompatibilidades com bindings nativos do V8. As compilações de produção (`bun run build`) seguem `OMNIROUTE_USE_TURBOPACK` exatamente como no Node: Turbopack por predefinição, `OMNIROUTE_USE_TURBOPACK=0` para compilar com Webpack (`Dockerfile.bun` disponibiliza esta opção como `--build-arg`).
- **Dockerfile dedicado ao Bun**: `Dockerfile.bun` multifase para implementações de produção nativas do Bun (`docker build -f Dockerfile.bun -t omniroute:bun .`).
```bash
# Instalar e executar com o Bun
bun install
bun run dev
```
**🛠️ A partir do código-fonte**
```bash
cp .env.example .env && npm install
PORT=20128 npm run dev
```
**📦 pnpm**
```bash
pnpm add -g omniroute@latest --allow-build=better-sqlite3 --allow-build=@swc/core && omniroute
```
**🐧 Arch Linux (AUR)**
```bash
yay -S omniroute-bin && systemctl --user enable --now omniroute.service
```
**🔧 Nix (Flake)**
```bash
# Utilizar flakes do Nix
nix develop
npm run dev
# Ou utilizar o devbox
devbox run npm run dev
```
📖 [Guia do Docker](docs/guides/DOCKER_GUIDE.md) — perfis do Compose, Caddy HTTPS e túneis do Cloudflare.
**🦭 Podman**
```bash
# 1. Preparar o diretório de dados montado por bind
mkdir -p data
# 2. Apenas Linux + Podman rootless local (nunca um cliente remoto Podman Machine):
podman unshare chown 1000:1000 ./data
# 3. Definir a indicação do ambiente de execução, criar a imagem local do Compose e iniciar
echo "CONTAINER_HOST=podman" >> .env
podman compose --profile base up -d --build
```
No macOS ou Windows, o Podman utiliza uma Podman Machine remota: ignore `podman unshare` e
siga as [orientações para o diretório de dados específicas da topologia](contrib/podman/README.md#data-directory-permissions-by-topology).
📖 [Guia do Podman](contrib/podman/README.md) — compilações do Compose, Podman Machine e
configuração do Quadlet com Linux/systemd.
**⚡ Instalação mais rápida / leve (ignorar a compilação nativa)**
O motor SQLite nativo (`better-sqlite3`) é uma dependência **opcional**, pelo que uma instalação
global nunca fica bloqueada a compilar a partir do código-fonte: utiliza um binário pré-compilado quando existe um compatível
com a sua plataforma/Node e, caso contrário, recorre de forma transparente a um motor JavaScript puro
(`node:sqlite` no Node 22+, ou o WASM `sql.js` incluído) — sem necessidade de ferramentas de compilação.
Para ignorar completamente a preparação nativa pós-instalação (CI, sistemas sem interface gráfica ou máquinas lentas):
```bash
OMNIROUTE_SKIP_POSTINSTALL=1 npm install -g omniroute # CI=1 também a ignora
```
Para instalações mais rápidas, prefira o **pnpm** (armazenamento endereçado por conteúdo + hard links — consulte acima).
Para um ambiente de execução sem painel nem interface gráfica, utilize o perfil `base` do Docker (acima) ou o
[guia do Termux](docs/guides/TERMUX_GUIDE.md). A CLI e o painel Web são disponibilizados pelo
mesmo processo numa única porta, pelo que atualmente não existe um pacote separado apenas para a CLI.
OAuth 2.0 (PKCE) + JWT + chaves de API + autenticação com âmbito 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
Registo
pino — registos JSON estruturados com contexto do pedido
Testes
Node.js test runner + Vitest — 56 000+ declarações estáticas de teste em mais de 7 800 ficheiros de teste monitorizados (unitários, integração, E2E, segurança, ecossistema)
Estratégia de cobertura de testes para mais de 56 000 declarações estáticas de testes em mais de 7 800 ficheiros de teste monitorizados
# ⭐ Principais Contribuidores
> O OmniRoute é moldado por uma comunidade de código aberto apaixonada. Estas pessoas fizeram contribuições excecionais que têm um impacto direto na qualidade, estabilidade e alcance do projeto. **Obrigado.**
### Contribuidores externos por pull requests integrados
Levantamento realizado em 2026-10-18 15:09:09 UTC com a ponta ativa de release/v3.8.52 em 656f01cb43. O levantamento paginado através da API GraphQL do GitHub contém 9 191 PRs integrados: 3 834 pelo proprietário do repositório, 229 pelo Dependabot, 6 por outros bots/aplicações e 5 122 PRs externos de 835 contribuidores distintos. «Linhas alteradas» corresponde às adições + eliminações do GitHub e inclui ficheiros gerados, ficheiros de bloqueio, catálogos, traduções e documentação; representa o volume de alterações, não as LOC de autoria própria. 49 PRs apresentam diferenças no GitHub superiores a 500 000 linhas (por exemplo, o #13399, que adiciona um único fornecedor, apresenta 2 347 ficheiros alterados), o que aumenta vários dos totais acima. Os empates partilham a mesma posição.
### Commits atribuídos pelo GitHub
Verificado novamente em 2026-10-18 14:44:45 UTC: commits atribuídos pelo GitHub, comunicados pela API Contributors do repositório para o ramo predefinido release/v3.8.52. A API devolveu 849 identidades (429 utilizadores, 2 bots e 418 anónimas); esta tabela exclui o responsável pela manutenção, os bots e as identidades anónimas e mantém os empates na classificação. É distinta tanto da classificação de PR integrados acima como do recenseamento de metadados do Git abaixo.
> 🙏 As funcionalidades, correções de erros e melhorias de infraestrutura destes contribuidores são uma **parte essencial** do que torna o OmniRoute fiável e rico em funcionalidades. Cada pull request, cada caso de teste e cada ficheiro de tradução i18n é importante. O código aberto é construído por pessoas como estas.
---
## 💖 Patrocinadores
Um agradecimento sincero às pessoas que financiam o OmniRoute do seu próprio bolso — cada contribuição mantém o projeto gratuito, independente e em evolução.
… e outras pessoas que preferem manter-se anónimas 💛Os Patrocinadores públicos do GitHub foram revalidados em 2026-10-18 através da API GraphQL do GitHub Sponsors: 11 patrocínios públicos (6 ativos, 5 anteriores) de um total de 14. O estado isActive do GitHub determina as etiquetas de atividade acima; os antigos apoiantes públicos pontuais continuam a ser agradecidos e os patrocinadores privados permanecem anónimos. As doações através do Ko-fi, Buy Me a Coffee, Liberapay, PIX e criptomoedas não estão listadas porque não têm um registo público de patrocinador.💖 Torne-se patrocinador → — cada dólar mantém o OmniRoute gratuito e independente.
## 👥 Mais de 900 Colaboradores
[](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)
Auditado em 2026-10-18 na ponta atual de release/v3.8.52, ad160ab2d1 (6 826 commits): 993 identidades Git humanas normalizadas — 707 aparecem como autores de commits (incluindo o responsável pela manutenção) e 286 apenas em trailers Co-authored-by explícitos. O levantamento aplica o .mailmap, compara endereços de e-mail sem distinção entre maiúsculas e minúsculas, associa endereços noreply numéricos e simples do GitHub apenas quando codificam o mesmo identificador, exclui 26 identidades de bots/agentes/serviços/marcadores de posição e não agrega endereços de e-mail comuns apenas porque os respetivos nomes de apresentação coincidem. A auditoria de 2026-08-24 indicava 639; a repetição deste método sobre a base ac02c5b42f dessa auditoria resulta em 619, pelo que o aumento provém de novos colaboradores, e não de um método menos restritivo.
### Como Contribuir
1. Faça um fork do repositório
2. Crie um branch a partir da ponta **ativa** de `release/vX.Y.Z` (não de `main`) — consulte [Modelo de Branches e Lançamentos](docs/ops/BRANCHING_MODEL.md)
3. Crie o seu branch de funcionalidade (`git checkout -b feat/amazing-feature`)
4. Faça commit das suas alterações (`git commit -m 'feat: add amazing feature'`)
5. Envie o branch (`git push origin feat/amazing-feature`)
6. Abra um Pull Request com **base = esse branch `release/vX.Y.Z`**
Consulte [CONTRIBUTING.md](CONTRIBUTING.md) para obter orientações detalhadas.
### Lançar uma Nova Versão
```bash
# Criar um lançamento — a publicação no npm ocorre automaticamente
VERSION=x.y.z
gh release create "v${VERSION}" --title "v${VERSION}" --generate-notes
```
## 📊 Estrelas
## 🌍 StarMapper
## 🙏 Agradecimentos
O OmniRoute apoia-se no trabalho de gigantes. Começou como um fork do **[9router](https://github.com/decolua/9router)** e uma conversão para TypeScript do projeto em Go **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** — e, a partir daí, cada subsistema abaixo foi inspirado por um projeto de código aberto que chegou primeiro. Cada um deles moldou uma parte concreta do OmniRoute. Este é o nosso agradecimento a todos eles. 🙏
> ⭐ contagens de estrelas verificadas através da API REST do GitHub em 18 de outubro de 2026 — dê uma estrela a estes projetos. As contagens são um retrato exato dessa data e mudarão naturalmente.
### 🧬 Linhagem e gateway
O gateway de IA cujo conjunto público de dados de preços alimenta a nossa sincronização de acompanhamento de custos e cujo modelo de normalização de fornecedores orientou o nosso encaminhamento.
Código-fonte MIT adaptado para a ponte incluída ChatGPT Web → Codex Responses, incluindo adaptadores de sessão do navegador, enquadramento de respostas, utilização e pesquisa na Web.
Padrões convertidos para a recuperação de streams, aliases sem raciocínio, pesquisa de recurso na Web, limites de janela deslizante, ocultação de dados nos registos e fluxos de inicialização reforçados.
Predefinições de transformação compatíveis com o Claude Code e comportamento dos cabeçalhos de faturação generalizados na ponte orientada por configuração do OmniRoute.
Os seus mapeamentos de modelos Grok, o gerador Statsig com TypeError simulado, as predefinições de pedidos e dispositivos e o processador de respostas NDJSON foram substancialmente adaptados para o executor Grok Web do OmniRoute.
A principal fonte de código transitiva por detrás do grok2api-merged; as 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 as predefinições de payloads e dispositivos do Grok, o gerador Statsig e o processador result.response, transmitido através do TQZHR e do grok2api-merged.
Uma fonte transitiva creditada pelo grok2api-merged pela sua camada de conjunto de proxies; o OmniRoute preserva essa indicação de linhagem, mas não reivindica uma conversão do conjunto de proxies no seu executor Grok Web de âmbito limitado.
A implementação original do Grok Web serviu de referência para a sua conceção de upstream HTTP/navegador; o respetivo caminho HTTP direto deriva do GrokProxy, pelo que não se reivindica qualquer conversão de código independente.
O projeto viral «porquê usar muitos token quando poucos token fazer truque» — a sua filosofia de linguagem de homem das cavernas alimenta o nosso modo de compressão padrão e mais de 30 regras de remoção de redundâncias/condensação.
Compressão de alto desempenho da saída de comandos — inspirou o nosso motor RTK, a DSL de filtros JSON, a recuperação da saída em bruto e o pipeline encadeado RTK → Caveman.
Investigação sobre compressão de prompts (LLMLingua / LLMLingua-2) — inspirou o nosso motor llmlingua assíncrono, seguro para código e com funcionamento em modo aberto em caso de falha.
Compressão de tokens em pt-BR — alimenta o nosso pacote linguístico pt-BR: redução de pleonasmos e remoção de expressões supérfluas ajustadas à gramática do português do Brasil.
A competência viral de programação YAGNI do «programador sénior preguiçoso» — inspirou o nosso Estilo de Saída less-code: orientação para a menor alteração funcional, que reduz o código _gerado_ (o equivalente, no eixo da saída, à prosa concisa do Caveman).
O seu estilo de resposta orientado primeiro para a ação e adaptado a pessoas com PHDA foi incorporado no estilo de saída conciso do OmniRoute em cinco idiomas.
### 🧩 Formatos compactos, investigação sobre tokens e ferramentas sensíveis ao código
Compressão de saída sensível ao conteúdo e específica por tipo de ficheiro, com desistência em caso de falha — validou o nosso encaminhamento 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 dos nossos motores headroom/ccr/session-dedup e a invariável, estável para cache, de que «a forma comprimida é independente da posição».
Kit de ferramentas da API do compilador TypeScript — inspirou a nossa remoção de comentários baseada em parser, que preserva literais de strings, templates e expressões regulares.
A interceção/análise MITM do tráfego entre assistentes de programação e LLM serviu de base aos requisitos iniciais do Inspetor de Tráfego. Quatro módulos anteriormente derivados — combinação de SSE, normalização de conversas, ocultação de segredos e sanitização de cabeçalhos — foram substituídos por implementações independentes de sala limpa, baseadas em normas públicas de protocolos. As duas superfícies de passagem direta do anfitrião (passthrough.ts e _internal/bypass.cjs) continuam a ser implementações internas do OmniRoute classificadas de forma independente; não foram reescritas como parte dessa substituição.
Encaminhamento de proxy transparente por processo — inspirou o nosso encerramento de MITM resiliente a falhas, os tempos limite de inatividade dos sockets, a atribuição de processos através de /proc e a captura TPROXY.
Observabilidade da malha de serviços Istio — inspirou os nossos distintivos de disjuntor e os elementos visuais das ligações com erros no Routing/Combo Studio.
Uma lista selecionada de bibliotecas seguras por predefinição que orienta as nossas escolhas de segurança (Helmet.js, DOMPurify, ssrf-req-filter, safe-regex, Google Tink).
Inspirou a desduplicação de pedidos, o recurso de emergência sem custos, as estratégias Auto-Combo extensíveis e a classificação multilingue de intenções.
O seu comportamento de remapeamento de modelos com reconhecimento de contas, validação de caminhos de executáveis e etiquetas de planos serviu de base ao ambiente de execução Antigravity do OmniRoute.
O seu formato compacto de contagem decrescente para a reposição de quotas inspirou a apresentação correspondente dos limites dos fornecedores no OmniRoute.
Identificou a superfície de quotas do Grok Build; o OmniRoute verificou e corrigiu depois, de forma independente, o formato dos dados transmitidos em tempo real.
## 📄 Licença
Licença MIT - consulte o ficheiro [LICENSE](LICENSE) para mais detalhes.
---
**[⬆ Voltar ao topo](#-omniroute)** · Criado 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 dinâmica `/dashboard/free-tiers`. Metodologia completa (desduplicação de pools, níveis de créditos, termos dos fornecedores): **[docs/reference/FREE_TIERS.md](docs/reference/FREE_TIERS.md)**.
>
> Estes valores são novamente auditados a cada duas semanas em comparação com o catálogo em produção e **podem variar em ambos os sentidos** — se um fornecedor terminar um nível gratuito, o número desce; se surgir um novo, aumenta. Publicamos aquilo que o catálogo realmente calcula, nunca um cenário otimista arredondado por excesso.
```bash
# Depois de ligar um fornecedor, copie a sua chave 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 sem chave elegíveis, e um fornecedor sem chave pode rejeitar clientes de terceiros. Os fornecedores marcados como `tos: avoid`, incluindo o Kiro, são excluídos do encaminhamento automático por predefinição; ligar uma conta não substitui essa definição. Consulte o [Guia de Planos Gratuitos](docs/getting-started/FREE-TIERS-GUIDE.md) antes de escolher um fornecedor.
📦 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 encaminha pedidos **automaticamente**. Se a quota se esgotar, um fornecedor falhar ou os custos dispararem, o combo pode avançar para o modelo elegível e operacional seguinte. 🛡️
### ⚡ Sem configuração — basta usar `auto`
Não é necessário criar nenhum combo. Defina o seu modelo como `auto` (ou uma variante) e o OmniRoute cria um combo virtual a partir dos fornecedores ligados, avaliados em tempo real:
📖 [Motor Auto-Combo](docs/routing/AUTO-COMBO.md) · [Guia de Resiliência](docs/architecture/RESILIENCE_GUIDE.md)
📊 Metodologia completa e detalhes por funcionalidade face ao 9router, OpenRouter, CLIProxyAPI e LiteLLM → [`docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md`](docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md)
Chave (aleatória): `5d865059-bc44-483a-962d-43ceb80126eb`
Pix para copiar e colar:
```
00020101021126580014br.gov.bcb.pix01365d865059-bc44-483a-962d-43ceb80126eb5204000053039865802BR5922OMNIROUTE CONTRIBUICAO6006BRASIL62070503***630475DD
```
📖 [Autorização](docs/architecture/AUTHZ_GUIDE.md) · [Proteções](docs/security/GUARDRAILS.md) · [Conformidade](docs/security/COMPLIANCE.md)
O combo empilhado predefinido executa `RTK → Caveman`. Quando ambos atuam sobre o mesmo payload de ferramenta/contexto, as poupanças compõem-se:
```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 estão **sempre protegidos** pelo motor de preservação.
> **Porquê usar muitos tokens quando poucos tokens bastam?** Cada pedido passa pelo pipeline de compressão do OmniRoute de forma **transparente** — sem alterações no cliente. É agora uma **pilha de 12 motores combináveis** que correm em ordem e se misturam e combinam por combo de encaminhamento — com base em ideias de [RTK](https://github.com/rtk-ai/rtk), [Caveman](https://github.com/JuliusBrussee/caveman) (⭐ 90K+), [LLMLingua-2](https://github.com/microsoft/LLMLingua) e [Troglodita](https://github.com/leninejunior/troglodita) (PT-BR).
### 🧱 A pilha de 12 motores
Os motores correm pela ordem do pipeline; cada um é ativável/desativável e configurável de forma independente por combo:
