## 💰 ~1,62 mil milhões de tokens/mês em níveis gratuitos de terceiros
> **Traz as tuas próprias contas de fornecedor.** Esta é uma estimativa agregada de níveis gratuitos de terceiros elegíveis separadamente, não é uma oferta de tokens da OmniRoute. Regista-te, obtém credenciais onde for necessário e liga os fornecedores que conseguires usar; cada fornecedor controla os seus limites, disponibilidade e termos.
>
> Acumular níveis gratuitos à mão é penoso — dezenas de SDKs, dezenas de limites de taxa e nenhuma ideia de quanto tens realmente. A OmniRoute cataloga **467 entradas de nível gratuito em 34 chaves de pool recorrentes** e calcula o valor de destaque de tokens a partir dos **17 pools com um orçamento mensal positivo publicado, mais cinco limites por modelo da Groq**, deduplicados por pool partilhado. As quotas que só se abrem após uma verificação de identidade regional (atualmente: ModelScope) são apresentadas à parte, +~6M atrás de verificação de identidade regional, e nunca são somadas ao valor de destaque. O resultado permanece visível no painel (`/dashboard/free-tiers`).
> Resumo animado da página `/dashboard/free-tiers` em direto. Metodologia completa (deduplicação de pools, níveis de créditos, termos dos fornecedores): **[docs/reference/FREE_TIERS.md](docs/reference/FREE_TIERS.md)**.
>
> Estes valores são reauditados a cada duas semanas com base no catálogo em direto e **movem-se em ambos os sentidos** — um fornecedor termina um nível gratuito e o número desce; chega um novo e o número sobe. Publicamos o que o catálogo calcula efetivamente, nunca um melhor cenário arredondado por excesso.
⭐ Dá uma estrela ao repositório se o OMNIROUTE te ajudou a poupar dinheiro e a facilitar o teu trabalho.
[](https://github.com/diegosouzapw/OmniRoute)
[](https://www.star-history.com/diegosouzapw/omniroute)
[](https://olud.ai/project/diegosouzapw-omniroute.html)
### 💬 Junta-te à comunidade
**👋 Segue o mantenedor — recebe primeiro novos fornecedores, versões e dicas:**
[](https://www.linkedin.com/in/diegosouzapw/)
[](https://github.com/diegosouzapw)
[](https://discord.gg/U47eFqAXCn)
[](https://t.me/omnirouteOficial)
[](https://chat.whatsapp.com/FvuCbrpZmQ6I85n2vW5QIC?s=cl&p=a&mlu=4)
[](https://chat.whatsapp.com/KWgatljAjmbELQory59Oti?s=cl&p=a&mlu=4)
[](https://omniroute.online)
**Perguntas, dicas sobre fornecedores, roadmap e suporte → [Discord](https://discord.gg/U47eFqAXCn) · [Telegram](https://t.me/omnirouteOficial) · WhatsApp [🌍 Global](https://chat.whatsapp.com/FvuCbrpZmQ6I85n2vW5QIC?s=cl&p=a&mlu=4) / [🇧🇷 Brasil](https://chat.whatsapp.com/KWgatljAjmbELQory59Oti?s=cl&p=a&mlu=4) / [Portal](https://portal.sthub.com.br/communities/groups/st-hub/channels/Omniroute-World-8kRjmK)**
## 📈 O Gateway continua a crescer
| | v3.8.50 | **v3.8.51** | `v3.8.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 marcados como gratuitos no catálogo
> **375 fornecedores registados** nas coleções canónicas de chat, media, pesquisa, local, agente na cloud e sistema, incluindo **153 com metadados de descoberta `hasFree: true`**. O registo de modelos de chat abrange **239 fornecedores / 3 059 pares distintos fornecedor-modelo / 1 475 IDs de modelo em bruto**; o catálogo separado de orçamento gratuito tem **467 linhas por modelo**, **34 pools recorrentes** e **51 fornecedores gratuitos para sempre, recorrentes/sem chave**. Estes são denominadores diferentes por conceção; as definições e os cálculos com deduplicação de pools estão em [Referência de Fornecedores](docs/reference/PROVIDER_REFERENCE.md) e [Níveis Gratuitos](docs/reference/FREE_TIERS.md).
### 🏢 Todos os grandes laboratórios — através de um único endpoint
OpenAI
Anthropic
Gemini
xAI Grok
DeepSeek
Mistral
Qwen
Meta Llama
Groq
NVIDIA
MiniMax
Cohere
Perplexity
HuggingFace
Together
Fireworks
Cloudflare
Baidu
…e mais de 350 — cada ícone é resolvido em tempo real a partir do catálogo de fornecedores do dashboard. 📖 [Referência de Fornecedores](docs/reference/PROVIDER_REFERENCE.md)
### 🆓 Gratuito para sempre — 0 $, sem cartão
OpenCode Zen DeepSeek V4, Nemotron 3 Sem limite de tokens
Kilo Code Auto-router, Tencent Hy3 Grátis para sempre
Requesty GPT-OSS 120B, Nemotron Grátis para sempre
SiliconFlow DeepSeek V3.2 / R1 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 Não precisa de chave
Cloudflare AI 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; requer cartão
OpenRouter Modelos :free +$10 → mais RPM
📖 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 de testes estáticos em mais de 7.800 ficheiros de teste monitorizados
# ⭐ Principais contribuidores
> O OmniRoute é moldado por uma comunidade open-source apaixonada. Estas pessoas deram contribuições excecionais que impactam diretamente a qualidade, a estabilidade e o alcance do projeto. **Obrigado.**
### Contribuidores externos por pull requests integrados
Censo realizado em 2026-10-18 15:09:09 UTC com o tip em direto release/v3.8.52656f01cb43. O censo paginado do GitHub GraphQL contém 9,191 PRs integrados: 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» corresponde a adições + eliminações do GitHub e inclui ficheiros gerados, lockfiles, catálogos, traduções e documentação; trata-se de volume de alterações, não de LOC de autoria. 49 PRs apresentam diffs do GitHub acima de 500,000 linhas (por exemplo, #13399, uma única adição de fornecedor, lista 2,347 ficheiros alterados), o que inflaciona vários totais acima. Os empates são classificados em conjunto.
### Commits atribuídos ao GitHub
Verificado novamente em 2026-10-18 14:44:45 UTC: commits atribuídos ao GitHub comunicados pela API de Contribuidores do repositório para o ramo predefinido release/v3.8.52. A API devolveu 849 identidades (429 utilizadores, 2 bots, 418 anónimos); esta tabela exclui o mantenedor, os bots e as identidades anónimas e mantém os empates na competição. É distinta tanto da classificação de PRs integrados acima como do censo de metadados Git abaixo.
> 🙏 As funcionalidades, correções de erros e melhorias de infraestrutura destes contribuidores são uma **parte fundamental** daquilo 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 eles.
---
## 💖 Patrocinadores
Um agradecimento sincero às pessoas que financiam o OmniRoute do seu próprio bolso — cada contribuição mantém o projeto gratuito, independente e em evolução.
… e outras pessoas que preferem manter-se anónimas 💛Os Patrocinadores públicos do GitHub foram revalidados em 2026-10-18 através da API GraphQL do GitHub Sponsors: 11 patrocínios públicos (6 ativos, 5 anteriores) de um total de 14. O estado isActive do GitHub determina as etiquetas de atividade acima; os antigos apoiantes públicos pontuais continuam a ser agradecidos e os patrocinadores privados permanecem anónimos. As doações através do Ko-fi, Buy Me a Coffee, Liberapay, PIX e criptomoedas não estão listadas porque não têm um registo público de patrocinador.💖 Torne-se patrocinador → — cada dólar mantém o OmniRoute gratuito e independente.
## 👥 Mais de 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 `/dashboard/free-tiers` em direto. Metodologia completa (deduplicação de pools, níveis de créditos, termos dos fornecedores): **[docs/reference/FREE_TIERS.md](docs/reference/FREE_TIERS.md)**.
>
> Estes valores são reauditados a cada duas semanas com base no catálogo em direto e **movem-se em ambos os sentidos** — um fornecedor termina um nível gratuito e o número desce; chega um novo e o número sobe. Publicamos o que o catálogo calcula efetivamente, nunca um melhor cenário 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:
