Versión: 2.1.0 Última Actualización: 2025-01-24
- Diagnóstico Rápido
- Problemas de Instalación
- Problemas de Red y Conectividad
- Problemas de Permisos y Acceso
- Problemas Específicos del Sistema Operativo
- Problemas de Configuración del IDE
- Problemas de Activación de Agentes
- Comandos de Diagnóstico
- Obtener Ayuda
Ejecute este comando de diagnóstico primero para identificar problemas comunes:
npx aiox-core statusSi el comando de estado falla, trabaje a través de las secciones a continuación según su mensaje de error.
Síntomas:
'npx' is not recognized as an internal or external command
Causa: Node.js o npm no está instalado o no está en PATH.
Solución:
# Verificar si Node.js está instalado
node --version
# Si no está instalado:
# Windows: Descargar desde https://nodejs.org/
# macOS: brew install node
# Linux: nvm install 18
# Verificar que npm esté disponible
npm --version
# Si falta npm, reinstalar Node.jsSíntomas:
⚠️ Inappropriate Installation Directory Detected
Current directory: /Users/username
Synkra AIOX should be installed in your project directory,
not in your home directory or temporary locations.
Causa: Ejecutar el instalador desde el directorio home, /tmp, o caché de npx.
Solución:
# Navegar primero a su directorio de proyecto
cd /path/to/your/project
# Luego ejecutar el instalador
npx aiox-core installSíntomas:
Installation failed: ENOENT: no such file or directory
Causa: El directorio de destino no existe o tiene permisos incorrectos.
Solución:
# Crear el directorio primero
mkdir -p /path/to/your/project
# Navegar a él
cd /path/to/your/project
# Ejecutar el instalador
npx aiox-core installSíntomas:
Error: Synkra AIOX requires Node.js 18.0.0 or higher
Current version: 14.17.0
Causa: La versión de Node.js está por debajo del requisito mínimo.
Solución:
# Verificar versión actual
node --version
# Actualizar usando nvm (recomendado)
nvm install 18
nvm use 18
# O descargar el último LTS desde nodejs.orgSíntomas:
npm ERR! code E404
npm ERR! 404 Not Found - GET https://registry.npmjs.org/aiox-core
Causa: Paquete no encontrado en el registro npm (problema de red o error tipográfico).
Solución:
# Limpiar caché de npm
npm cache clean --force
# Verificar registro
npm config get registry
# Debe ser: https://registry.npmjs.org/
# Si usa un registro personalizado, restablecer al predeterminado
npm config set registry https://registry.npmjs.org/
# Reintentar instalación
npx aiox-core installSíntomas:
npm ERR! EACCES: permission denied, mkdir '/usr/local/lib/node_modules'
Causa: El directorio npm global tiene permisos incorrectos.
Solución:
# Opción 1: Corregir permisos de npm (Linux/macOS)
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH
# Agregar la línea export a ~/.bashrc o ~/.zshrc
# Opción 2: Usar npx en lugar de instalación global (recomendado)
npx aiox-core install
# Opción 3: Usar nvm para administrar Node.js
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 18Síntomas:
npm ERR! code ETIMEDOUT
npm ERR! errno ETIMEDOUT
npm ERR! network request to https://registry.npmjs.org/aiox-core failed
Causa: Problema de conectividad de red, firewall o proxy bloqueando npm.
Solución:
# Verificar si el registro npm es accesible
curl -I https://registry.npmjs.org/
# Si está detrás de un proxy, configurar npm
npm config set proxy http://proxy.company.com:8080
npm config set https-proxy http://proxy.company.com:8080
# Si usa inspección SSL corporativa, deshabilitar SSL estricto (usar con precaución)
npm config set strict-ssl false
# Reintentar con registro detallado
npm install aiox-core --verboseSíntomas:
npm ERR! code UNABLE_TO_GET_ISSUER_CERT_LOCALLY
npm ERR! unable to get local issuer certificate
Causa: La verificación del certificado SSL falla (común en entornos corporativos).
Solución:
# Agregar el certificado CA de su empresa
npm config set cafile /path/to/your/certificate.pem
# O deshabilitar SSL estricto (usar solo si confía en su red)
npm config set strict-ssl false
# Verificar y reintentar
npm config get strict-ssl
npx aiox-core installSíntomas:
npm ERR! network socket hang up
npm ERR! network This is a problem related to network connectivity.
Causa: Conexión a internet inestable o problemas de DNS.
Solución:
# Intentar usar DNS diferente
# Windows: Panel de Control > Red > DNS = 8.8.8.8, 8.8.4.4
# Linux: echo "nameserver 8.8.8.8" | sudo tee /etc/resolv.conf
# Limpiar caché DNS
# Windows: ipconfig /flushdns
# macOS: sudo dscacheutil -flushcache
# Linux: sudo systemd-resolve --flush-caches
# Reintentar con un tiempo de espera más largo
npm config set fetch-timeout 60000
npx aiox-core installSíntomas:
Error: EPERM: operation not permitted, unlink '/path/to/file'
Causa: El archivo está bloqueado por otro proceso o permisos insuficientes.
Solución:
# Windows: Cerrar todas las instancias del IDE, luego:
taskkill /f /im node.exe
# macOS/Linux: Verificar procesos bloqueados
lsof +D /path/to/project
# Matar cualquier proceso que retiene archivos
kill -9 <PID>
# Intentar la instalación nuevamente
npx aiox-core installSíntomas:
Error: EROFS: read-only file system
Causa: Intentando instalar en un montaje de solo lectura o directorio del sistema.
Solución:
# Verificar que el sistema de archivos sea escribible
touch /path/to/project/test.txt
# Si esto falla, el directorio es de solo lectura
# Verificar opciones de montaje
mount | grep /path/to/project
# Instalar en un directorio escribible en su lugar
cd ~/projects/my-project
npx aiox-core installSíntomas:
Error: ENOTEMPTY: directory not empty, rmdir '.aiox-core'
Causa: Instalación existente con archivos modificados.
Solución:
# Hacer copia de seguridad de la instalación existente
mv .aiox-core .aiox-core.backup
# Ejecutar el instalador con bandera de fuerza
npx aiox-core install --force-upgrade
# Si es necesario, restaurar archivos personalizados desde la copia de seguridad
cp .aiox-core.backup/custom-files/* .aiox-core/Síntomas:
File cannot be loaded because running scripts is disabled on this system.
Solución:
# Verificar política actual
Get-ExecutionPolicy
# Establecer en RemoteSigned (recomendado)
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
# O usar CMD en lugar de PowerShell
cmd
npx aiox-core installSíntomas:
Error: ENAMETOOLONG: name too long
Solución:
# Habilitar rutas largas en Windows 10/11
# Ejecutar como Administrador:
reg add "HKLM\SYSTEM\CurrentControlSet\Control\FileSystem" /v LongPathsEnabled /t REG_DWORD /d 1 /f
# O usar una ruta de proyecto más corta
cd C:\dev\proj
npx aiox-core installSíntomas:
bash: npm: command not found
Solución:
# Agregar Node.js al path de Git Bash
# En ~/.bashrc o ~/.bash_profile:
export PATH="$PATH:/c/Program Files/nodejs"
# O usar Windows Terminal/CMD/PowerShell en su lugarSíntomas:
xcode-select: error: command line tools are not installed
Solución:
# Instalar Xcode Command Line Tools
xcode-select --install
# Seguir el diálogo de instalación
# Luego reintentar
npx aiox-core installSíntomas:
Error: Unsupported architecture: arm64
Solución:
# La mayoría de los paquetes funcionan nativamente, pero si los problemas persisten:
# Instalar Rosetta 2 para compatibilidad x86
softwareupdate --install-rosetta
# Usar versión x86 de Node.js (si es necesario)
arch -x86_64 /bin/bash
nvm install 18
npx aiox-core installSíntomas:
Error: Cannot find module '../build/Release/sharp-linux-x64.node'
Solución:
# Ubuntu/Debian
sudo apt-get update
sudo apt-get install -y build-essential libvips-dev
# Fedora/RHEL
sudo dnf install vips-devel
# Limpiar caché de npm y reinstalar
npm cache clean --force
npx aiox-core installSíntomas:
Error: /lib/x86_64-linux-gnu/libc.so.6: version `GLIBC_2.28' not found
Solución:
# Verificar versión de GLIBC
ldd --version
# Si la versión es muy antigua, use Node.js LTS para su distribución:
# Ubuntu 18.04: Use Node.js 16 (máximo soportado)
nvm install 16
nvm use 16
# O actualice su distribución de LinuxSíntomas: Los comandos de agentes (/dev, @dev) no funcionan después de la instalación.
Solución:
-
Reinicie su IDE completamente (no solo recargar)
-
Verifique que los archivos fueron creados:
# Claude Code ls .claude/commands/AIOX/agents/ # Cursor ls .cursor/rules/
-
Verifique que la configuración del IDE permita comandos personalizados
-
Vuelva a ejecutar la instalación para el IDE específico:
npx aiox-core install --ide claude-code
Síntomas: El IDE muestra el contenido del archivo del agente en lugar de activarlo.
Solución:
- Verifique que la versión del IDE sea compatible
- Para Cursor: Asegúrese de que los archivos tengan extensión
.mdc - Para Claude Code: Los archivos deben estar en
.claude/commands/ - Reinicie el IDE después de la instalación
Síntomas:
Error: Agent 'dev' not found in .aiox-core/agents/
Solución:
# Verificar que los archivos de agentes existan
ls .aiox-core/agents/
# Si faltan, reinstalar core
npx aiox-core install --full
# Verificar que core-config.yaml sea válido
cat .aiox-core/core-config.yamlSíntomas:
YAMLException: bad indentation of a mapping entry
Solución:
# Validar sintaxis YAML
npx yaml-lint .aiox-core/agents/dev.md
# Correcciones comunes:
# - Usar espacios, no tabulaciones
# - Asegurar indentación consistente (2 espacios)
# - Verificar caracteres especiales en cadenas (usar comillas)
# Reinstalar para obtener archivos de agentes limpios
mv .aiox-core/agents/dev.md .aiox-core/agents/dev.md.backup
npx aiox-core install --full# Verificar estado de instalación de AIOX
npx aiox-core status
# Listar Squads disponibles
npx aiox-core install
# Actualizar instalación existente
npx aiox-core update
# Mostrar registro detallado
npx aiox-core install --verbose# Versiones de Node.js y npm
node --version && npm --version
# Configuración de npm
npm config list
# Variables de entorno
printenv | grep -i npm
printenv | grep -i node
# Espacio en disco (asegurar >500MB libres)
df -h .# Verificar estructura de .aiox-core
find .aiox-core -type f | wc -l
# Esperado: 200+ archivos
# Verificar YAML corrupto
for f in .aiox-core/**/*.yaml; do npx yaml-lint "$f"; done
# Verificar permisos
ls -la .aiox-core/- Ejecute
npx aiox-core statusy anote la salida - Revise esta guía de solución de problemas
- Busque Issues de GitHub existentes
**Entorno:**
- SO: [Windows 11 / macOS 14 / Ubuntu 22.04]
- Versión de Node.js: [salida de `node --version`]
- Versión de npm: [salida de `npm --version`]
- IDE: [Claude Code / Cursor / etc.]
**Pasos para Reproducir:**
1. [Primer paso]
2. [Segundo paso]
3. [Ocurre el error]
**Comportamiento Esperado:**
[Qué debería pasar]
**Comportamiento Actual:**
[Qué realmente pasa]
**Salida del Error:**
[Pegar mensaje de error completo aquí]
**Contexto Adicional:**
[Cualquier otra información relevante]
- Issues de GitHub: aiox-core/issues
- Documentación: docs/installation/
- FAQ: faq.md