Guia de Instalação e Solução de Problemas do AIOS-Core

🌐 EN | PT | ES

Início Rápido

npx aios-core@latest

Este comando baixa e executa a versão mais recente do instalador do AIOS-Core.

Requisitos do Sistema

Links para Download

• Node.js: https://nodejs.org/  (Baixe a versão LTS - inclui npm e npx)
• Git: https://git-scm.com/  (Opcional, mas recomendado)

Métodos de Instalação

Método 1: npx (Recomendado)

# Install in current directory
npx aios-core@latest
 
# Install with specific version
npx aios-core@2.2.0
 
# Show version
npx aios-core@latest --version
 
# Show help
npx aios-core@latest --help

Método 2: Do GitHub

npx github:SynkraAI/aios-core install

Método 3: Instalação Global

npm install -g aios-core
aios-core

Ferramenta de Diagnóstico

Se você está tendo problemas de instalação, execute nossa ferramenta de diagnóstico:

Windows (CMD)

curl -o diagnose.cmd https://raw.githubusercontent.com/SynkraAI/aios-core/main/tools/quick-diagnose.cmd && diagnose.cmd

Windows (PowerShell)

irm https://raw.githubusercontent.com/SynkraAI/aios-core/main/tools/quick-diagnose.ps1 | iex

macOS/Linux

curl -fsSL https://raw.githubusercontent.com/SynkraAI/aios-core/main/tools/diagnose-installation.js | node

Problemas Comuns e Soluções

Problema 1: “Node.js version too old”

Erro:

error engine Unsupported engine
error notsup Required: {"node":">=18.0.0"}

Solução:

1. Baixe o Node.js LTS de https://nodejs.org/ 
2. Instale e reinicie seu terminal
3. Verifique: node --version (deve mostrar v18+ ou v20+)

Problema 2: “npm version too old”

Erro:

npm ERR! Required: {"npm":">=9.0.0"}

Solução:

# Update npm globally
npm install -g npm@latest
 
# Verify
npm --version

Problema 3: “npx not found” ou “npx command not recognized”

Causa: Pasta bin do npm não está no PATH do sistema

Solução (Windows):

1. Encontre o prefixo do npm: npm config get prefix
2. Adicione ao PATH:
   • Pressione Win+X → Sistema → Configurações avançadas do sistema → Variáveis de Ambiente
   • Edite “Path” nas variáveis do usuário
   • Adicione: C:\Users\SEU_USUARIO\AppData\Roaming\npm
3. Reinicie o terminal

Solução (macOS/Linux):

# Add to ~/.bashrc or ~/.zshrc
export PATH="$PATH:$(npm config get prefix)/bin"
 
# Reload
source ~/.bashrc

Problema 4: “EACCES: permission denied”

Solução (Windows): Execute o terminal como Administrador

Solução (macOS/Linux):

# Fix npm permissions (recommended)
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH
 
# Or use nvm (best practice)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

Problema 5: “ETIMEDOUT” ou “ECONNREFUSED”

Causa: Rede/firewall bloqueando registro do npm

Soluções:

1. Verifique o registro do npm:

   npm config get registry
   # Should be: https://registry.npmjs.org/

2. Redefina o registro:

   npm config set registry https://registry.npmjs.org/

3. Teste a conectividade:

   npm ping

4. Atrás de proxy corporativo:

   npm config set proxy http://proxy.company.com:8080
   npm config set https-proxy http://proxy.company.com:8080

5. Use mirror (China):

   npm config set registry https://registry.npmmirror.com

Problema 6: “PowerShell execution policy” (Windows)

Erro:

File cannot be loaded because running scripts is disabled on this system

Solução:

# Run as Administrator
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Problema 7: “Cannot find module” ou “Missing dependencies”

Solução:

# Clear npm cache
npm cache clean --force
 
# Remove node_modules if exists
rm -rf node_modules
 
# Try again
npx aios-core@latest

Problema 8: “SSL/Certificate errors”

Solução:

# Temporarily disable strict SSL (not recommended for production)
npm config set strict-ssl false
 
# Better: Update certificates
npm config set cafile /path/to/certificate.pem

Problema 9: Pacote mostra versão antiga

Causa: Cache do npm servindo versão antiga

Solução:

# Clear npx cache
npx clear-npx-cache
 
# Or force fresh download
npx --ignore-existing aios-core@latest
 
# Or use specific version
npx aios-core@2.2.0

Checklist de Verificação do Ambiente

Execute estes comandos para verificar seu ambiente:

# 1. Check Node.js (need v18+)
node --version
 
# 2. Check npm (need v9+)
npm --version
 
# 3. Check npx
npx --version
 
# 4. Check npm registry access
npm view aios-core version
 
# 5. Test installation
npx aios-core@latest --version

Saída esperada:

v22.x.x (or v18+/v20+)
11.x.x (or v9+)
11.x.x (same as npm)
2.2.0
2.2.0

Obtendo Ajuda

Se você ainda está tendo problemas:

1. GitHub Issues: https://github.com/SynkraAI/aios-core/issues 
2. Execute diagnósticos: npx aios-core@latest doctor
3. Verifique informações do sistema: npx aios-core@latest info

Ao reportar problemas, por favor inclua:

• Sistema operacional e versão
• Versão do Node.js (node --version)
• Versão do npm (npm --version)
• Mensagem de erro completa
• Saída da ferramenta de diagnóstico

Referência Rápida

Última atualização: Dezembro 2025 | AIOS-Core v2.2.0