User Guide (Português (Brasil))

Sumário

• Visão Geral dos Preços
• Casos de Uso
• Configuração de Provedores
• Integração com CLI
• Implantação
• Modelos Disponíveis
• Recursos Avançados
• Roteamento Automático (Configuração Zero)
• Integração com MCP e A2A
• Sistema de Skills
• Sistema de Memória
• Webhooks
• Agentes na Nuvem
• Gerenciamento Programático
• CLI Interna
• Aplicativo para Desktop (Electron)

---

💰 Visão Geral dos Preços

Categoria	Provedor	Custo	Redefinição da Cota	Melhor Para
💳 ASSINATURA	Claude Code (Pro)	$20/mês	5h + semanal	Quem já possui assinatura
	Codex (Plus/Pro)	$20-200/mês	5h + semanal	Usuários da OpenAI
	GitHub Copilot	$10-19/mês	Mensal	Usuários do GitHub
🔑 CHAVE DE API	DeepSeek	Pague por uso	Nenhuma	Raciocínio barato
	Groq	Pague por uso	Nenhuma	Inferência ultrarrápida
	xAI (Grok)	Pague por uso	Nenhuma	Raciocínio com Grok 4
	Mistral	Pague por uso	Nenhuma	Modelos hospedados na UE
	Perplexity	Pague por uso	Nenhuma	Busca aprimorada
	Together AI	Pague por uso	Nenhuma	Modelos de código aberto
	Fireworks AI	Pague por uso	Nenhuma	Imagens FLUX rápidas
	Cerebras	Pague por uso	Nenhuma	Velocidade em escala de wafer
	Cohere	Pague por uso	Nenhuma	RAG com Command R+
	NVIDIA NIM	Pague por uso	Nenhuma	Modelos empresariais
	Baidu Qianfan	Pague por uso	Nenhuma	Modelos ERNIE
💰 BARATO	GLM-4.7	$0.6/1M	Diariamente às 10h	Alternativa econômica
	MiniMax M2.1	$0.2/1M	Janela móvel de 5 horas	Opção mais barata
	Kimi K2	$9/mês fixos	10M tokens/mês	Custo previsível
🆓 GRATUITO	Qoder	$0	Aplicam-se os limites do provedor	Verifique o catálogo atual
	Kiro	$0	~50 créditos/mês	Claude gratuito

---

🎯 Casos de Uso

Caso 1: “Tenho uma assinatura do Claude Pro”

Problema: A cota expira sem ser usada, e há limites de taxa durante períodos de programação intensa

Combinação: "maximize-claude"
  1. cc/claude-opus-4-7        (use a assinatura por completo)
  2. glm/glm-4.7               (alternativa barata quando a cota acabar)
  3. if/qwen3.8-max-preview       (alternativa gratuita de emergência)

Custo mensal: $20 (assinatura) + ~$5 (alternativa) = $25 no total
em vez de $20 + atingir os limites = frustração

Caso 2: “Quero custo zero”

Problema: Não posso pagar por assinaturas e preciso de uma IA confiável para programação

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

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

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

Problema: Tenho prazos e não posso me dar ao luxo de ficar indisponível

Combinação: "always-on"
  1. cc/claude-opus-4-7        (melhor qualidade)
  2. cx/gpt-5.5                (segunda assinatura)
  3. glm/glm-4.7               (barato, redefinição diária)
  4. minimax/MiniMax-M2.1      (mais barato, redefinição em 5h)
  5. if/deepseek-v4-flash       (acesso gratuito informado; limites de taxa podem ser aplicados)

Resultado: 5 camadas de contingência ampliam a resiliência; a disponibilidade dos serviços upstream não é garantida
Custo mensal: $20-200 (assinaturas) + $10-20 (alternativas)

Caso 4: “Quero IA GRATUITA no OpenClaw”

Problema: Preciso de um assistente de IA em aplicativos de mensagens, totalmente gratuito

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

Custo mensal: $0
Acesso por meio de: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...

---

📖 Configuração de provedores

Para adicionar em massa conexões de chaves de API a partir de um arquivo CSV ou JSON, use Painel → Provedores → Importar de arquivo. As colunas são posicionais (provider,name,apiKey,baseUrl,priority); provider já deve existir como um provedor gerenciado ou um nó compatível. Consulte Importar provedores de um arquivo CSV ou JSON.

🔐 Provedores por assinatura

Claude Code (Pro/Max)

Painel → Provedores → Conectar Claude Code
→ Login via OAuth → Atualização automática do token
→ Monitoramento das cotas de 5 horas + semanal

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

Dica profissional: Use o Opus para tarefas complexas e o Sonnet para obter velocidade. O OmniRoute monitora a cota por modelo!

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, portanto, o OmniRoute reduz essa solicitação para um orçamento de raciocínio alto antes de enviá-la ao provedor upstream.

OpenAI Codex (Plus/Pro)

Painel → Provedores → Conectar Codex
→ Login via OAuth (porta 1455)
→ Redefiniçã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 → Provedores → Conectar GitHub
→ OAuth via GitHub
→ Redefinição mensal (no dia 1º de cada 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

💰 Provedores econômicos

GLM-4.7 (Redefinição diária, US$ 0,6/1M)

1. Cadastre-se: Zhipu AI
2. Obtenha a chave de API no Coding Plan
3. Painel → Adicionar chave de API: Provedor: glm, Chave de API: your-key

Uso: glm/glm-4.7 — Dica profissional: O Coding Plan oferece uma cota 3 vezes maior por 1/7 do custo! Redefinição diária às 10h.

MiniMax M2.1 (Redefinição a cada 5 horas, US$ 0,20/1M)

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

Uso: minimax/MiniMax-M2.1 — Dica profissional: A opção mais barata para contextos longos (1 milhão de tokens)!

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

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

Uso: kimi/kimi-k2.5 — Dica profissional: Valor fixo de US$ 9/mês por 10 milhões de tokens = custo efetivo de US$ 0,90/1M!

Baidu Qianfan / ERNIE

1. Cadastre-se: Baidu AI Cloud Qianfan
2. Crie uma chave de API do Qianfan → Painel → Adicionar chave de API: Provedor: qianfan

Uso: qianfan/ernie-5.1, qianfan/ernie-x1.1 ou outro ID de modelo do Qianfan compatível com a OpenAI.

🆓 Provedores GRATUITOS

Os provedores gratuitos sem autenticação têm um botão ao lado de Nenhuma autenticação necessária na página do provedor. Desativá-lo desabilita esse provedor, remove-o das visualizações configurada/compacta de Provedores e remove seus modelos de /v1/models.

Qoder (9 modelos GRATUITOS)

Painel → Conectar Qoder → Login via OAuth → O acesso está sujeito aos limites atuais do provedor

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 → Conectar Kiro → AWS Builder ID ou Google/GitHub → ~50 créditos/mês

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

---

🎨 Combos

Você pode reordenar os cartões de combos diretamente em Painel → Combos, arrastando a alça de cada cartão. A ordem é armazenada no SQLite e restaurada ao recarregar.

Exemplo 1: Maximizar assinatura → Backup econômico

Painel → Combos → Criar novo

Nome: premium-coding
Modelos:
  1. cc/claude-opus-4-7 (Assinatura principal)
  2. glm/glm-4.7 (Backup econômico, $0.6/1M)
  3. minimax/MiniMax-M2.7 (Alternativa mais barata, $0.3/1M)

Usar na CLI: premium-coding

Exemplo 2: Somente gratuitos (Custo zero)

Nome: free-combo
Modelos:
  1. if/kimi-k2.7-code (listado com acesso gratuito; podem ser aplicados limites do provedor)
  2. kr/qwen3-coder-next (alternativa gratuita do Kiro)

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

---

🔧 Integração com a CLI

Cursor IDE

Usando o Cursor como cliente do OmniRoute (roteie o chat do Cursor pelo OmniRoute):

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

Usando o OmniRoute como provedor do Cursor (o OmniRoute chama o Cursor como upstream): prefira Painel → Provedores → Cursor → Entrar 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"
  }
}

Use 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 use o Painel: Ferramentas de CLI → OpenClaw → Configuração automática

Cline / Continue / RooCode

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

---

🚀 Implantação

Instalação global via npm (Recomendado)

npm install -g omniroute

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

# Criar o arquivo .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 de ~/.omniroute/.env ou ./.env.

Modo de bandeja

Inicie o OmniRoute na bandeja do sistema:

omniroute serve --tray

O comando retorna depois que o servidor e a bandeja estiverem prontos.

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

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

Use o menu da bandeja para estas ações:

• Abrir o painel.
• Abrir /dashboard/logs.
• Alterar a inicialização automática.
• Parar o OmniRoute.

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

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

Esses modos exigem diferentes formas de gerenciamento do processo.

Habilite a inicialização no próximo login da máquina:

omniroute autostart enable

A inicialização automática usa o modo de bandeja no macOS, no Windows e em sessões gráficas do Linux. O Linux sem interface gráfica usa o serviço de usuário systemd existente.

Desabilite a inicialização ao fazer login:

omniroute autostart disable

Desinstalação

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

Comando	Ação
npm run uninstall	Remove o aplicativo do sistema, mas mantém seu banco de dados e suas configurações em ~/.omniroute.
npm run uninstall:full	Remove o aplicativo E apaga permanentemente todas as configurações, chaves e bancos de dados.

Observação: para executar esses comandos, acesse a pasta do projeto OmniRoute (caso você o tenha clonado) e execute-os. Como alternativa, se ele tiver sido instalado globalmente, basta executar npm uninstall -g omniroute.

Implantação em 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

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

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

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

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

# Ou usando 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 (padrã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 ao host com binários da CLI, consulte a seção sobre Docker na documentação principal.

Void Linux (xbps-src)

Os usuários do Void Linux podem empacotar e instalar o OmniRoute nativamente usando o framework de compilação cruzada xbps-src. Isso automatiza a compilação independente do Node.js junto com os bindings nativos necessários do better-sqlite3.

Ver template do xbps-src

# Arquivo 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() {
  # Determina a arquitetura de 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) Instala todas as dependências – ignora os scripts
  NODE_ENV=development npm ci --ignore-scripts

  # 2) Compila o pacote independente do Next.js
  npm run build

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

  # 4) Compila 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) Coloca o binding compilado no pacote independente
  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) Remove os pacotes do sharp específicos da arquitetura
  rm -rf .next/standalone/node_modules/@img

  # 7) Copia 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

  # Impede que os diretórios vazios do roteador de aplicativos do Next.js sejam removidos 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	Padrão	Descrição
JWT_SECRET	omniroute-default-secret-change-me	Segredo de assinatura JWT (altere em produção)
INITIAL_PASSWORD	CHANGEME	Senha do primeiro login
DATA_DIR	~/.omniroute	Diretório de dados (banco de dados, uso, logs)
PORT	padrão do framework	Porta do serviço (20128 nos exemplos)
HOSTNAME	padrão do framework	Host de vinculação (o Docker usa 0.0.0.0 por padrão)
NODE_ENV	padrão do ambiente de execução	Defina como production para implantação
NEXT_PUBLIC_BASE_URL	http://localhost:20128	URL base pública exibida no painel e disponibilizada ao servidor (substitui a variável legada BASE_URL)
NEXT_PUBLIC_CLOUD_URL	https://omniroute.dev	URL base do endpoint de sincronização com a nuvem (substitui a variável legada CLOUD_URL)
API_KEY_SECRET	endpoint-proxy-api-key-secret	Segredo HMAC para chaves de API geradas
REQUIRE_API_KEY	false	Exige uma chave de API Bearer em /v1/*
ALLOW_API_KEY_REVEAL	false	Permite que usuários autenticados do painel revelem, sob demanda, os valores completos das chaves de API armazenadas
PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES	70	Frequência de atualização no servidor para dados em cache de limites dos provedores; os botões da interface ainda acionam a sincronização manual
DISABLE_SQLITE_AUTO_BACKUP	false	Desabilita snapshots automáticos do SQLite antes de gravações/importações/restaurações; backups manuais continuam funcionando
APP_LOG_TO_FILE	true	Habilita a gravação em disco dos logs do aplicativo e de auditoria
AUTH_COOKIE_SECURE	false	Força o cookie de autenticação Secure (atrás de um proxy reverso HTTPS)
CLOUDFLARED_BIN	não definido	Usa um binário cloudflared existente em vez do download gerenciado
CLOUDFLARED_PROTOCOL	http2	Transporte para Quick Tunnels gerenciados (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 no cache de prompts
SEMANTIC_CACHE_MAX_SIZE	100	Número máximo de entradas no cache semântico

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 foi selecionada a partir de open-sse/config/providerRegistry.ts para a v3.8.0. Os catálogos em nuvem (Gemini, OpenRouter etc.) são sincronizados dinamicamente — para consultar o catálogo completo e atualizado, acesse Painel → Provedores → [provedor] → Modelos disponíveis ou chame GET /api/models/catalog.

Se a lista integrada de um provedor estiver desatualizada, use Importar de /models nessa página (ou habilite a Sincronização automática) para obter o catálogo atualizado do serviço upstream. Isso foi verificado na v3.8.50 para LLM7.io (gemini-3.1-flash-lite) e UncloseAI (solidrust/Hermes-3-Llama-3.1-8B-AWQ); o acesso anônimo ao Pollinations continuou limitado pelo serviço upstream durante a mesma rodada 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: use o catálogo atualizado exibido em Painel → Provedores → 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/) — US$ 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/) — US$ 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/) — US$ 9/mês fixos ou por uso: 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/) — Hospedado na UE: mistral/mistral-large-latest, mistral/mistral-medium-3-5, mistral/mistral-small-latest, mistral/devstral-latest, mistral/codestral-latest

Perplexity (pplx/) — Aprimorado com pesquisa: 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/) — Em 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/) — Corporativo: nvidia/z-ai/glm-5.1, nvidia/minimaxai/minimax-m2.7, nvidia/google/gemma-4-31b-it, nvidia/mistralai/mistral-small-4-119b-2603, nvidia/mistralai/mistral-large-3-675b-instruct-2512, nvidia/qwen/qwen3.5-397b-a17b, nvidia/deepseek-ai/deepseek-v4-pro, nvidia/openai/gpt-oss-120b, nvidia/nvidia/nemotron-3-super-120b-a12b

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 do Google — sem lista estática. Conecte uma chave em Painel → Provedores e use Modelos disponíveis para importar o catálogo atual (por exemplo, gemini/gemini-3-pro, gemini/gemini-3-flash).

Outros provedores compatíveis (selecionados): cohere, databricks, snowflake, together, vertex, alibaba, alibaba-cn, bedrock (via 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 sua própria lista de modelos em providerRegistry.ts e pode ser sincronizado automaticamente quando o provedor disponibiliza um endpoint /models.

Observação sobre IDs de modelos: O OmniRoute usa IDs nativos dos provedores (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 acesse GET /api/models/catalog para confirmar a disponibilidade.

---

🧩 Recursos avançados

Modelos personalizados

Adicione qualquer ID de modelo a qualquer provedor sem precisar esperar por uma atualização do aplicativo:

# 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"}'

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

Ou use o Dashboard: Provedores → [Provedor] → Modelos personalizados.

Observações:

• Provedores compatíveis com OpenRouter e OpenAI/Anthropic são gerenciados apenas em Modelos disponíveis. A adição manual, a importação e a sincronização automática são todas direcionadas à mesma lista de modelos disponíveis, portanto não há uma seção separada de Modelos personalizados para esses provedores.
• A seção Modelos personalizados destina-se a provedores que não oferecem importações gerenciadas de modelos disponíveis.

Encadeamento de pares do OmniRoute

Outro gateway OmniRoute pode ser adicionado como um provedor personalizado compatível com OpenAI. Use a URL base /v1 do par e uma chave de API dedicada, com privilégios mínimos, emitida por esse par.

Para cadeias recíprocas ou com múltiplos saltos, habilite a proteção opcional contra loops 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

Somente solicitações enviadas a uma URL de par explicitamente incluída na lista de permissões recebem o cabeçalho X-OmniRoute-Peer-Trace. Um gateway rejeita um ID de instância repetido ou um limite de saltos esgotado com HTTP 508 Loop Detected; provedores upstream comuns não recebem metadados de pares.

O encadeamento de pares não é replicação de banco de dados nem failover de host. Cada gateway mantém estados SQLite, caches, contadores de taxa e sessões independentes. Use um proxy reverso com verificação de integridade ou failover no cliente para disponibilidade ativa/passiva ou ativa/ativa e nunca monte um banco de dados SQLite em várias instâncias do OmniRoute em execução.

Rotas dedicadas de provedores

Encaminhe solicitações diretamente para um provedor 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 provedor é adicionado automaticamente se estiver ausente. Modelos incompatíveis retornam 400.

Configuração de proxy de rede

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

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

# Testar 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 da combinação → Específico do provedor → Global → Ambiente.

API do catálogo de modelos

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

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

Sincronização com a nuvem

• Sincronize provedores, combinações e configurações entre dispositivos
• Sincronização automática em segundo plano com tempo limite + falha rápida
• Em produção, prefira NEXT_PUBLIC_BASE_URL/NEXT_PUBLIC_CLOUD_URL no lado do servidor

Túnel rápido do Cloudflare

• Disponível em Dashboard → Endpoints para Docker e outras implantações auto-hospedadas
• Cria uma URL temporária https://*.trycloudflare.com que encaminha para o endpoint /v1 atual compatível com OpenAI
• A primeira ativação instala o cloudflared somente quando necessário; reinicializações posteriores reutilizam o mesmo binário gerenciado
• Túneis rápidos não são restaurados automaticamente após a reinicialização do OmniRoute ou do contêiner; reative-os pelo dashboard quando necessário
• As URLs dos túneis são efêmeras e mudam sempre que você interrompe/inicia o túnel
• Túneis rápidos gerenciados usam por padrão o transporte HTTP/2 para evitar avisos excessivos sobre o buffer UDP do QUIC em contêineres com recursos limitados
• Defina CLOUDFLARED_PROTOCOL=quic ou auto se quiser substituir a opção de transporte gerenciada
• Defina CLOUDFLARED_BIN se preferir usar um binário cloudflared pré-instalado em vez do download gerenciado
• Os painéis Túnel rápido do Cloudflare, Tailscale Funnel e ngrok Tunnel podem ser exibidos ou ocultados em Configurações → Aparência. Ocultar um painel não interrompe um túnel em execução.

Inteligência do gateway de LLM (Fase 9)

• Cache semântico — Armazena automaticamente em cache respostas sem streaming e com temperature=0 (ignore o cache com X-OmniRoute-No-Cache: true)
• Idempotência de solicitações — Elimina solicitações duplicadas em um intervalo de 5s por meio do cabeçalho Idempotency-Key ou X-Request-Id
• Acompanhamento do progresso — Eventos SSE opcionais event: progress por meio do cabeçalho X-OmniRoute-Progress: true

---

Playground do tradutor

Acesse por Dashboard → Tradutor. Depure e visualize como o OmniRoute traduz solicitações de API entre provedores.

Modo	Finalidade
Playground	Selecione os formatos de origem/destino, cole uma solicitação e veja instantaneamente a saída traduzida
Testador de chat	Envie mensagens de chat em tempo real pelo proxy e inspecione o ciclo completo de solicitação/resposta
Bancada de testes	Execute testes em lote com várias combinações de formatos para verificar se a tradução está correta
Monitor em tempo real	Acompanhe traduções em tempo real enquanto as solicitações passam pelo proxy

Casos de uso:

• Depurar por que uma combinação específica de cliente/provedor falha
• Verificar se tags de raciocínio, chamadas de ferramentas e prompts de sistema são traduzidos corretamente
• Comparar diferenças de formato entre OpenAI, Claude, Gemini e os formatos da Responses API

---

Estratégias de roteamento

Configure em Dashboard → Settings → Routing. O dashboard apresenta as seis estratégias mais usadas; os combos e o roteador automático oferecem internamente suporte a um conjunto mais amplo.

Estratégias visíveis no dashboard (roteamento no nível da conta):

Estratégia	Descrição
Preencher Primeiro	Usa as contas por ordem de prioridade — a conta principal processa todas as solicitações até ficar indisponível
Round Robin	Alterna entre todas as contas com um limite configurável de afinidade (padrão: 3 chamadas por conta)
P2C (Power of Two Choices)	Escolhe 2 contas aleatórias e encaminha para a mais saudável — equilibra a carga considerando a integridade
Aleatória	Seleciona aleatoriamente uma conta para cada solicitação usando o embaralhamento Fisher-Yates
Menos Usada	Encaminha para a conta com o timestamp lastUsedAt mais antigo, distribuindo o tráfego uniformemente
Otimizada por Custo	Encaminha para a conta com o menor valor de prioridade, otimizando para os provedores de menor custo

Estratégias avançadas de combo e automáticas (configuráveis por combo ou por meio de prefixos auto/* — consulte AUTO-COMBO.md):

• priority — ordem estrita, nunca usa round-robin
• weighted — divisão proporcional do tráfego por pesos definidos para cada modelo
• fill-first — usa o primeiro modelo até atingir os limites
• round-robin / strict-random / random
• p2c (Power of Two Choices)
• least-used e cost-optimized
• auto — orientada por pontuação entre todos os candidatos
• lkgp (Last Known Good Provider) — fixa no último provedor bem-sucedido e, em seguida, recorre às regras
• context-optimized — escolhe o modelo com a maior janela de contexto livre
• context-relay — encadeia modelos de contexto longo para turnos subsequentes

Cabeçalho externo de sessão persistente

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

X-Session-Id: your-session-key

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

Se você usa Nginx e envia cabeçalhos que contêm sublinhados, habilite:

underscores_in_headers on;

Aliases de modelo com curingas

Crie padrões com curingas para remapear nomes de modelos:

Padrão: claude-sonnet-*     →  Destino: cc/claude-sonnet-4-6
Padrão: gpt-*               →  Destino: gh/gpt-5.3-codex

Os curingas aceitam * (quaisquer caracteres) e ? (um único caractere).

Cadeias de fallback

Defina cadeias globais de fallback que se aplicam a todas as solicitações:

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

---

Resiliência e disjuntores

Configure em Dashboard → Settings → Resilience.

O OmniRoute implementa resiliência no nível do provedor com cinco componentes:

1. Fila e controle de ritmo das solicitações — Controle de solicitações no nível do sistema:

   • Solicitações por minuto (RPM) — Número máximo de solicitações por minuto por conta
   • Tempo mínimo entre solicitações — Intervalo mínimo em milissegundos entre solicitações
   • Máximo de solicitações simultâneas — Número máximo de solicitações simultâneas por conta

2. Cooldown da conexão — Configuração por tipo de autenticação para uma única conexão após falhas que permitem novas tentativas:

   • Cooldown base — Período padrão de cooldown para falhas de upstream que permitem novas tentativas
   • Usar sugestões de nova tentativa do upstream — Respeita indicações oficiais de Retry-After ou de redefinição quando fornecidas
   • Máximo de etapas de backoff — Nível máximo de backoff exponencial para falhas repetidas

3. Disjuntor do provedor — Monitora falhas de ponta a ponta do provedor, marca um provedor como degradado no limite de alerta configurado e abre o disjuntor quando o limite de falhas configurado é atingido:

   • Limite de degradação — Número de falhas consecutivas do provedor antes de entrar em DEGRADED
   • Limite de falhas — Número de falhas consecutivas do provedor antes de entrar em OPEN
   • Tempo limite de redefinição — Período antes que o provedor seja testado novamente
   • CLOSED (Saudável) — As solicitações fluem normalmente
   • DEGRADED — As solicitações continuam fluindo enquanto o aumento das falhas é monitorado
   • OPEN — O provedor é temporariamente bloqueado após falhas repetidas
   • HALF_OPEN — Verifica se o provedor se recuperou

   Os limites de taxa 429 no escopo da conexão permanecem no Cooldown da conexão e não são contabilizados pelo disjuntor do provedor.

   O estado do disjuntor do provedor em tempo de execução é exibido apenas em Dashboard → Health.

4. Aguardar o cooldown — Se todas as conexões candidatas já estiverem em cooldown, o OmniRoute poderá aguardar o cooldown que terminar primeiro e repetir automaticamente a mesma solicitação do cliente.

5. Detecção automática de limite de taxa — Quando os provedores upstream retornam períodos de espera explícitos, essas indicações substituem o cooldown local da conexão quando a configuração está habilitada.

Dica profissional: Use a página Health para inspecionar e redefinir disjuntores ativos de provedores após uma interrupção. A página Resilience altera apenas a configuração.

---

Exportação/importação do banco de dados

Gerencie os backups do banco de dados em Dashboard → Settings → System & Storage.

Ação	Descrição
Exportar banco de dados	Baixa o banco de dados SQLite atual como um arquivo .sqlite
Exportar tudo (.tar.gz)	Baixa um arquivo de backup completo, incluindo: banco de dados, configurações, combos, conexões de provedores (sem credenciais) e metadados de chaves de API
Importar banco de dados	Envia um arquivo .sqlite para substituir o banco de dados atual. Um backup pré-importação é criado automaticamente, a menos que DISABLE_SQLITE_AUTO_BACKUP=true

# API: Exportar banco de dados
curl -o backup.sqlite http://localhost:20128/api/db-backups/export

# API: Exportar tudo (arquivo completo)
curl -o backup.tar.gz http://localhost:20128/api/db-backups/exportAll

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

Validação da importação: O arquivo importado é validado quanto à integridade (verificação por pragma do SQLite), às tabelas obrigatórias (provider_connections, provider_nodes, combos, api_keys) e ao tamanho (máximo de 100 MB).

Casos de uso:

• Migrar o OmniRoute entre máquinas
• Criar backups externos para recuperação de desastres
• Compartilhar configurações entre membros da equipe (exportar tudo → compartilhar arquivo)

---

Painel de configurações

A página de configurações está organizada em 7 abas para facilitar a navegação:

Aba	Conteúdo
Geral	Ferramentas de armazenamento do sistema, comportamento padrão, visibilidade do túnel de endpoint
Aparência	Controles de tema (claro/escuro/sistema), visibilidade da barra lateral, opções de exibição dos painéis de túneis Cloudflare/Tailscale/ngrok
IA	Orçamento de raciocínio (repasse / remoção automática / personalizado / adaptável — consulte THINKING_BUDGET.md), prompt global do sistema, estatísticas do cache de prompts
Segurança	Configurações de login/senha, controle de acesso por IP, autenticação de API para /models, bloqueio de provedores, proteção contra injeção de prompts
Roteamento	Estratégia global de roteamento (preencher primeiro / round-robin / P2C / aleatório / menos usado / custo otimizado), aliases de modelo com curingas, cadeias de fallback, padrões de combos
Resiliência	Fila de solicitações, período de espera de conexão, configuração do disjuntor de provedores e comportamento de espera pelo fim do período de espera
Avançado	Configuração global de proxy (HTTP/SOCKS5), substituições de proxy por provedor

A aba Geral não duplica mais as observações somente leitura sobre logs e cache. As configurações de retenção e otimização do banco de dados são persistidas por meio de /api/settings/database; a limpeza manual do cache usa DELETE /api/cache. Os limites de linhas das tabelas de logs de solicitações e de proxy são controlados por CALL_LOGS_TABLE_MAX_ROWS e PROXY_LOGS_TABLE_MAX_ROWS.

---

Gerenciamento de custos e orçamentos

Acesse por Painel → Custos.

Aba	Finalidade
Orçamento	Definir limites de gastos por chave de API, com orçamentos diários/semanais/mensais e acompanhamento em tempo real
Preços	Visualizar e editar entradas de preços de modelos — custo por mil tokens de entrada/saída por provedor

# API: Definir um orçamento
curl -X POST http://localhost:20128/api/usage/budget \
  -H "Content-Type: application/json" \
  -d '{"keyId": "key-123", "limit": 50.00, "period": "monthly"}'

# API: Obter o status atual do orçamento
curl http://localhost:20128/api/usage/budget

Acompanhamento de custos: Cada solicitação registra o uso de tokens e calcula o custo usando a tabela de preços. Veja os detalhamentos em Painel → Uso por provedor, modelo e chave de API.

---

Transcrição de áudio

O OmniRoute oferece suporte à transcrição de áudio por meio do endpoint compatível com a OpenAI:

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

# Exemplo com 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 da Deepgram e requer uma chave de API da Deepgram. Se apenas o OpenRouter estiver configurado, use openrouter/deepgram/nova-3.

Provedores de conversão de fala em texto (transcrição):

• openai/ (compatível com Whisper)
• groq/ (Groq Whisper Turbo)
• deepgram/ (família Nova)
• assemblyai/
• nvidia/ (Parakeet, Canary)
• huggingface/ (variantes do Whisper)
• qwen/

Provedores de conversão de texto em fala (POST /v1/audio/speech):

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

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

---

Estratégias de balanceamento de combos

Configure o balanceamento de cada combo em Painel → Combos → Criar/Editar → Estratégia.

Estratégia	Descrição
Round-Robin	Alterna entre os modelos sequencialmente
Prioridade	Sempre tenta o primeiro modelo; recorre aos demais somente em caso de erro
Aleatória	Escolhe um modelo aleatório da combinação para cada solicitação
Ponderada	Roteia proporcionalmente com base nos pesos atribuídos a cada modelo
Menos usado	Roteia para o modelo com menos solicitações recentes (usa métricas da combinação)
Otimizada por custo	Roteia para o modelo disponível mais barato (usa a tabela de preços)

Os padrões globais das combinações podem ser definidos em Dashboard → Configurações → Roteamento → Padrões das combinações. Por padrão, os tempos limite dos destinos da combinação herdam o tempo limite da solicitação atual. Use Tempo limite do destino (segundos) nos padrões das combinações ou em uma combinação individual somente quando um limite mais curto por destino precisar acionar a contingência mais rapidamente.

As otimizações de latência zero são opcionais. Deixe Otimizações de latência zero desativado para impedir que esses recursos de latência façam os destinos de contingência competirem entre si, ignorem destinos com base no histórico de TTFT ou compactem solicitações de contingência; habilitá-lo permite que a cobertura configurada, os saltos preditivos de TTFT e a compactação proativa de contingência troquem a fidelidade do roteamento/solicitação por menor latência de cauda.

Desative Buffer de tokens de raciocínio quando os provedores upstream exigirem limites estritos de max_tokens / maxOutputTokens. Quando habilitado, o roteamento de combinações adiciona margem para modelos de raciocínio somente aos modelos com um limite de saída conhecido e mantém inalterado o limite de tokens do cliente quando o valor seguro com buffer excederia esse limite. Se o limite do cliente já estiver acima de um limite conhecido, o OmniRoute o reduz para esse limite antes de enviar a solicitação upstream.

---

Painel de integridade

Acesse por meio de Dashboard → Integridade. Visão geral em tempo real da integridade do sistema com 6 cartões:

Cartão	O que ele mostra
Status do sistema	Tempo de atividade, versão, uso de memória e diretório de dados
Integridade do provedor	Estado global de execução do disjuntor dos provedores
Limites de taxa	Tempos de espera de conexões ativas por conta, com o tempo restante
Bloqueios ativos	Bloqueios ativos específicos por modelo e exclusões temporárias
Cache de assinaturas	Estatísticas do cache de desduplicação (chaves ativas, taxa de acertos)
Telemetria de latência	Agregação de latência p50/p95/p99 por provedor

Dica profissional: A página Integridade é atualizada automaticamente a cada 10 segundos. Use o cartão do disjuntor para identificar quais provedores estão enfrentando problemas.

---

🤖 Roteamento automático (configuração zero)

O OmniRoute inclui um roteador automático orientado por pontuação que seleciona o melhor modelo para cada solicitação entre todos os provedores conectados — sem precisar manter nenhuma combinação. Basta enviar a solicitação com um dos prefixos auto/*, e o OmniRoute montará uma combinação virtual dinamicamente, pontuando os candidatos com base em latência, custo, taxa de sucesso, adequação ao contexto, aptidão do modelo para a tarefa, falhas recentes, cota e estado do circuit breaker.

Prefixo	Otimiza para
auto	Padrão equilibrado (latência × custo × taxa de sucesso)
auto/coding	Tarefas de programação: prioriza Claude, GPT-5, GLM, Kimi, Qwen Coder e codificadores DeepSeek
auto/cheap	Menor custo por token, aceita maior latência
auto/fast	Menor latência, ignora o custo
auto/offline	Provedores somente locais (Ollama, vLLM, llama.cpp) — útil para ambientes isolados
auto/smart	Prioriza a qualidade do raciocínio (Opus, GPT-5 xhigh, R1, raciocínio do GLM 5.1)
auto/lkgp	“Último provedor válido conhecido” — fixa no último provedor 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 roteador automático está totalmente descrito em AUTO-COMBO.md — incluindo como ajustar os pesos de pontuação, adicionar provedores à lista de bloqueio e inspecionar as decisões de roteamento em Painel → Auto Combo.

---

🔌 Integração com MCP e A2A

O OmniRoute é tanto um servidor MCP (Model Context Protocol) quanto um servidor A2A (JSON-RPC 2.0 entre agentes). Qualquer IDE ou host de agentes compatível com MCP pode chamar as ferramentas do OmniRoute diretamente — nenhum wrapper adicional é necessário.

Transportes MCP

• SSE: http://localhost:20128/api/mcp/sse
• HTTP com streaming: http://localhost:20128/api/mcp/stream
• stdio: omniroute --mcp (para plugins de IDE que preferem stdio)

Conectar 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"]
    }
  }
}

Conectar o Cursor / Continue / MCP do VS Code

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

Escopos

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

---

🧠 Sistema de Skills

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

• Interface do Marketplace — Explore e instale skills em Dashboard → Skills
• Escopos por chave — Restrinja quais chaves de API podem invocar cada skill
• Skills personalizadas — Adicione um arquivo TypeScript em src/lib/a2a/skills/, registre-o e ele poderá ser invocado imediatamente via 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 fatos — 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

Gerencie as memórias em Dashboard → Memory (pesquisar, editar, exportar, limpar). A interface HTTP (/api/memory/*) permite que agentes enviem e consultem fatos de forma programática — consulte MEMORY.md.

---

🔔 Webhooks

Inscreva-se em eventos do OmniRoute para monitoramento e automação em tempo real.

• Crie um webhook em Dashboard → Webhooks com a 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 backoff exponencial e, em seguida, envio para a fila de mensagens mortas

Esquema completo em WEBHOOKS.md.

---

☁️ Agentes na Nuvem

O OmniRoute integra-se a agentes de programação na nuvem (OpenAI Codex Cloud, Devin, Jules, Antigravity), permitindo que você envie tarefas de longa duração pelo mesmo dashboard que gerencia seu roteamento local.

• Crie tarefas em Dashboard → Cloud Agents ou via POST /api/v1/agents/tasks
• Acompanhe o status, os logs e os artefatos de cada tarefa
• Use sua própria chave de API para cada provedor — as credenciais nunca saem da instância do OmniRoute

Referência completa: CLOUD_AGENT.md.

---

🛠️ Gerenciamento Programático

Você pode gerenciar todos os recursos do OmniRoute (provedores, combos, chaves e configurações) via HTTP usando uma chave Bearer com o escopo manage.

Gere a chave em Dashboard → API Keys → New Key → Scope: manage e, em seguida:

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

# Adicionar uma conexão de provedor
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 solicitação/resposta.

---

💻 CLI interna

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

omniroute setup                    # Assistente interativo (senha, provedores, combinações)
omniroute setup --non-interactive  # Adequado para CI
omniroute doctor                   # Diagnósticos de integridade (diretório de dados, banco de dados, provedores, portas)
omniroute providers available      # Lista os provedores compatíveis
omniroute providers list           # Lista as conexões configuradas
omniroute providers test <id>      # Testa uma conexão de provedor em tempo real
omniroute combos list              # Lista as combinações
omniroute combos switch <name>     # Define a combinação padrão
omniroute models                   # Lista os modelos disponíveis (--json, --search)
omniroute keys add | list | remove # Gerencia chaves de API pelo terminal
omniroute backup                   # Cria um snapshot da configuração e do banco de dados
omniroute restore [<timestamp>]    # Restaura a partir de um snapshot
omniroute health                   # Integridade detalhada (disjuntores, cache, memória)
omniroute quota                    # Uso da cota dos provedores
omniroute mcp status               # Status do servidor MCP
omniroute a2a status               # Status do servidor A2A
omniroute tunnel list|create|stop  # Túneis do Cloudflare/Tailscale/ngrok
omniroute reset-password           # Redefine a senha do administrador
omniroute --mcp                    # Inicia o servidor MCP via stdio
omniroute --port 3000              # Inicia o servidor em uma porta personalizada

Dica: combine omniroute doctor --json com sua ferramenta de monitoramento para emitir alertas sobre conexões de provedores que não estejam íntegras.

---

🖥️ Aplicativo para desktop (Electron)

O OmniRoute está disponível como um aplicativo nativo para Windows, macOS e Linux.

Instalação

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

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

# Modo de produção (usa a compilação independente):
npm start

Compilação dos 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 recursos

Recurso	Descrição
Prontidão do servidor	Consulta o servidor antes de exibir a janela (sem tela vazia)
Bandeja do sistema	Minimiza para a bandeja, altera a porta e encerra pelo menu
Gerenciamento de portas	Altera a porta do servidor pela bandeja (reinicia o servidor automaticamente)
Política de Segurança de Conteúdo	CSP restritiva por meio de cabeçalhos de sessão
Instância única	Somente uma instância do aplicativo pode ser executada por vez
Modo offline	O servidor Next.js incluído funciona sem internet

Variáveis de ambiente

Variável	Padrã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

---

Código-fonte do OmniRoute (a58000c7685f)