Muchas herramientas tienen documentación de instalación preciosa — hasta que la sigues y descubres tres prerrequisitos faltantes, una incompatibilidad de versión o un conflicto de PORT, y terminas buscando una solución en los issues de GitHub.

Esta guía intenta señalar esos problemas de antemano, para que puedas llegar a la primera conversación con OpenAlice en cinco minutos de verdad.

Prerrequisitos

OpenAlice no tiene muchos requisitos de entorno, pero estos tres deben estar correctos:

Herramienta	Versión	Notas
Node.js	22+	Las versiones inferiores no funcionarán — usa nvm para gestionar
pnpm	10+	Instala via `npm install -g pnpm` o Corepack
Claude Code CLI	Última	Proveedor IA predeterminado; usa tu suscripción Pro/Max

Sobre Claude Code: Este es el proveedor IA predeterminado porque OpenAlice admite OAuth a través del Agent SDK de Claude Code — lo que significa que no necesitas una clave API de Anthropic separada; una suscripción Claude Pro/Max es suficiente.

Si quieres usar tu propia clave API (modo Vercel AI SDK, compatible con OpenAI, Google, Anthropic), Claude Code se vuelve opcional.

Verificación de versiones:

node --version   # Debe mostrar v22.x.x o superior
pnpm --version   # Debe mostrar 10.x.x o superior
claude --version # Versión de Claude Code CLI

Si los tres están bien, estás listo para continuar.

Pasos de Instalación

Paso 1: Clonar e Instalar

git clone https://github.com/TraderAlice/OpenAlice.git
cd OpenAlice
pnpm install && pnpm build

pnpm install descarga todas las dependencias; pnpm build construye tanto el backend como la UI. La primera ejecución puede tomar un poco más de tiempo — eso es normal.

Paso 2: Iniciar el Modo de Desarrollo

pnpm dev

Esto inicia el backend (puerto 3002) y sirve la UI pre-construida.

Abre tu navegador y ve a http://localhost:3002 — deberías ver la interfaz de chat de la Web UI de OpenAlice.

Paso 3: Tu Primera Conversación

Escribe esto directamente en el cuadro de chat:

What's the current price of AAPL?

La primera respuesta puede ser un poco lenta mientras se inicializa la conexión. Si recibes de vuelta datos precisos del precio de la acción, felicitaciones — tu OpenAlice está en vivo.

Dos Modos de Desarrollo

OpenAlice proporciona dos comandos para diferentes escenarios:

Comando	Puerto	Caso de Uso
`pnpm dev`	3002	Modo watch del backend (tsx), sirve la UI pre-construida
`pnpm dev:ui`	5173	Servidor de desarrollo Vite frontend con hot reload, proxy de API a 3002

Para uso general: pnpm dev es suficiente.
Si estás modificando la UI: Abre dos terminales — uno ejecutando pnpm dev, el otro ejecutando pnpm dev:ui — luego accede en http://localhost:5173. Los cambios en la UI aparecerán en tiempo real.

Problemas Comunes de Instalación

P: pnpm build falla, la versión de Node es correcta pero sigue dando errores?
Verifica si hay un problema de caché de pnpm: pnpm store prune && pnpm install --force.

P: El servidor inició pero las conversaciones no obtienen respuesta?
Verifica que Claude Code CLI esté autenticado: claude auth status. Si muestra que no está autenticado, ejecuta claude auth login y completa el flujo OAuth.

P: El puerto 3002 ya está en uso?
Ejecuta lsof -i :3002 para encontrar el proceso que usa el puerto, mátalo y luego ejecuta pnpm dev nuevamente.

P: ¿Quieres cambiar a tu propia clave API de OpenAI?
OpenAlice admite múltiples perfiles de proveedores IA que puedes cambiar en la UI de configuración. La configuración está en la página Config de la Web UI — selecciona Vercel AI SDK e ingresa tu clave API.

Un Rápido Recorrido por la Web UI

Una vez que está en marcha, verás algunas áreas:

Interfaz de Chat — donde hablas con Alice; admite sub-canales, para que puedas abrir diferentes canales para diferentes mercados o tareas
Panel de Portafolio — muestra las posiciones de tu cuenta UTA conectada, incluyendo visualización de curva de equity
Gestión de Configuración — donde configuras tu proveedor IA, cuentas de corretaje y reglas del Guard Pipeline

El Panel de Portafolio puede estar vacío la primera vez que lo abres — eso es porque todavía no has conectado ninguna cuenta de corretaje. Está bien. Empieza familiarizándote con las funciones de investigación y análisis, luego configura cuentas reales cuando estés listo.

Ejercicios Sugeridos para Empezar

Una vez en marcha, prueba estos prompts para hacerte una idea de lo que puede hacer OpenAlice:

# Consultas de precios
What's the 52-week high and low for TSLA?

# Análisis técnico
Show me the RSI and MACD for BTC/USD over the last 30 days

# Búsqueda de noticias
What are the latest news about Fed interest rate decisions?

# Fundamentales
Give me a summary of NVDA's latest earnings report

No necesitas probarlos todos — elige uno o dos mercados que te interesen y ejecuta algunas consultas. El objetivo es desarrollar una sensación de la velocidad de respuesta de OpenAlice, la profundidad de sus datos y qué tan bien entiende tus preguntas.

Próximos Pasos de Configuración

Una vez en marcha, si quieres profundizar, los próximos pasos típicamente son:

Configurar el Guard Pipeline — define los límites de trading dentro de los cuales estás dispuesto a dejar operar a la IA en Config
Conectar cuentas de corretaje — crea una Cuenta de Trading Unificada e integra tus cuentas reales
Configurar Heartbeat — haz que OpenAlice empiece a monitorear proactivamente las condiciones de mercado que te importan

No tienes que hacer todo esto de una vez. Haz que el flujo de trabajo de investigación funcione sin problemas primero, luego abre gradualmente los permisos de ejecución — eso es el enfoque más medido.

Una Línea

Instalar OpenAlice no es la parte difícil — la parte difícil es saber cómo hacerlo genuinamente útil una vez que está en marcha. Levantar el entorno es solo el punto de partida. El trabajo real comienza después de eso.

Volver al Resumen de la Serie

Esta es la segunda parada en la serie OpenAlice, que cubre la instalación y configuración del entorno. El siguiente artículo es Trading-as-Git: Gestiona Tus Operaciones Como Código con Control de Versiones, que explica la filosofía central de diseño de trading de OpenAlice. El mapa completo de lectura está en Curso para Principiantes de OpenAlice.