Como instalar o OmniRoute: início rápido e Claude Code

O OmniRoute é um gateway de IA compatível com a OpenAI. Ele coloca vários provedores de modelos upstream atrás de uma única API local, de modo que Claude Code, Codex CLI, extensões de IDE e seus próprios scripts só precisam ser configurados uma vez. Esta página é o caminho mais curto da instalação até a primeira requisição bem-sucedida; os guias completos por tema ficam em um site dedicado.

Guarde estes dois endereços

• Painel: http://localhost:20128
• Base URL compatível com a OpenAI: http://localhost:20128/v1

Os clientes são configurados com o segundo, não com o endereço do painel.

Pré-requisitos

• Node.js >=22.22.2 <23 ou >=24.0.0 <27; recomenda-se o Node.js 24 LTS. Fora dessa faixa, o painel pode mostrar uma página em branco ou erros de módulo nativo. Instale o Node.js antes, se necessário.
• A porta local 20128 está livre.
• Pelo menos uma conta ou chave de provedor upstream que você pretende rotear pelo OmniRoute.

Instalar e iniciar

Escolha um método:

# npm (recomendado)
npm install -g omniroute
omniroute

# Docker
docker run -d --name omniroute -p 20128:20128 diegosouzapw/omniroute:latest

Você também pode baixar um instalador Desktop para Windows, macOS ou Linux em OmniRoute GitHub Releases. :latest aponta para a versão estável publicada mais recente; fixe uma versão exata quando precisar de implantações reproduzíveis.

Depois de iniciar, abra http://localhost:20128. A senha de login é controlada pela variável de ambiente INITIAL_PASSWORD; na configuração de auto-hospedagem do upstream, ela é gerada na primeira inicialização e exibida nos logs, e com Docker você pode encontrá-la com docker logs omniroute | grep -i password. Defina uma senha forte própria antes de expor o serviço a uma rede.

Conectar um provedor e criar uma chave

1. No painel, vá em Providers → Add Provider e conecte o seu provedor.
2. Na página API Keys, crie uma nova chave e guarde-a, porque ela é exibida apenas uma vez. Essa chave serve para os clientes acessarem o OmniRoute; não é uma chave de provedor upstream.

A documentação do upstream lista alguns provedores gratuitos que não exigem chave. Disponibilidade e termos mudam, então confira os termos de cada serviço antes de depender de um deles.

Verificar o serviço

export OMNIROUTE_API_KEY="cole a chave criada na página API Keys"

curl http://localhost:20128/v1/models \
  -H "Authorization: Bearer ${OMNIROUTE_API_KEY}"

Uma lista de modelos significa que o endpoint compatível com a OpenAI e a autenticação funcionam. Em seguida, envie uma requisição de chat mínima para confirmar que um modelo realmente pode ser roteado:

curl http://localhost:20128/v1/chat/completions \
  -H "Authorization: Bearer ${OMNIROUTE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "messages": [{ "role": "user", "content": "Reply with ok." }]
  }'

auto deixa o OmniRoute escolher um provedor por velocidade, custo e disponibilidade. Você também pode usar um ID de modelo específico retornado por /v1/models.

Conectar suas ferramentas

Em qualquer ferramenta que fale o formato da OpenAI, informe:

Base URL: http://localhost:20128/v1
API Key:  a chave do OmniRoute que você criou
Model:    auto

O OmniRoute também traz lançadores de um comando, por exemplo omniroute launch-codex --model auto; a forma genérica omniroute run <target> oferece suporte a claude, codex, aider, goose, opencode, qwen e gemini. Se quiser usar um Agent CLI dentro do HagiCode, configure-o primeiro com Instalação dos AI Agent CLI.

Problemas comuns

• Painel em branco ou aviso de versão do Node.js sem suporte: mude para o Node.js 24 LTS, execute npm install -g omniroute novamente e depois omniroute.
• better-sqlite3 não encontrado no npm 11: o npm 11 bloqueia por padrão os scripts de instalação de dependências opcionais; recompile-o manualmente seguindo o guia de solução de problemas.
• slice is not valid mach-o file no macOS: execute npm rebuild better-sqlite3 dentro de $(npm root -g)/omniroute/app e inicie novamente.

Documentação completa

Abrir a documentação do OmniRoute em português

• Início rápido: OmniRoute em 3 minutos
• Configurar o OmniRoute para o Claude Code
• Implantar o OmniRoute com Docker
• Configurar o OmniRoute para o Codex CLI
• Solução de problemas