Skip to content

USER_GUIDE.md

Latest commit

 

History

History
1414 lines (1016 loc) · 80.5 KB

USER_GUIDE.md

File metadata and controls

1414 lines (1016 loc) · 80.5 KB
Raw

User Guide (Português (Portugal))

🌐 Languages: 🇺🇸 English · 🇪🇹 am · 🇸🇦 ar · 🇦🇿 az · 🇧🇬 bg · 🇧🇩 bn · 🇧🇦 bs · 🇨🇿 cs · 🇩🇰 da · 🇩🇪 de · 🇬🇷 el · 🇪🇸 es · 🇪🇪 et · 🇮🇷 fa · 🇫🇮 fi · 🇫🇷 fr · 🇮🇪 ga · 🇮🇳 gu · 🇳🇬 ha · 🇮🇱 he · 🇮🇳 hi · 🇭🇷 hr · 🇭🇺 hu · 🇦🇲 hy · 🇮🇩 id · 🇳🇬 ig · 🇮🇹 it · 🇯🇵 ja · 🇬🇪 ka · 🇰🇭 km · 🇮🇳 kn · 🇰🇷 ko · 🇱🇹 lt · 🇱🇻 lv · 🇮🇳 ml · 🇮🇳 mr · 🇲🇾 ms · 🇲🇹 mt · 🇲🇲 my · 🇳🇵 ne · 🇳🇱 nl · 🇳🇴 no · 🇮🇳 or · 🇮🇳 pa · 🇵🇭 phi · 🇵🇱 pl · 🇧🇷 pt-BR · 🇷🇴 ro · 🇷🇺 ru · 🇱🇰 si · 🇸🇰 sk · 🇸🇮 sl · 🇷🇸 sr · 🇸🇪 sv · 🇰🇪 sw · 🇮🇳 ta · 🇮🇳 te · 🇹🇭 th · 🇹🇷 tr · 🇺🇦 uk-UA · 🇵🇰 ur · 🇺🇿 uz · 🇻🇳 vi · 🇳🇬 yo · 🇨🇳 zh-CN · 🇹🇼 zh-TW

🌐 Languages: 🇺🇸 English · 🇪🇹 am · 🇸🇦 ar · 🇦🇿 az · 🇧🇬 bg · 🇧🇩 bn · 🇧🇦 bs · 🇨🇿 cs · 🇩🇰 da · 🇩🇪 de · 🇬🇷 el · 🇪🇸 es · 🇪🇪 et · 🇮🇷 fa · 🇫🇮 fi · 🇫🇷 fr · 🇮🇪 ga · 🇮🇳 gu · 🇳🇬 ha · 🇮🇱 he · 🇮🇳 hi · 🇭🇷 hr · 🇭🇺 hu · 🇦🇲 hy · 🇮🇩 id · 🇳🇬 ig · 🇮🇹 it · 🇯🇵 ja · 🇬🇪 ka · 🇰🇭 km · 🇮🇳 kn · 🇰🇷 ko · 🇱🇹 lt · 🇱🇻 lv · 🇮🇳 ml · 🇮🇳 mr · 🇲🇾 ms · 🇲🇹 mt · 🇲🇲 my · 🇳🇵 ne · 🇳🇱 nl · 🇳🇴 no · 🇮🇳 or · 🇮🇳 pa · 🇵🇭 phi · 🇵🇱 pl · 🇧🇷 pt-BR · 🇷🇴 ro · 🇷🇺 ru · 🇱🇰 si · 🇸🇰 sk · 🇸🇮 sl · 🇷🇸 sr · 🇸🇪 sv · 🇰🇪 sw · 🇮🇳 ta · 🇮🇳 te · 🇹🇭 th · 🇹🇷 tr · 🇺🇦 uk-UA · 🇵🇰 ur · 🇺🇿 uz · 🇻🇳 vi · 🇳🇬 yo · 🇨🇳 zh-CN · 🇹🇼 zh-TW

Guia completo para configurar fornecedores, criar combinações, integrar ferramentas de CLI e implementar o OmniRoute.

Índice

💰 Preços em Resumo

Nível Fornecedor Custo Reposição da quota Mais indicado para
💳 SUBSCRIÇÃO Claude Code (Pro) $20/mês 5 h + semanal Quem já tem subscrição
Codex (Plus/Pro) $20-200/mês 5 h + semanal Utilizadores da OpenAI
GitHub Copilot $10-19/mês Mensal Utilizadores do GitHub
🔑 CHAVE DE API DeepSeek Pagamento por uso Nenhuma Raciocínio económico
Groq Pagamento por uso Nenhuma Inferência ultrarrápida
xAI (Grok) Pagamento por uso Nenhuma Raciocínio com o Grok 4
Mistral Pagamento por uso Nenhuma Modelos alojados na UE
Perplexity Pagamento por uso Nenhuma Pesquisa aumentada
Together AI Pagamento por uso Nenhuma Modelos de código aberto
Fireworks AI Pagamento por uso Nenhuma Imagens FLUX rápidas
Cerebras Pagamento por uso Nenhuma Velocidade à escala de wafer
Cohere Pagamento por uso Nenhuma RAG com Command R+
NVIDIA NIM Pagamento por uso Nenhuma Modelos empresariais
Baidu Qianfan Pagamento por uso Nenhuma Modelos ERNIE
💰 ECONÓMICO GLM-4.7 $0.6/1M Diariamente às 10:00 Alternativa de baixo custo
MiniMax M2.1 $0.2/1M Período móvel de 5 horas Opção mais barata
Kimi K2 $9/mês, fixo 10M tokens/mês Custo previsível
🆓 GRATUITO Qoder $0 Aplicam-se os limites do fornecedor Verificar o catálogo atual
Kiro $0 ~50 créditos/mês Claude gratuito

🎯 Casos de Utilização

Caso 1: "Tenho uma subscrição Claude Pro"

Problema: A quota expira sem ser utilizada e são atingidos limites de utilização durante sessões intensivas de programação

Combinação: "maximize-claude"
  1. cc/claude-opus-4-7        (utilizar totalmente a subscrição)
  2. glm/glm-4.7               (alternativa económica quando a quota se esgota)
  3. if/qwen3.8-max-preview       (recurso de emergência gratuito)

Custo mensal: $20 (subscrição) + ~$5 (alternativa) = $25 no total
em comparação com $20 + atingir os limites = frustração

Caso 2: "Quero um custo zero"

Problema: Não consigo pagar subscrições e preciso de uma IA fiável para programação

Combinação: "zero-cost"
  1. if/kimi-k2.7-code          (acesso gratuito indicado; podem aplicar-se limites de utilização)
  2. kr/qwen3-coder-next        (Kiro como alternativa gratuita)

Custo mensal: $0
Qualidade: verifique o modelo, os limites, a privacidade e o SLA para a sua carga de trabalho

Caso 3: "Preciso de programar 24 horas por dia, 7 dias por semana, sem interrupções"

Problema: Tenho prazos a cumprir e não posso permitir períodos de indisponibilidade

Combinação: "always-on"
  1. cc/claude-opus-4-7        (melhor qualidade)
  2. cx/gpt-5.5                (segunda subscrição)
  3. glm/glm-4.7               (económico, reposto diariamente)
  4. minimax/MiniMax-M2.1      (o mais barato, reposição a cada 5 h)
  5. if/deepseek-v4-flash       (acesso gratuito indicado; podem aplicar-se limites de utilização)

Resultado: 5 níveis de recurso aumentam a resiliência; a disponibilidade dos serviços a montante não é garantida
Custo mensal: $20-200 (subscrições) + $10-20 (alternativas)

Caso 4: "Quero IA GRATUITA no OpenClaw"

Problema: Preciso de um assistente de IA em aplicações de mensagens, totalmente gratuito

Combinação: "openclaw-free"
  1. if/qwen3.8-max-preview     (acesso gratuito indicado; podem aplicar-se limites de utilização)
  2. if/deepseek-v4-flash       (acesso gratuito indicado; podem aplicar-se limites de utilização)
  3. if/kimi-k2.7-code          (acesso gratuito indicado; podem aplicar-se limites de utilização)

Custo mensal: $0
Acesso através de: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...

📖 Configuração de fornecedores

Para adicionar em massa ligações de chaves de API a partir de um ficheiro CSV ou JSON, utilize Painel → Fornecedores → Importar de ficheiro. As colunas são posicionais (provider,name,apiKey,baseUrl,priority); provider tem de existir previamente como fornecedor gerido ou nó compatível. Consulte Importar fornecedores de um ficheiro CSV ou JSON.

🔐 Fornecedores de subscrição

Claude Code (Pro/Max)

Painel → Fornecedores → Ligar Claude Code
→ Início de sessão OAuth → Atualização automática do token
→ Monitorização da quota de 5 horas + semanal

Modelos:
  cc/claude-opus-4-7
  cc/claude-sonnet-4-6
  cc/claude-haiku-4-5-20251001

Dica profissional: Utilize o Opus para tarefas complexas e o Sonnet para obter velocidade. O OmniRoute monitoriza a quota por modelo!

Não tem um navegador no anfitrião do OmniRoute? Execute claude setup-token em qualquer local onde tenha sessão iniciada no Claude Code e cole o token válido por um ano no separador Token de configuração. Consulte Claude Code com um token de configuração.

As rotas compatíveis com Claude e Claude Code preservam o esforço de raciocínio max para os modelos Opus e Sonnet. Os modelos Haiku não aceitam o nível de esforço max, pelo que o OmniRoute reduz esse pedido para um orçamento de raciocínio elevado antes de o enviar para o serviço a montante.

OpenAI Codex (Plus/Pro)

Painel → Fornecedores → Ligar Codex
→ Início de sessão OAuth (porta 1455)
→ Reposição a cada 5 horas + semanal

Modelos:
  cx/gpt-5.5
  cx/gpt-5.4
  cx/gpt-5.3-codex
  cx/gpt-5.3-codex-spark

GitHub Copilot

Painel → Fornecedores → Ligar GitHub
→ OAuth através do GitHub
→ Reposição mensal (dia 1 do mês)

Modelos:
  gh/gpt-5.5
  gh/gpt-5.4
  gh/claude-sonnet-4.6
  gh/claude-opus-4.7
  gh/gemini-3.1-pro-preview

Créditos de IA (faturação baseada em tokens). Quando o GitHub comunica credits_used para a conta, o cartão Limites do fornecedor apresenta uma linha Créditos de IA com os créditos consumidos no período de faturação atual, incluindo nos planos de organização ilimitados.

Limite local de Créditos de IA. Edite uma ligação do GitHub e defina Limite de Créditos de IA por período de faturação (providerSpecificData.githubCreditLimit). Deixar em branco desativa-o; 0 ignora sempre a ligação. Quando a última leitura de utilização for igual ou superior ao limite, a seleção de conta ignora essa ligação e o encaminhamento recorre às outras ligações, tal como acontece com um corte definido pela política de quota. A verificação utiliza os dados de utilização que a atualização periódica da quota já recolhe — nunca contacta o GitHub durante o processamento do pedido — e falha de forma permissiva: uma leitura em falta ou desatualizada (com mais de 15 minutos ou referente a um período de faturação que já foi reposto) não bloqueia a ligação. Esta é uma salvaguarda local, não um limite de despesa garantido: atrasos na comunicação do GitHub, o intervalo de atualização, pedidos em curso e utilização fora do OmniRoute podem fazer com que o limite seja ultrapassado. Utilize os próprios controlos de despesa do GitHub para definir um limite rígido.

💰 Fornecedores económicos

GLM-4.7 (reposição diária, $0.6/1M)

  1. Registe-se: Zhipu AI
  2. Obtenha a chave de API através do Coding Plan
  3. Painel → Adicionar chave de API: Fornecedor: glm, Chave de API: your-key

Utilização: glm/glm-4.7 — Dica profissional: O Coding Plan oferece 3× a quota por 1/7 do custo! Reposição diária às 10:00.

MiniMax M2.1 (reposição a cada 5 horas, $0.20/1M)

  1. Registe-se: MiniMax
  2. Obtenha a chave de API → Painel → Adicionar chave de API

Utilização: minimax/MiniMax-M2.1 — Dica profissional: A opção mais económica para contextos longos (1M de tokens)!

Kimi K2 ($9/mês, preço fixo)

  1. Subscreva: Moonshot AI
  2. Obtenha a chave de API → Painel → Adicionar chave de API

Utilização: kimi/kimi-k2.5 — Dica profissional: $9/mês fixos por 10M de tokens = custo efetivo de $0.90/1M!

Baidu Qianfan / ERNIE

  1. Registe-se: Baidu AI Cloud Qianfan
  2. Crie uma chave de API Qianfan → Painel → Adicionar chave de API: Fornecedor: qianfan

Utilização: qianfan/ernie-5.1, qianfan/ernie-x1.1 ou outro ID de modelo compatível com OpenAI do Qianfan.

🆓 Fornecedores GRATUITOS

Os fornecedores gratuitos que não requerem autenticação têm um interruptor junto a Não é necessária autenticação na respetiva página. Desativá-lo desativa o fornecedor, remove-o das vistas de fornecedores configurados/compactos e remove os respetivos modelos de /v1/models.

Qoder (9 modelos GRATUITOS)

Painel → Ligar Qoder → Início de sessão OAuth → O acesso está sujeito aos limites atuais do fornecedor

Modelos: if/qwen3.8-max-preview, if/qwen3.7-max, if/qwen3.7-plus, if/kimi-k3, if/kimi-k2.7-code, if/glm-5.2, if/deepseek-v4-pro, if/deepseek-v4-flash, if/minimax-m3

Kiro (Claude GRATUITO)

Painel → Ligar Kiro → AWS Builder ID ou Google/GitHub → ~50 créditos/mês

Modelos: kr/claude-sonnet-4.5, kr/claude-haiku-4.5

🎨 Combinações

Pode reordenar os cartões de combinações diretamente em Painel → Combinações, arrastando a pega de cada cartão. A ordem é armazenada no SQLite e restaurada ao recarregar.

Exemplo 1: Maximizar a subscrição → Alternativa económica

Painel → Combinações → Criar nova

Nome: premium-coding
Modelos:
  1. cc/claude-opus-4-7 (Subscrição principal)
  2. glm/glm-4.7 (Alternativa económica, $0.6/1M)
  3. minimax/MiniMax-M2.7 (Recurso mais barato, $0.3/1M)

Utilizar na CLI: premium-coding

Exemplo 2: Apenas gratuitos (Custo zero)

Nome: free-combo
Modelos:
  1. if/kimi-k2.7-code (acesso gratuito indicado; podem aplicar-se limites do fornecedor)
  2. kr/qwen3-coder-next (alternativa gratuita do Kiro)

Custo: atualmente indicado como $0; os termos e a disponibilidade podem mudar

🔧 Integração com a CLI

Cursor IDE

Utilizar o Cursor como cliente do OmniRoute (encaminhar o chat do Cursor através do OmniRoute):

Definições → Modelos → Avançadas:
  URL base da API OpenAI: http://localhost:20128/v1
  Chave da API OpenAI: [do painel do OmniRoute]
  Modelo: cc/claude-opus-4-7

Utilizar o OmniRoute como fornecedor do Cursor (o OmniRoute faz chamadas a montante para o Cursor): dê preferência a Painel → Fornecedores → Cursor → Iniciar sessão com o Cursor. No Docker, consulte docs/providers/CURSOR-DOCKER.md.

Claude Code

Edite ~/.claude/settings.json:

{
  "env": {
    "ANTHROPIC_BASE_URL": "http://localhost:20128",
    "ANTHROPIC_AUTH_TOKEN": "your-omniroute-api-key"
  }
}

Utilize aqui o endpoint raiz compatível com o Claude. Não acrescente /v1 a ANTHROPIC_BASE_URL.

Codex CLI

export OPENAI_BASE_URL="http://localhost:20128"
export OPENAI_API_KEY="your-omniroute-api-key"
codex "your prompt"

OpenClaw

Edite ~/.openclaw/openclaw.json:

{
  "agents": {
    "defaults": {
      "model": { "primary": "omniroute/if/kimi-k2.7-code" }
    }
  },
  "models": {
    "providers": {
      "omniroute": {
        "baseUrl": "http://localhost:20128/v1",
        "apiKey": "your-omniroute-api-key",
        "api": "openai-completions",
        "models": [{ "id": "if/kimi-k2.7-code", "name": "Kimi K2.7 Code" }]
      }
    }
  }
}

Ou utilize o Painel: Ferramentas da CLI → OpenClaw → Configuração automática

Cline / Continue / RooCode

Fornecedor: Compatível com OpenAI
URL base: http://localhost:20128/v1
Chave da API: [do painel]
Modelo: cc/claude-opus-4-7

🚀 Implementação

Instalação global através do npm (Recomendado)

npm install -g omniroute

# Criar o diretório de configuração
mkdir -p ~/.omniroute

# Criar o ficheiro .env (consulte .env.example)
cp .env.example ~/.omniroute/.env

# Iniciar o servidor
omniroute
# Ou com uma porta personalizada:
omniroute --port 3000

A CLI carrega automaticamente o .env a partir de ~/.omniroute/.env ou ./.env.

Modo da área de notificação

Inicie o OmniRoute na área de notificação do sistema:

omniroute serve --tray

O comando termina depois de o servidor e o ícone da área de notificação estarem prontos.

O servidor continua em execução sem o terminal.

O modo da área de notificação é compatível com macOS, Windows e sessões gráficas de Linux. O modo da área de notificação não abre automaticamente o painel.

Utilize o menu da área de notificação para as seguintes ações:

  • Abrir o painel.
  • Abrir /dashboard/logs.
  • Alterar o arranque automático.
  • Parar o OmniRoute.

Não combine --tray com estas opções:

  • --daemon
  • --log
  • --no-recovery

Estes modos exigem uma gestão de processos diferente.

Ative o arranque no próximo início de sessão da máquina:

omniroute autostart enable

O arranque automático utiliza o modo da área de notificação no macOS, Windows e em sessões gráficas de Linux. O Linux sem interface gráfica utiliza o serviço de utilizador systemd existente.

Desative o arranque no início de sessão:

omniroute autostart disable

Desinstalação

Quando já não precisar do OmniRoute, disponibilizamos dois scripts rápidos para uma remoção limpa:

Comando Ação
npm run uninstall Remove a aplicação do sistema, mas mantém a sua BD e configurações em ~/.omniroute.
npm run uninstall:full Remove a aplicação E elimina permanentemente todas as configurações, chaves e bases de dados.

Nota: Para executar estes comandos, aceda à pasta do projeto OmniRoute (caso o tenha clonado) e execute-os. Em alternativa, se estiver instalado globalmente, basta executar npm uninstall -g omniroute.

Implementação num VPS

git clone https://github.com/diegosouzapw/OmniRoute.git
cd OmniRoute && npm install && npm run build

export JWT_SECRET="your-secure-secret-change-this"
export INITIAL_PASSWORD="your-password"
export DATA_DIR="/var/lib/omniroute"
export PORT="20128"
export HOSTNAME="0.0.0.0"
export NODE_ENV="production"
export NEXT_PUBLIC_BASE_URL="http://localhost:20128"
export API_KEY_SECRET="endpoint-proxy-api-key-secret"

npm run start
# Ou: pm2 start npm --name omniroute -- start

Implementação com PM2 (Pouca memória)

Para servidores com RAM limitada, utilize a opção de limite de memória:

# Com um limite de 512MB (predefinição)
pm2 start npm --name omniroute -- start

# Ou com um limite de memória personalizado
OMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start

# Ou utilizando ecosystem.config.js
pm2 start ecosystem.config.js

Crie ecosystem.config.js:

module.exports = {
  apps: [
    {
      name: "omniroute",
      script: "npm",
      args: "start",
      env: {
        NODE_ENV: "production",
        OMNIROUTE_MEMORY_MB: "512",
        JWT_SECRET: "your-secret",
        INITIAL_PASSWORD: "your-password",
      },
      node_args: "--max-old-space-size=512",
      max_memory_restart: "300M",
    },
  ],
};

Docker

# Criar a imagem (predefinição = runner-cli com codex/claude/droid pré-instalados)
docker build -t omniroute:cli .

# Modo portátil (recomendado)
docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli

Para o modo integrado com o anfitrião e com binários da CLI, consulte a secção Docker na documentação principal.

Void Linux (xbps-src)

Os utilizadores do Void Linux podem empacotar e instalar o OmniRoute nativamente utilizando a infraestrutura de compilação cruzada xbps-src. Isto automatiza a compilação autónoma do Node.js, juntamente com os bindings nativos necessários do better-sqlite3.

Ver o template xbps-src 
# Ficheiro de template para 'omniroute'
pkgname=omniroute
version=3.8.0
revision=1
hostmakedepends="nodejs python3 make"
depends="openssl"
short_desc="Universal AI gateway with smart routing for multiple LLM providers"
maintainer="zenobit <zenobit@disroot.org>"
license="MIT"
homepage="https://github.com/diegosouzapw/OmniRoute"
distfiles="https://github.com/diegosouzapw/OmniRoute/archive/refs/tags/v${version}.tar.gz"
checksum=009400afee90a9f32599d8fe734145cfd84098140b7287990183dde45ae2245b
system_accounts="_omniroute"
omniroute_homedir="/var/lib/omniroute"
export NODE_ENV=production
export npm_config_engine_strict=false
export npm_config_loglevel=error
export npm_config_fund=false
export npm_config_audit=false

do_build() {
	# Determinar a arquitetura da CPU de destino para o node-gyp
	local _gyp_arch
	case "$XBPS_TARGET_MACHINE" in
		aarch64*) _gyp_arch=arm64 ;;
		armv7*|armv6*) _gyp_arch=arm ;;
		i686*) _gyp_arch=ia32 ;;
		*) _gyp_arch=x64 ;;
	esac

	# 1) Instalar todas as dependências – ignorar scripts
	NODE_ENV=development npm ci --ignore-scripts

	# 2) Compilar o pacote autónomo do Next.js
	npm run build

	# 3) Copiar os recursos estáticos para o pacote autónomo
	cp -r .next/static .next/standalone/.next/static
	[ -d public ] && cp -r public .next/standalone/public || true

	# 4) Compilar o binding nativo do better-sqlite3
	local _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js
	(cd node_modules/better-sqlite3 && node "$_node_gyp" rebuild --arch="$_gyp_arch")

	# 5) Colocar o binding compilado no pacote autónomo
	local _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release
	mkdir -p "$_bs3_release"
	cp node_modules/better-sqlite3/build/Release/better_sqlite3.node "$_bs3_release/"

	# 6) Remover os pacotes do sharp específicos de cada arquitetura
	rm -rf .next/standalone/node_modules/@img

	# 7) Copiar as dependências de runtime do pino omitidas pela análise estática do Next.js:
	for _mod in pino-abstract-transport split2 process-warning; do
		cp -r "node_modules/$_mod" .next/standalone/node_modules/
	done
}

do_check() {
	npm run test:unit
}

do_install() {
	vmkdir usr/lib/omniroute/.next
	vcopy .next/standalone/. usr/lib/omniroute/.next/standalone

	# Impedir a remoção dos diretórios vazios do router da aplicação Next.js pelo hook de pós-instalação
	for _d in \
		.next/standalone/.next/server/app/dashboard \
		.next/standalone/.next/server/app/dashboard/settings \
		.next/standalone/.next/server/app/dashboard/providers; do
		touch "${DESTDIR}/usr/lib/omniroute/${_d}/.keep"
	done

	cat > "${WRKDIR}/omniroute" <<'EOF'
#!/bin/sh
export PORT="${PORT:-20128}"
export DATA_DIR="${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}"
export APP_LOG_TO_FILE="${APP_LOG_TO_FILE:-false}"
mkdir -p "${DATA_DIR}"
exec node /usr/lib/omniroute/.next/standalone/server.js "$@"
EOF
	vbin "${WRKDIR}/omniroute"
}

post_install() {
	vlicense LICENSE
}

Variáveis de ambiente

Variável Predefinição Descrição
JWT_SECRET omniroute-default-secret-change-me Segredo de assinatura JWT (alterar em produção)
INITIAL_PASSWORD CHANGEME Palavra-passe do primeiro início de sessão
DATA_DIR ~/.omniroute Diretório de dados (base de dados, utilização, registos)
PORT predefinição da framework Porta do serviço (20128 nos exemplos)
HOSTNAME predefinição da framework Anfitrião de escuta (o Docker usa 0.0.0.0 por predefinição)
NODE_ENV predefinição do runtime Defina como production para a implementação
NEXT_PUBLIC_BASE_URL http://localhost:20128 URL base pública apresentada no painel e exposta ao servidor (substitui a antiga BASE_URL)
NEXT_PUBLIC_CLOUD_URL https://omniroute.dev URL base do endpoint de sincronização com a nuvem (substitui a antiga CLOUD_URL)
API_KEY_SECRET endpoint-proxy-api-key-secret Segredo HMAC para as chaves de API geradas
REQUIRE_API_KEY false Exige uma chave de API Bearer em /v1/*
ALLOW_API_KEY_REVEAL false Permite que os utilizadores autenticados do painel revelem, a pedido, os valores completos das chaves de API armazenadas
PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES 70 Frequência de atualização, no servidor, dos dados em cache dos limites dos fornecedores; os botões de atualização da interface continuam a acionar a sincronização manual
DISABLE_SQLITE_AUTO_BACKUP false Desativa os instantâneos automáticos do SQLite antes de operações de escrita/importação/restauro; as cópias de segurança manuais continuam a funcionar
APP_LOG_TO_FILE true Ativa a gravação em disco dos registos da aplicação e de auditoria
AUTH_COOKIE_SECURE false Força o atributo Secure no cookie de autenticação (atrás de um proxy inverso HTTPS)
CLOUDFLARED_BIN não definido Utiliza um binário cloudflared existente em vez da transferência gerida
CLOUDFLARED_PROTOCOL http2 Transporte para Quick Tunnels geridos (http2, quic ou auto)
OMNIROUTE_MEMORY_MB 512 Limite de heap do Node.js em MB
PROMPT_CACHE_MAX_SIZE 50 Número máximo de entradas na cache de prompts
SEMANTIC_CACHE_MAX_SIZE 100 Número máximo de entradas na cache semântica

Para consultar a referência completa das variáveis de ambiente, consulte o README.

📊 Modelos disponíveis

Ver todos os modelos disponíveis

A lista abaixo é selecionada a partir de open-sse/config/providerRegistry.ts para a v3.8.0. Os catálogos na nuvem (Gemini, OpenRouter, etc.) são sincronizados dinamicamente — para consultar o catálogo completo e atualizado, abra Painel → Fornecedores → [fornecedor] → Modelos disponíveis ou chame GET /api/models/catalog.

Se a lista integrada de um fornecedor estiver desatualizada, utilize Importar de /models nessa página (ou ative a Sincronização automática) para obter o catálogo upstream atualizado. Isto foi verificado na v3.8.50 para o LLM7.io (gemini-3.1-flash-lite) e o UncloseAI (solidrust/Hermes-3-Llama-3.1-8B-AWQ); o acesso anónimo ao Pollinations continuou limitado pelo upstream durante a mesma ronda de testes.

Claude Code (cc/) — OAuth Pro/Max: cc/claude-opus-4-8, cc/claude-opus-4-7, cc/claude-opus-4-6, cc/claude-opus-4-5-20251101, cc/claude-sonnet-4-6, cc/claude-sonnet-4-5-20250929, cc/claude-haiku-4-5-20251001

Codex (cx/) — OAuth Plus/Pro: cx/gpt-5.5 (+ níveis de esforço: gpt-5.5-xhigh, gpt-5.5-high, gpt-5.5-medium, gpt-5.5-low), cx/gpt-5.4, cx/gpt-5.4-mini, cx/gpt-5.3-codex, cx/gpt-5.3-codex-spark

GitHub Copilot (gh/) — OAuth: gh/gpt-5.5, gh/gpt-5.4, gh/gpt-5.4-mini, gh/gpt-5-mini, gh/gpt-5.3-codex, gh/claude-opus-4.7, gh/claude-opus-4.6, gh/claude-opus-4-5-20251101, gh/claude-sonnet-4.6, gh/claude-sonnet-4.5, gh/claude-haiku-4.5, gh/gemini-3.1-pro-preview, gh/gemini-3-flash-preview, gh/oswe-vscode-prime

Kiro (kr/) — OAuth GRATUITO: utilize o catálogo atualizado apresentado em Painel → Fornecedores → Kiro → Modelos disponíveis. A disponibilidade depende da conta e do plano.

Qoder (if/) — OAuth GRATUITO: if/qwen3.8-max-preview, if/qwen3.7-max, if/qwen3.7-plus, if/kimi-k3, if/kimi-k2.7-code, if/glm-5.2, if/deepseek-v4-pro, if/deepseek-v4-flash, if/minimax-m3

GLM (glm/, glm-cn/, zai/, glmt/) — $0.2–0.6/1M: glm/glm-5.1, glm/glm-5, glm/glm-5-turbo, glm/glm-4.7, glm/glm-4.7-flash, glm/glm-4.6, glm/glm-4.6v, glm/glm-4.5, glm/glm-4.5v, glm/glm-4.5-air

MiniMax (minimax/, minimax-cn/) — $0.2/1M: minimax/MiniMax-M2.7, minimax/MiniMax-M2.7-highspeed, minimax/MiniMax-M2.5, minimax/MiniMax-M2.5-highspeed

Kimi (kimi/, kimi-coding/, kimi-coding-apikey/) — $9/mês fixos ou por utilização: kimi/kimi-k2.6, kimi/kimi-k2.5

DeepSeek (ds/) — chave de API: ds/deepseek-v4-pro, ds/deepseek-v4-flash

Groq (groq/) — Ultrarrápido: groq/llama-3.3-70b-versatile, groq/meta-llama/llama-4-maverick-17b-128e-instruct, groq/qwen/qwen3-32b, groq/openai/gpt-oss-120b

xAI (xai/) — Grok nativo: xai/grok-4.3, xai/grok-4.20-multi-agent-0309, xai/grok-4.20-0309-reasoning, xai/grok-4.20-0309-non-reasoning

Mistral (mistral/) — Alojado na UE: mistral/mistral-large-latest, mistral/mistral-medium-3-5, mistral/mistral-small-latest, mistral/codestral-latest

Perplexity (pplx/) — Com pesquisa integrada: pplx/sonar-deep-research, pplx/sonar-reasoning-pro, pplx/sonar-pro, pplx/sonar

Together AI (together/) — Código aberto: together/meta-llama/Llama-3.3-70B-Instruct-Turbo-Free (gratuito), together/meta-llama/Llama-Vision-Free, together/deepseek-ai/DeepSeek-R1-Distill-Llama-70B-Free, together/deepseek-ai/DeepSeek-R1, together/Qwen/Qwen3-235B-A22B, together/meta-llama/Llama-4-Maverick-17B-128E-Instruct-FP8

Fireworks AI (fireworks/) — Inferência rápida: fireworks/accounts/fireworks/models/kimi-k2p6, fireworks/accounts/fireworks/models/minimax-m2p7, fireworks/accounts/fireworks/models/qwen3p6-plus, fireworks/accounts/fireworks/models/glm-5p1, fireworks/accounts/fireworks/models/deepseek-v4-pro

Cerebras (cerebras/) — À escala de wafer: cerebras/zai-glm-4.7, cerebras/gpt-oss-120b

Cohere (cohere/) — Focado em RAG: cohere/command-a-reasoning-08-2025, cohere/command-a-vision-07-2025, cohere/command-a-03-2025, cohere/command-r-08-2024

NVIDIA NIM (nvidia/) — Empresarial: nvidia/google/gemma-4-31b-it, nvidia/nvidia/nemotron-3.5-super-vl-120b-a12b, nvidia/nvidia/nemotron-3-ultra-550b-a55b, nvidia/nvidia/nemotron-3.5-lightning-30b-a3b

Baidu Qianfan (qianfan/) — ERNIE: qianfan/ernie-5.1, qianfan/ernie-5.0-thinking-latest, qianfan/ernie-x1.1

Ollama Cloud (ollama-cloud/): ollama-cloud/deepseek-v4-pro, ollama-cloud/deepseek-v4-flash, ollama-cloud/kimi-k2.6, ollama-cloud/glm-5.1, ollama-cloud/minimax-m2.7, ollama-cloud/gemma4:31b, ollama-cloud/qwen3.5:397b

Gemini (Google Cloud gemini/): Sincronizado em tempo real por chave de API a partir da Google — não existe uma lista estática. Ligue uma chave em Painel → Fornecedores e utilize Modelos disponíveis para importar o catálogo atual (por exemplo, gemini/gemini-3-pro, gemini/gemini-3-flash).

Outros fornecedores compatíveis (selecionados): cohere, databricks, snowflake, together, vertex, alibaba, alibaba-cn, bedrock (através de aws-bedrock), azure-ai, openrouter (catálogo de passagem), siliconflow, hyperbolic, huggingface, featherless-ai, cloudflare-ai, scaleway, deepinfra, vercel-ai-gateway, bazaarlink, friendliai, nous-research, reka, volcengine, ai21, gigachat. Cada um mantém a sua própria lista de modelos em providerRegistry.ts e pode ser sincronizado automaticamente quando o fornecedor disponibiliza um endpoint /models.

Nota sobre os IDs dos modelos: o OmniRoute utiliza IDs nativos dos fornecedores (claude-opus-4-8, gpt-5.5, glm-5.1, MiniMax-M2.7, kimi-k2.5, grok-4.20-0309-reasoning). Alguns IDs incluem versões com pontos porque é assim que a API upstream os espera. Se um modelo não estiver listado acima, execute omniroute models --search <term> ou consulte GET /api/models/catalog para confirmar a disponibilidade.

Recursos avançados 🧩

Modelos personalizados

Adicione qualquer modelo ID a qualquer fornecedor sem esperar por uma atualização da aplicação:

# Via API
curl -X POST http://localhost:20128/api/provider-models \
  -H "Content-Type: application/json" \
  -d '{"provider": "openai", "modelId": "gpt-5.2", "modelName": "GPT-5.2"}'

# List: curl http://localhost:20128/api/provider-models?provider=openai
# Remove: curl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-5.2"

Ou utilize o Painel:** Fornecedores → [Fornecedor] Modelos personalizados →** .

Notas:

  • Os fornecedores OpenRouter e OpenAI/Anthropic-compatible são geridos a partir de** Modelos Disponíveis** apenas. A adição manual, a importação e a sincronização automática estão na mesma lista de modelos disponíveis, pelo que não existe uma secção separada de modelos personalizados para estes fornecedores.
  • O** Modelos personalizados** A secção destina-se a fornecedores que não expõem importações geridas de modelos disponíveis.

Fornecedores personalizados compatíveis com OpenAI

Qualquer gateway que fale o OpenAI API (um proxy auto-hospedado, vLLM, um agregador de terceiros) pode ser adicionado como o seu próprio nó fornecedor:

  1. Fornecedores → Adicionar OpenAI Compatível .
  2. Nome : um rótulo de visualização para o nó.
  3. Prefixo : o nome do encaminhamento. Os clientes chamam os modelos como <prefix>/<model>, pelo que um nó com prefixo mygw serve mygw/gpt-4o-mini. Obrigatório; não há restrição de caracteres.
  4. Tipo API : a família de endpoints que o gateway serve (conclusões de chat, respostas, incorporações, áudio, imagens).
  5. Base URL : a raiz API, até e incluindo /v1 (por exemplo https://gateway.example.com/v1), e não o caminho /chat/completions completo. Os gateways com caminhos não padrão definem-nos em** Configurações avançadas** (percurso do chat, percurso dos modelos).
  6. O** Chave API (para verificação)** campo apenas testa a ligação. Após criar o nó, abra-o e utilize** Adicionar ligação** para armazenar a chave que os pedidos irão utilizar.

O nó obtém um id interno no formato openai-compatible-<apiType>-<uuid>; nunca precisa de o digitar, o prefixo é o nome público.

Prefixos reservados

Um prefixo não pode ser o id ou alias de um fornecedor integrado (por exemplo openai, cf), nem o id de um fornecedor retirado. O resolvedor de modelos verifica os ids e aliases integrados antes dos nós personalizados, pelo que um nó que utiliza um destes prefixos nunca receberia tráfego: <prefix>/model iria para o fornecedor integrado ou falharia o fecho se esse fornecedor fosse desativado. A criação ou edição de um nó com este prefixo é rejeitada com:

prefix: "<prefix>" is a reserved provider prefix — choose a different prefix (reserved ids/aliases cannot be used for custom nodes because requests like <prefix>/model route to a built-in provider or fail closed when retired)

Escolha um prefixo distinto (mygw, acme-proxy). Se os pedidos para um nó personalizado falharem com um erro que nomeia um fornecedor integrado ou as suas credenciais, verifique se o prefixo do nó está reservado: os nós guardados antes da existência desta regra ainda serão armazenados, mas o seu prefixo será encaminhado para o fornecedor integrado. Edite o nó e atribua-lhe um novo prefixo.

Opções de gateway por ligação

Estas chaves vão para o providerSpecificData de uma ligação (por exemplo, através PUT /api/providers/{id}):

  • toolNameMaxLength (inteiro, 1–1024) — para ligações compatíveis com o formato de chat OpenAI cuja gateway rejeita nomes de ferramentas longos. Os nomes mais longos são enviados como aliases curtos e restaurados na resposta.
  • quotaEndpoint — o endpoint quota/credits do gateway, lido para a gama de quotas do painel e encaminhamento com reconhecimento de quotas. Funciona em ligações compatíveis com OpenAI e Anthropic; a forma completa está documentada em open-sse/services/usage/openaiCompatible.ts.
{
  "toolNameMaxLength": 64,
  "quotaEndpoint": {
    "url": "https://gateway.example.com/key/info",
    "auth": "bearer",
    "quotas": {
      "budget": { "used": "$.info.spend", "total": "$.info.max_budget", "currency": "USD" }
    }
  }
}

Encadeamento de pares OmniRoute

Outro gateway OmniRoute pode ser adicionado como um** Compatível com OpenAI personalizado** provedor. Utilize o /v1 base URL do peer e uma chave API dedicada e com menos privilégios emitida por esse peer.

Para cadeias recíprocas ou multi-hop, ative o protetor de loop opcional em cada gateway:

# gateway-a
OMNIROUTE_INSTANCE_ID=gateway-a
OMNIROUTE_PEER_URLS=http://gateway-b:20128/v1
OMNIROUTE_PEER_MAX_HOPS=4
# gateway-b
OMNIROUTE_INSTANCE_ID=gateway-b
OMNIROUTE_PEER_URLS=http://gateway-a:20128/v1
OMNIROUTE_PEER_MAX_HOPS=4

Apenas os pedidos enviados para um peer URL explicitamente incluído na lista de permissões recebem o cabeçalho X-OmniRoute-Peer-Trace. Um gateway rejeita uma instância repetida ID ou orçamento de salto esgotado com HTTP 508 Loop Detected; os fornecedores upstream comuns não recebem metadados de pares.

O encadeamento de pares não é replicação de base de dados ou failover de host. Cada gateway mantém estados SQLite, caches, contadores de taxas e sessões independentes. Utilize um proxy reverso com verificação de integridade ou failover de cliente para a disponibilidade active/passive ou active/active e nunca monte uma base de dados SQLite em várias instâncias OmniRoute em execução.

Rotas de fornecedores dedicados

Encaminhe os pedidos diretamente para um fornecedor específico com validação de modelo:

POST http://localhost:20128/v1/providers/openai/chat/completions
POST http://localhost:20128/v1/providers/openai/embeddings
POST http://localhost:20128/v1/providers/fireworks/images/generations

O prefixo do fornecedor é adicionado automaticamente se estiver em falta. Os modelos incompatíveis retornam 400.

Configuração de proxy de rede

# Set global proxy
curl -X PUT http://localhost:20128/api/settings/proxy \
  -d '{"global": {"type":"http","host":"proxy.example.com","port":"8080"}}'

# Per-provider proxy
curl -X PUT http://localhost:20128/api/settings/proxy \
  -d '{"providers": {"openai": {"type":"socks5","host":"proxy.example.com","port":"1080"}}}'

# Test proxy
curl -X POST http://localhost:20128/api/settings/proxy/test \
  -d '{"proxy":{"type":"socks5","host":"proxy.example.com","port":"1080"}}'

Precedência: Específico da chave → Específico do Combo → Específico do fornecedor → Ambiente → global.

Catálogo de modelos API

curl http://localhost:20128/api/models/catalog

Retorna modelos agrupados por fornecedor com tipos (chat, embedding, image).

Sincronização na nuvem

  • Sincronize fornecedores, combinações e definições entre dispositivos
  • Sincronização automática em segundo plano com tempo limite + fail-fast
  • Prefira NEXT_PUBLIC_BASE_URL/NEXT_PUBLIC_CLOUD_URL do lado do servidor em produção

Túnel Rápido Cloudflare

  • Disponível em** Terminais → do painel** para Docker e outras implementações auto-hospedadas
  • Cria um https://*.trycloudflare.com URL temporário que encaminha para o seu endpoint /v1 atual compatível com OpenAI
  • Primeiro, o enable instala cloudflared apenas quando necessário; depois reinicia reutilizar o mesmo binário gerido
  • Os Quick Tunnels não são restaurados automaticamente após um reinício OmniRoute ou do contentor; reative-os no painel quando necessário
  • Os túneis URLs são efémeros e mudam sempre que stop/start o túnel
  • Os túneis rápidos geridos são padronizados para o transporte HTTP/2 para evitar avisos de buffer QUIC UDP barulhentos em contentores restritos
  • Configure CLOUDFLARED_PROTOCOL=quic ou auto se pretender substituir a opção de transporte gerido
  • Defina CLOUDFLARED_BIN se preferir utilizar um binário cloudflared pré-instalado em vez do download gerido
  • Os painéis Cloudflare Quick Tunnel, Tailscale Funnel e ngrok Tunnel podem ser mostrados ou ocultados em** Configurações → Aparência** . Ocultar um painel não interrompe um túnel em execução.

LLM Gateway Intelligence (Fase 9)

  • Cache Semântico - Armazena automaticamente em cache as respostas sem streaming e temperatura = 0 (ignorar com X-OmniRoute-No-Cache: true)
  • Solicitar Idempotência — Desduplica os pedidos em 5s através do cabeçalho Idempotency-Key ou X-Request-Id
  • Acompanhamento do progresso - Eventos SSE event: progress ativados através do cabeçalho X-OmniRoute-Progress: true

Parque do Tradutor

Acesso via** Tradutor → do painel** . Depure e visualize como OmniRoute traduz os pedidos API entre fornecedores.

Modo Finalidade
Parque infantil Selecione os formatos source/target, cole um pedido e veja a saída traduzida instantaneamente
Testador de chat Envie mensagens de chat ao vivo através do proxy e inspecione todo o ciclo request/response
Bancada de testes Execute testes em lote em várias combinações de formatos para verificar a exatidão da tradução
Monitorização ao vivo Assista às traduções em tempo real à medida que os pedidos fluem pelo proxy

Casos de uso:

  • Depure por que razão uma combinação client/provider específica falha
  • Verifique se as etiquetas de pensamento, as chamadas de ferramentas e os avisos do sistema são traduzidos corretamente
  • Compare as diferenças de formato entre os formatos OpenAI, Claude, Gemini e Responses API

Estratégias de encaminhamento

Configurar via** Painel → Configurações Encaminhamento →** . O dashboard expõe as seis estratégias mais utilizadas; combos e o router automático suportam internamente um conjunto mais alargado.

Estratégias visíveis no painel (routing ao nível da conta):

Estratégia Descrição
Preencha primeiro Utiliza as contas por ordem de prioridade – a conta principal trata de todos os pedidos até ficar indisponível
Rodada Robin Percorre todas as contas com um limite fixo configurável (padrão: 3 chamadas por conta)
P2C (poder de duas escolhas) Escolhe 2 contas aleatórias e direciona para a mais saudável – equilibra a carga com a consciência da saúde
Aleatório Seleciona aleatoriamente uma conta para cada pedido utilizando o embaralhamento Fisher-Yates
Menos usado Percursos para a conta com o carimbo de data/hora lastUsedAt mais antigo, distribuindo o tráfego uniformemente
Custo Otimizado Percursos para a conta com o valor de menor prioridade, otimizando para prestadores de menor custo

Combinações avançadas e estratégias automáticas (configurável por combo ou através de prefixos auto/* — ver AUTO-COMBO.md ):

  • priority – ordem estrita, nunca round-robins
  • weighted — tráfego proporcional dividido por pesos por modelo
  • fill-first — drena o primeiro modelo até que os limites sejam atingidos
  • round-robin / strict-random / random
  • p2c (poder de duas escolhas)
  • least-used e cost-optimized
  • auto – baseado na pontuação de todos os candidatos
  • lkgp (último fornecedor válido) – fixa o último fornecedor bem-sucedido e depois volta às regras
  • context-optimized — escolhe o modelo com a maior janela de contexto livre
  • context-relay — encadeia modelos de longo contexto para turnos de seguimento

Cabeçalho de sessão fixa externa

Para afinidade de sessão externa (por exemplo, agentes Claude Code/Codex atrás de proxies reversos), envie:

X-Session-Id: your-session-key

OmniRoute também aceita x_session_id e devolve a chave de sessão efetiva em X-OmniRoute-Session-Id.

Se utilizar o Nginx e enviar cabeçalhos em formato de sublinhado, ative:

underscores_in_headers on;

Aliases de modelo curinga

Crie padrões de caracteres curinga para remapear os nomes dos modelos:

Pattern: claude-sonnet-*     →  Target: cc/claude-sonnet-4-6
Pattern: gpt-*               →  Target: gh/gpt-5.3-codex

Os caracteres coringa suportam * (qualquer caractere) e ? (caracter único).

Cadeias substitutas

Defina cadeias de fallback globais que se aplicam a todos os pedidos:

Chain: production-fallback
  1. cc/claude-opus-4-7
  2. gh/gpt-5.3-codex
  3. glm/glm-4.7

Combinações comuns de fornecedores e padrões de encaminhamento

Aqui estão exemplos de padrões para combinar vários fornecedores e encaminhamento entre eles em OmniRoute:

1. Combinação de agentes de codificação: raciocínio sofisticado com Cost/Speed Fallback

Ideal para agentes de codificação (OpenCode, Claude Code, Cursor, Cline). Encaminha inicialmente para modelos de raciocínio de fronteira, recorrendo a modelos de codificação rápida em caso de esgotamento de quotas ou erros.

  • Painel : Combos → Novo Combo → Nome: agent-coding → Estratégia: Priority
  • Modelos :
    1. claude/claude-sonnet-4-6 (agente de codificação primário)
    2. openai/gpt-4o (substituição secundária de alta capacidade)
    3. deepseek/deepseek-v4-flash (substituição de alta eficiência e relação custo-benefício)
# Example via API
curl -X POST http://localhost:20128/api/combos \
  -H "Authorization: Bearer $OMNIROUTE_MANAGE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "agent-coding",
    "strategy": "priority",
    "models": [
      { "model": "claude/claude-sonnet-4-6" },
      { "model": "openai/gpt-4o" },
      { "model": "deepseek/deepseek-v4-flash" }
    ]
  }'

2. Combinação de failover automático de nível gratuito

Encadeia vários fornecedores de nível gratuito e sem chave para maximizar o tempo de atividade sem custos API.

  • Estratégia : Least Used ou Round Robin (distribui carga entre cotas)
  • Modelos :
    1. groq/llama-3.3-70b-versatile
    2. gemini/gemini-2.5-flash
    3. cerebras/gpt-oss-120b
# Example via CLI
omniroute combo create free-stack \
  --models "groq/llama-3.3-70b-versatile,gemini/gemini-2.5-flash,cerebras/gpt-oss-120b" \
  --strategy round-robin

3. Pipeline multimodal/visão e texto

Combinação de modelos de visão especializados com geração de texto a alta velocidade para fluxos de trabalho que envolvem a compreensão de imagens e a geração de código.

  • Padrão : um combo Priority que lista primeiro os modelos com capacidade de visão e por último um modelo text/code de alto rendimento.
  • Modelos :
    1. gemini/gemini-2.5-pro (forte compreensão image/multimodal )
    2. openai/gpt-4o (visão equilibrada e utilização de ferramentas)
    3. deepseek/deepseek-v4-flash (geração Text/code )

Resiliência e disjuntores

Configurar via** Painel → Configurações Resiliência →** .

OmniRoute implementa a resiliência ao nível do fornecedor com cinco componentes:

  1. Solicitar fila e ritmo — Modelação de pedidos ao nível de sistema:

    • Pedidos por minuto (RPM) — Máximo de pedidos por minuto por conta
    • Tempo mínimo entre pedidos — Intervalo mínimo em milissegundos entre pedidos
    • Máximo de pedidos simultâneos — Máximo de pedidos simultâneos por conta

  2. Arrefecimento da conexão — Configuração por tipo de autenticação para uma única ligação após falhas repetíveis:

    • Recarga básica — Janela de arrefecimento padrão para falhas upstream repetíveis
    • Utilize dicas de nova tentativa upstream — Honra Retry-After oficial ou dicas de redefinição quando fornecidas
    • Etapas máximas de espera — Nível máximo de espera exponencial para avarias repetidas

  3. Disjuntor do fornecedor — Rastreia as falhas do fornecedor de ponta a ponta, marca um fornecedor como degradado no limite de aviso configurado e abre o disjuntor quando o limite de falha configurado é atingido:

    • Limite de degradação — Falhas consecutivas do fornecedor antes de entrar DEGRADED
    • Limite de falha — Falhas consecutivas do fornecedor antes de entrar OPEN
    • Repor tempo limite — Período de tempo antes de o prestador ser testado novamente
    • CLOSED (Saudável) — As solicitações fluem normalmente
    • DEGRADED — As solicitações ainda fluem enquanto as falhas elevadas são rastreadas
    • OPEN — O fornecedor é bloqueado temporariamente após falhas repetidas
    • HALF_OPEN — Testando se o prestador recuperou

    Os limites de taxa 429 com âmbito de ligação permanecem válidos** Arrefecimento da conexão** e não contam para o disjuntor do fornecedor.

    O estado do tempo de execução do disjuntor do fornecedor é mostrado na** Painel → Saúde** apenas.

  4. Aguarde o arrefecimento — Se todas as ligações candidatas já estiverem a arrefecer, OmniRoute poderá aguardar o primeiro arrefecimento e tentar novamente o mesmo pedido do cliente automaticamente.

  5. Detecção automática de limite de taxa — Quando os fornecedores upstream devolvem janelas de espera explícitas, estas dicas substituem o tempo de espera da ligação local quando a configuração está ativada.

Dica profissional: Use o** Saúde** página para inspecionar e repor os disjuntores do fornecedor ativo após uma interrupção. A página Resiliência apenas altera a configuração.

Exportação/importação de base de dados

Gerir backups de base de dados em** Configurações do painel → Sistema e armazenamento →** .

Ação Descrição
Exportar base de dados Descarrega a base de dados SQLite atual como um ficheiro .sqlite
Exportar tudo (. tar.gz) Descarrega um ficheiro de cópia de segurança completo, incluindo: base de dados, definições, combos, ligações de fornecedor (sem credenciais), metadados de chave API
Importar base de dados Faça o upload de um ficheiro .sqlite para substituir a base de dados atual. Um backup de pré-importação é criado automaticamente, a menos que DISABLE_SQLITE_AUTO_BACKUP=true 
# API: Export database
curl -o backup.sqlite http://localhost:20128/api/db-backups/export

# API: Export all (full archive)
curl -o backup.tar.gz http://localhost:20128/api/db-backups/exportAll

# API: Import database
curl -X POST http://localhost:20128/api/db-backups/import \
  -F "file=@backup.sqlite"

Validação de importação: O ficheiro importado é validado quanto à integridade (SQLite pragma check), tabelas necessárias (provider_connections, provider_nodes, combos, api_keys) e tamanho (máximo de 100 MB).

Casos de uso:

  • Migrar OmniRoute entre máquinas
  • Crie cópias de segurança externas para recuperação de desastres
  • Partilhe as definições entre os membros da equipa (exporte todo o ficheiro de partilha → )

Painel de definições

A página de definições está organizada em** 7 guias** para facilitar a navegação:

Guia Conteúdo
General Ferramentas de armazenamento do sistema, comportamento padrão, visibilidade do túnel Endpoint
Aspeto Controlos de tema (light/dark/system), visibilidade da barra lateral, alternância de painel para cartões de túnel Cloudflare/Tailscale/ngrok
AI Pensar no orçamento (passagem/remoção automática/personalizada/adaptativa - ver THINKING_BUDGET.md ), prompt do sistema global, estatísticas de cache de prompt
Segurança definições Login/Password, controlo de acesso IP, autenticação API para /models, bloqueio de fornecedor, protecção de injecção de prompt
Roteamento Estratégia de encaminhamento global (preencher primeiro/round robin/ P2C /aleatório/menos utilizado/custo otimizado), aliases de modelo wildcard, cadeias de fallback, padrões de combinação
Resiliência Fila de solicitação, arrefecimento da ligação, configuração do disjuntor do fornecedor e comportamento de espera pelo arrefecimento
Avançado Configuração de proxy global (HTTP/SOCKS5), substituições de proxy por fornecedor

Geral já não duplica registos de leitura apenas e notas de cache. As definições de retenção e otimização da base de dados são mantidas através de /api/settings/database; a limpeza manual da cache utiliza DELETE /api/cache. Os limites de linha de registo de pedidos e proxy são controlados por CALL_LOGS_TABLE_MAX_ROWS e PROXY_LOGS_TABLE_MAX_ROWS.

Gestão de Custos e Orçamento

Acesso via** Custos → painel** .

Guia Finalidade
Orçamento Defina limites de gastos por chave API com orçamentos daily/weekly/monthly e rastreio em tempo real
Preços Visualizar e editar entradas de preços de modelo — custo por 1 mil tokens input/output por fornecedor 
# API: Set a budget
curl -X POST http://localhost:20128/api/usage/budget \
  -H "Content-Type: application/json" \
  -d '{"keyId": "key-123", "limit": 50.00, "period": "monthly"}'

# API: Get current budget status
curl http://localhost:20128/api/usage/budget

Acompanhamento de custos: Cada pedido regista a utilização do token e calcula o custo utilizando a tabela de preços. Ver detalhes em** Utilização do painel →** por fornecedor, modelo e chave API.

Transcrição de áudio

OmniRoute suporta a transcrição de áudio através do endpoint compatível com OpenAI:

POST /v1/audio/transcriptions
Authorization: Bearer your-api-key
Content-Type: multipart/form-data

# Example with curl
curl -X POST http://localhost:20128/v1/audio/transcriptions \
  -H "Authorization: Bearer your-api-key" \
  -F "file=@audio.mp3" \
  -F "model=openai/whisper-1"

deepgram/nova-3 é a rota nativa do Deepgram e necessita de uma chave API do Deepgram . Se apenas OpenRouter estiver configurado, utilize openrouter/deepgram/nova-3.

Fala para Texto (transcrição) fornecedores:

  • openai/ (compatível com sussurro)
  • groq/ (Groq Whisper Turbo)
  • deepgram/ (família Nova)
  • assemblyai/
  • nvidia/ (periquito, canário)
  • huggingface/ (variantes de sussurro)
  • qwen/

Conversão de texto para voz (POST /v1/audio/speech) fornecedores:

  • openai/ (tts-1, tts-1-hd)
  • hyperbolic/
  • deepgram/ (Aura)
  • nvidia/ (apanha TTS)
  • elevenlabs/
  • huggingface/
  • inworld/
  • cartesia/
  • playht/
  • kie/
  • aws-polly/
  • xiaomi-mimo/
  • coqui/, tortoise/
  • qwen/

Formatos de áudio suportados para transcrição: mp3, wav, m4a, flac, ogg, webm. Os formatos de saída TTS dependem do fornecedor (mp3, wav, opus, pcm, mulaw).

Estratégias de equilíbrio de combinação

Configure o balanceamento por combinação em** Dashboard → Combos → Create/Edit → Estratégia** .

Estratégia Descrição
Round-Robin Gira através dos modelos sequencialmente
Prioridade Experimenta sempre o primeiro modelo; recorre apenas ao erro
Aleatório Escolhe um modelo aleatório do combo para cada pedido
Ponderado Percursos proporcionalmente com base nos pesos atribuídos por modelo
Menos usado Rotas para o modelo com o menor número de pedidos recentes (utiliza métricas combinadas)
Otimizado em termos de custos Percursos para o modelo mais barato disponível (utiliza tabela de preços)

Os padrões de combinação global podem ser definidos em** Painel → Definições → Encaminhamento → Combo Padrões** . Os tempos limite de destino combinados herdam o tempo limite do pedido atual por predefinição. Usar** Tempo limite pretendido (segundos)** em padrões de combo ou num combo individual apenas quando um limite mais curto por alvo deve desencadear um substituto mais rápido.

As otimizações combinadas de latência zero são opcionais. Deixar** Otimizações de latência zero** desativado para evitar que estas características de latência compitam em alvos substitutos, ignorem alvos com base no histórico TTFT ou compactem pedidos de substitutos; a sua ativação permite hedging configurado, saltos preditivos TTFT e compressão de fallback proativa para negociar a fidelidade routing/request por menor latência final.

Desativar** Buffer de token de raciocínio** quando os fornecedores upstream exigem limites rígidos max_tokens / maxOutputTokens. Quando ativado, o encaminhamento combinado apenas adiciona espaço ao modelo de raciocínio para modelos com um limite de saída conhecido e deixa o limite de tokens do cliente inalterado quando o valor do buffer seguro excede esse limite. Se o limite do cliente já estiver acima de um limite conhecido, OmniRoute limita-o a esse limite antes de enviar o pedido upstream.

Painel de saúde

Acesso via** Painel → Saúde** . Visão geral da integridade do sistema em tempo real com 6 cartões:

Cartão O que mostra
Estado do sistema Tempo de atividade, versão, utilização de memória, diretório de dados
Saúde do Prestador Estado de tempo de execução do disjuntor do fornecedor global
Limites de taxa Tempos de espera de ligação ativa por conta com tempo restante
Bloqueios ativos Bloqueios ativos no âmbito do modelo e exclusões temporárias
Cache de Assinatura Estatísticas da cache de desduplicação (chaves ativas, taxa de acertos)
Telemetria de Latência agregação de latência p50/p95/p99 por fornecedor

Dica profissional: A página Saúde é atualizada automaticamente a cada 10 segundos. Utilize a placa do disjuntor para identificar quais os fornecedores que estão a ter problemas.

🤖 Encaminhamento Automático (Configuração zero)

O OmniRoute inclui um encaminhador automático orientado por pontuação que seleciona o melhor modelo para cada pedido entre todos os fornecedores ligados — sem necessidade de manter qualquer combinação. Basta enviar o pedido com um dos prefixos auto/* e o OmniRoute criará dinamicamente uma combinação virtual, atribuindo pontuações aos candidatos com base na latência, custo, taxa de sucesso, adequação ao contexto, aptidão do modelo para a tarefa, falhas recentes, quota e estado do disjuntor.

Prefixo Otimiza para
auto Predefinição equilibrada (latência × custo × taxa de sucesso)
auto/coding Tarefas de programação: dá preferência a Claude, GPT-5, GLM, Kimi, Qwen Coder e programadores DeepSeek
auto/cheap Menor custo por token, aceitando uma latência superior
auto/fast Menor latência, ignorando o custo
auto/offline Apenas fornecedores locais (Ollama, vLLM, llama.cpp) — útil para configurações isoladas da rede
auto/smart Prioriza a qualidade do raciocínio (Opus, GPT-5 xhigh, R1, raciocínio do GLM 5.1)
auto/lkgp "Último fornecedor válido conhecido" — fixa o último fornecedor bem-sucedido e, depois, recorre às regras

Exemplo:

curl -X POST http://localhost:20128/v1/chat/completions \
  -H "Authorization: Bearer $OMNIROUTE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto/coding",
    "messages": [{ "role": "user", "content": "Refactor this Python function" }],
    "stream": true
  }'

O encaminhador automático está totalmente descrito em AUTO-COMBO.md — incluindo como ajustar os pesos de pontuação, colocar fornecedores numa lista negra e inspecionar as decisões de encaminhamento em Painel → Combinação automática.

🔌 Integração com MCP e A2A

O OmniRoute é simultaneamente um servidor MCP (Model Context Protocol) e um servidor A2A (Agent-to-Agent JSON-RPC 2.0). Qualquer IDE ou anfitrião de agentes compatível com MCP pode invocar diretamente as ferramentas do OmniRoute — sem necessidade de qualquer wrapper adicional.

Transportes MCP

  • SSE: http://localhost:20128/api/mcp/sse
  • HTTP transmissível: http://localhost:20128/api/mcp/stream
  • stdio: omniroute --mcp (para plugins de IDE que prefiram stdio)

Ligar o Claude Desktop

Edite ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) ou o equivalente no Windows/Linux:

{
  "mcpServers": {
    "omniroute": {
      "command": "omniroute",
      "args": ["--mcp"]
    }
  }
}

Ligar o Cursor / Continue / MCP do VS Code

Utilize o URL SSE http://localhost:20128/api/mcp/sse e uma chave de API Bearer gerada em Painel → Chaves de API.

Âmbitos

Atualmente, o MCP define 32 âmbitos com nome. Cada chave Bearer pode ser limitada a âmbitos específicos — consulte MCP-SERVER.md para obter o inventário oficial de âmbitos e ferramentas e A2A-SERVER.md para obter o esquema JSON-RPC.

🧠 Sistema de Skills

O OmniRoute disponibiliza uma framework de skills extensível (src/lib/skills/) para que os agentes e o endpoint A2A possam executar rotinas específicas de cada domínio (por exemplo, code-review, summarize, extract-facts, web-research).

  • Interface do Marketplace — Explore e instale skills em Painel → Skills
  • Âmbitos por chave — Restrinja as skills que cada chave de API pode invocar
  • Skills personalizadas — Coloque um ficheiro TypeScript em src/lib/a2a/skills/, registe-o e este poderá ser imediatamente invocado através de A2A

Referência completa: SKILLS.md.

💾 Sistema de Memória

O OmniRoute mantém memória conversacional de longo prazo com recuperação híbrida:

  • SQLite FTS5 para pesquisa por palavras-chave em interações anteriores
  • Armazenamento vetorial Qdrant (opcional) para recuperação semântica
  • Extração automática de factos — entidades, preferências e decisões são resumidas após cada sessão e armazenadas na tabela memory_facts
  • As memórias são isoladas por chave de API e por sessão

Faça a gestão das memórias em Painel → Memória (pesquisar, editar, exportar, eliminar). A interface HTTP (/api/memory/*) permite que os agentes enviem e consultem factos programaticamente — consulte MEMORY.md.

🔔 Webhooks

Subscreva eventos do OmniRoute para monitorização e automatização em tempo real.

  • Crie um webhook em Painel → Webhooks com o URL de destino e o segredo de assinatura HMAC
  • Eventos disponíveis: request.completed, request.failed, provider.unavailable, budget.exceeded, combo.switched, circuit_breaker.opened, circuit_breaker.closed
  • Cada payload inclui X-OmniRoute-Signature (HMAC-SHA256) para verificação
  • Novas tentativas: 3 tentativas com espera exponencial, seguidas de envio para a fila de mensagens não processadas

Esquema completo em WEBHOOKS.md.

☁️ Agentes na Cloud

O OmniRoute integra-se com agentes de programação na cloud (OpenAI Codex Cloud, Devin, Jules, Antigravity), permitindo-lhe enviar tarefas de longa duração a partir do mesmo painel que gere o encaminhamento local.

  • Crie tarefas em Painel → Agentes na Cloud ou através de POST /api/v1/agents/tasks
  • Acompanhe o estado, os registos e os artefactos de cada tarefa
  • Utilize a sua própria chave de API para cada fornecedor — as credenciais nunca saem da instância do OmniRoute

Referência completa: CLOUD_AGENT.md.

🛠️ Gestão Programática

Pode gerir todos os recursos do OmniRoute (fornecedores, combos, chaves, definições) através de HTTP utilizando uma chave Bearer com o âmbito manage.

Gere a chave em Painel → Chaves de API → Nova Chave → Âmbito: manage e, em seguida:

# Listar fornecedores
curl http://localhost:20128/api/providers \
  -H "Authorization: Bearer $OMNIROUTE_MANAGE_KEY"

# Adicionar uma ligação a um fornecedor
curl -X POST http://localhost:20128/api/providers \
  -H "Authorization: Bearer $OMNIROUTE_MANAGE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "provider": "openai", "apiKey": "sk-...", "name": "main" }'

# Criar um combo
curl -X POST http://localhost:20128/api/combos \
  -H "Authorization: Bearer $OMNIROUTE_MANAGE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "premium", "strategy": "priority", "models": [{ "model": "cc/claude-opus-4-7" }, { "model": "glm/glm-5.1" }] }'

# Listar/criar chaves de API
curl http://localhost:20128/api/keys -H "Authorization: Bearer $OMNIROUTE_MANAGE_KEY"
curl -X POST http://localhost:20128/api/keys -H "Authorization: Bearer $OMNIROUTE_MANAGE_KEY" \
  -d '{ "name": "ci-bot", "scopes": ["chat"] }'

Consulte API_REFERENCE.md para ver o catálogo completo de endpoints e os esquemas de pedidos/respostas.

💻 CLI interna

O OmniRoute inclui uma CLI interna (omniroute …) para configuração, diagnóstico e controlo em tempo de execução. Esta é distinta da página "Ferramentas CLI" no painel, que configura CLIs de terceiros (Claude Code, Cursor, Codex, Cline, …) para que possam comunicar com o OmniRoute.

omniroute setup                    # Assistente interativo (palavra-passe, fornecedores, combinações)
omniroute setup --non-interactive  # Adequado para CI
omniroute doctor                   # Diagnósticos de funcionamento (diretório de dados, BD, fornecedores, portas)
omniroute providers available      # Listar fornecedores suportados
omniroute providers list           # Listar ligações configuradas
omniroute providers test <id>      # Testar em tempo real uma ligação a um fornecedor
omniroute combos list              # Listar combinações
omniroute combos switch <name>     # Definir a combinação predefinida
omniroute models                   # Listar modelos disponíveis (--json, --search)
omniroute keys add | list | remove # Gerir chaves de API a partir do terminal
omniroute backup                   # Criar um instantâneo da configuração + BD
omniroute restore [<timestamp>]    # Restaurar a partir de um instantâneo
omniroute health                   # Estado de funcionamento detalhado (disjuntores, cache, memória)
omniroute quota                    # Utilização da quota dos fornecedores
omniroute mcp status               # Estado do servidor MCP
omniroute a2a status               # Estado do servidor A2A
omniroute tunnel list|create|stop  # Túneis Cloudflare/Tailscale/ngrok
omniroute reset-password           # Repor a palavra-passe de administrador
omniroute --mcp                    # Iniciar o servidor MCP através de stdio
omniroute --port 3000              # Iniciar o servidor numa porta personalizada

Sugestão: associe omniroute doctor --json à sua ferramenta de monitorização para receber alertas sobre ligações a fornecedores com problemas.

🖥️ Aplicação para computador (Electron)

O OmniRoute está disponível como uma aplicação nativa para Windows, macOS e Linux.

Instalação

# A partir do diretório electron:
cd electron
npm install

# Modo de desenvolvimento (liga ao servidor de desenvolvimento Next.js em execução):
npm run dev

# Modo de produção (utiliza a compilação autónoma):
npm start

Criação de instaladores

cd electron
npm run build          # Plataforma atual
npm run build:win      # Windows (.exe NSIS)
npm run build:mac      # macOS (.dmg universal)
npm run build:linux    # Linux (.AppImage)

Saída → electron/dist-electron/

Principais funcionalidades

Funcionalidade Descrição
Disponibilidade do servidor Consulta o servidor antes de apresentar a janela (sem ecrã vazio)
Área de notificação Minimizar para a área de notificação, alterar a porta e sair através do respetivo menu
Gestão de portas Alterar a porta do servidor através da área de notificação (reinicia automaticamente o servidor)
Política de Segurança de Conteúdos CSP restritiva através de cabeçalhos de sessão
Instância única Apenas uma instância da aplicação pode ser executada de cada vez
Modo offline O servidor Next.js incluído funciona sem Internet

Variáveis de ambiente

Variável Predefinição Descrição
OMNIROUTE_PORT 20128 Porta do servidor
OMNIROUTE_MEMORY_MB 512 Limite de heap do Node.js (64–16384 MB)

📖 Documentação completa: electron/README.md