Instalar OmniRoute: inicio rápido y Claude Code

OmniRoute es una pasarela de IA compatible con OpenAI. Reúne muchos proveedores de modelos detrás de una única API local, de modo que Claude Code, Codex CLI, las extensiones de IDE y tus propios scripts solo necesitan configurarse una vez. Esta página es el camino más corto desde la instalación hasta una primera petición correcta; las guías temáticas completas están en un sitio dedicado.

Recuerda estas dos direcciones

• Panel: http://localhost:20128
• Base URL compatible con OpenAI: http://localhost:20128/v1

Los clientes se configuran con la segunda, no con la dirección del panel.

Requisitos previos

• Node.js >=22.22.2 <23 o >=24.0.0 <27; se recomienda Node.js 24 LTS. Fuera de ese rango el panel puede mostrar una página en blanco o errores de módulos nativos. Si hace falta, instala Node.js primero.
• El puerto local 20128 está libre.
• Al menos una cuenta o clave de un proveedor de origen que quieras enrutar a través de OmniRoute.

Instalar e iniciar

Elige un método:

# npm (recomendado)
npm install -g omniroute
omniroute

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

También puedes descargar un instalador de Desktop para Windows, macOS o Linux desde OmniRoute GitHub Releases. :latest apunta a la última versión estable publicada; fija una versión exacta cuando necesites despliegues reproducibles.

Tras el arranque, abre http://localhost:20128. La contraseña de acceso se controla con la variable de entorno INITIAL_PASSWORD; en la configuración de autoalojamiento del proyecto original se genera en el primer arranque y se imprime en los registros, y con Docker puedes encontrarla con docker logs omniroute | grep -i password. Establece una contraseña propia y robusta antes de exponer el servicio a una red.

Conectar un proveedor y crear una clave

1. En el panel, ve a Providers → Add Provider y conecta tu proveedor.
2. En la página API Keys, crea una clave nueva y guárdala, porque solo se muestra una vez. Esta clave sirve para que los clientes accedan a OmniRoute; no es una clave de un proveedor de origen.

La documentación original enumera algunos proveedores gratuitos que no necesitan clave. La disponibilidad y las condiciones cambian, así que revisa las condiciones de cada servicio antes de depender de él.

Verificar el servicio

export OMNIROUTE_API_KEY="paste the key you created on the API Keys page"

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

Si recibes una lista de modelos, el punto de acceso compatible con OpenAI y la autenticación funcionan. Después envía una petición de chat mínima para confirmar que un modelo se puede enrutar de verdad:

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 deja que OmniRoute elija el proveedor según velocidad, coste y disponibilidad. También puedes usar un ID de modelo concreto devuelto por /v1/models.

Conectar tus herramientas

En cualquier herramienta que use el formato OpenAI, introduce:

Base URL: http://localhost:20128/v1
API Key:  the OmniRoute key you created
Model:    auto

OmniRoute también incluye lanzadores de un solo comando, por ejemplo omniroute launch-codex --model auto; la forma general omniroute run <target> admite claude, codex, aider, goose, opencode, qwen y gemini. Si quieres usar un Agent CLI dentro de HagiCode, configúralo primero con Instalación de AI Agent CLI.

Problemas comunes

• Panel en blanco o aviso de versión de Node.js no compatible: cambia a Node.js 24 LTS, vuelve a ejecutar npm install -g omniroute y luego omniroute.
• better-sqlite3 no se encuentra en npm 11: npm 11 bloquea por defecto los scripts de instalación de las dependencias opcionales; recompílalo a mano siguiendo la guía de solución de problemas.
• slice is not valid mach-o file en macOS: ejecuta npm rebuild better-sqlite3 dentro de $(npm root -g)/omniroute/app y vuelve a iniciar.

Documentación completa

Abrir la documentación de OmniRoute en español

• Inicio rápido: pon OmniRoute en marcha en 3 minutos
• Configurar OmniRoute para Claude Code
• Desplegar OmniRoute con Docker
• Configurar OmniRoute para Codex CLI
• Solución de problemas