Versão: 2.1.0 Última Atualização: 2025-01-24
- Diagnóstico Rápido
- Problemas de Instalação
- Problemas de Rede e Conectividade
- Problemas de Permissão e Acesso
- Problemas Específicos de SO
- Problemas de Configuração de IDE
- Problemas de Ativação de Agentes
- Comandos de Diagnóstico
- Obtendo Ajuda
Execute este comando de diagnóstico primeiro para identificar problemas comuns:
npx aiox-core statusSe o comando de status falhar, trabalhe através das seções abaixo baseado na sua mensagem de erro.
Sintomas:
'npx' is not recognized as an internal or external command
Causa: Node.js ou npm não está instalado ou não está no PATH.
Solução:
# Verifique se o Node.js está instalado
node --version
# Se não estiver instalado:
# Windows: Baixe em https://nodejs.org/
# macOS: brew install node
# Linux: nvm install 18
# Verifique se o npm está disponível
npm --version
# Se o npm estiver faltando, reinstale o Node.jsSintomas:
⚠️ 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: Executando o instalador do diretório home, /tmp, ou cache npx.
Solução:
# Navegue para o diretório do seu projeto primeiro
cd /path/to/your/project
# Então execute o instalador
npx aiox-core installSintomas:
Installation failed: ENOENT: no such file or directory
Causa: O diretório de destino não existe ou tem permissões incorretas.
Solução:
# Crie o diretório primeiro
mkdir -p /path/to/your/project
# Navegue até ele
cd /path/to/your/project
# Execute o instalador
npx aiox-core installSintomas:
Error: Synkra AIOX requires Node.js 18.0.0 or higher
Current version: 14.17.0
Causa: A versão do Node.js está abaixo do requisito mínimo.
Solução:
# Verifique a versão atual
node --version
# Atualize usando nvm (recomendado)
nvm install 18
nvm use 18
# Ou baixe o LTS mais recente em nodejs.orgSintomas:
npm ERR! code E404
npm ERR! 404 Not Found - GET https://registry.npmjs.org/aiox-core
Causa: Pacote não encontrado no registro npm (problema de rede ou erro de digitação).
Solução:
# Limpe o cache npm
npm cache clean --force
# Verifique o registro
npm config get registry
# Deve ser: https://registry.npmjs.org/
# Se estiver usando registro customizado, resete para o padrão
npm config set registry https://registry.npmjs.org/
# Tente a instalação novamente
npx aiox-core installSintomas:
npm ERR! EACCES: permission denied, mkdir '/usr/local/lib/node_modules'
Causa: O diretório npm global tem permissões incorretas.
Solução:
# Opção 1: Corrigir permissões npm (Linux/macOS)
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH
# Adicione a linha de export ao ~/.bashrc ou ~/.zshrc
# Opção 2: Usar npx ao invés de instalação global (recomendado)
npx aiox-core install
# Opção 3: Usar nvm para gerenciar Node.js
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 18Sintomas:
npm ERR! code ETIMEDOUT
npm ERR! errno ETIMEDOUT
npm ERR! network request to https://registry.npmjs.org/aiox-core failed
Causa: Problema de conectividade de rede, firewall, ou proxy bloqueando npm.
Solução:
# Verifique se o registro npm está acessível
curl -I https://registry.npmjs.org/
# Se estiver atrás de um proxy, configure o npm
npm config set proxy http://proxy.company.com:8080
npm config set https-proxy http://proxy.company.com:8080
# Se estiver usando inspeção SSL corporativa, desabilite SSL estrito (use com cuidado)
npm config set strict-ssl false
# Tente novamente com logging verboso
npm install aiox-core --verboseSintomas:
npm ERR! code UNABLE_TO_GET_ISSUER_CERT_LOCALLY
npm ERR! unable to get local issuer certificate
Causa: Verificação de certificado SSL falhando (comum em ambientes corporativos).
Solução:
# Adicione o certificado CA da sua empresa
npm config set cafile /path/to/your/certificate.pem
# Ou desabilite SSL estrito (use apenas se você confia na sua rede)
npm config set strict-ssl false
# Verifique e tente novamente
npm config get strict-ssl
npx aiox-core installSintomas:
npm ERR! network socket hang up
npm ERR! network This is a problem related to network connectivity.
Causa: Conexão de internet instável ou problemas de DNS.
Solução:
# Tente usar DNS diferente
# Windows: Painel de Controle > Rede > DNS = 8.8.8.8, 8.8.4.4
# Linux: echo "nameserver 8.8.8.8" | sudo tee /etc/resolv.conf
# Limpe o cache DNS
# Windows: ipconfig /flushdns
# macOS: sudo dscacheutil -flushcache
# Linux: sudo systemd-resolve --flush-caches
# Tente novamente com timeout maior
npm config set fetch-timeout 60000
npx aiox-core installSintomas:
Error: EPERM: operation not permitted, unlink '/path/to/file'
Causa: Arquivo está bloqueado por outro processo ou permissões insuficientes.
Solução:
# Windows: Feche todas as instâncias de IDE, então:
taskkill /f /im node.exe
# macOS/Linux: Verifique processos bloqueando
lsof +D /path/to/project
# Mate qualquer processo segurando arquivos
kill -9 <PID>
# Tente a instalação novamente
npx aiox-core installSintomas:
Error: EROFS: read-only file system
Causa: Tentando instalar em uma montagem somente leitura ou diretório de sistema.
Solução:
# Verifique se o sistema de arquivos permite escrita
touch /path/to/project/test.txt
# Se isso falhar, o diretório é somente leitura
# Verifique opções de montagem
mount | grep /path/to/project
# Instale em um diretório com permissão de escrita
cd ~/projects/my-project
npx aiox-core installSintomas:
Error: ENOTEMPTY: directory not empty, rmdir '.aiox-core'
Causa: Instalação existente com arquivos modificados.
Solução:
# Faça backup da instalação existente
mv .aiox-core .aiox-core.backup
# Execute o instalador com flag force
npx aiox-core install --force-upgrade
# Se necessário, restaure arquivos customizados do backup
cp .aiox-core.backup/custom-files/* .aiox-core/Sintomas:
File cannot be loaded because running scripts is disabled on this system.
Solução:
# Verifique a política atual
Get-ExecutionPolicy
# Defina para RemoteSigned (recomendado)
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
# Ou use CMD ao invés de PowerShell
cmd
npx aiox-core installSintomas:
Error: ENAMETOOLONG: name too long
Solução:
# Habilite caminhos longos no Windows 10/11
# Execute como Administrador:
reg add "HKLM\SYSTEM\CurrentControlSet\Control\FileSystem" /v LongPathsEnabled /t REG_DWORD /d 1 /f
# Ou use um caminho de projeto mais curto
cd C:\dev\proj
npx aiox-core installSintomas:
bash: npm: command not found
Solução:
# Adicione Node.js ao path do Git Bash
# Em ~/.bashrc ou ~/.bash_profile:
export PATH="$PATH:/c/Program Files/nodejs"
# Ou use Windows Terminal/CMD/PowerShell ao invésSintomas:
xcode-select: error: command line tools are not installed
Solução:
# Instale Xcode Command Line Tools
xcode-select --install
# Siga o diálogo de instalação
# Então tente novamente
npx aiox-core installSintomas:
Error: Unsupported architecture: arm64
Solução:
# A maioria dos pacotes funciona nativamente, mas se problemas persistirem:
# Instale Rosetta 2 para compatibilidade x86
softwareupdate --install-rosetta
# Use versão x86 do Node.js (se necessário)
arch -x86_64 /bin/bash
nvm install 18
npx aiox-core installSintomas:
Error: Cannot find module '../build/Release/sharp-linux-x64.node'
Solução:
# Ubuntu/Debian
sudo apt-get update
sudo apt-get install -y build-essential libvips-dev
# Fedora/RHEL
sudo dnf install vips-devel
# Limpe o cache npm e reinstale
npm cache clean --force
npx aiox-core installSintomas:
Error: /lib/x86_64-linux-gnu/libc.so.6: version `GLIBC_2.28' not found
Solução:
# Verifique a versão do GLIBC
ldd --version
# Se a versão for muito antiga, use Node.js LTS para sua distro:
# Ubuntu 18.04: Use Node.js 16 (máximo suportado)
nvm install 16
nvm use 16
# Ou atualize sua distribuição LinuxSintomas: Comandos de agentes (/dev, @dev) não funcionam após instalação.
Solução:
-
Reinicie sua IDE completamente (não apenas recarregue)
-
Verifique se os arquivos foram criados:
# Claude Code ls .claude/commands/AIOX/agents/ # Cursor ls .cursor/rules/
-
Verifique se as configurações da IDE permitem comandos customizados
-
Re-execute a instalação para IDE específica:
npx aiox-core install --ide claude-code
Sintomas: IDE exibe o conteúdo do arquivo do agente ao invés de ativar.
Solução:
- Verifique se a versão da IDE é compatível
- Para Cursor: Certifique-se que os arquivos têm extensão
.mdc - Para Claude Code: Arquivos devem estar em
.claude/commands/ - Reinicie a IDE após a instalação
Sintomas:
Error: Agent 'dev' not found in .aiox-core/agents/
Solução:
# Verifique se os arquivos de agentes existem
ls .aiox-core/agents/
# Se estiverem faltando, reinstale o core
npx aiox-core install --full
# Verifique se core-config.yaml é válido
cat .aiox-core/core-config.yamlSintomas:
YAMLException: bad indentation of a mapping entry
Solução:
# Valide a sintaxe YAML
npx yaml-lint .aiox-core/agents/dev.md
# Correções comuns:
# - Use espaços, não tabs
# - Certifique-se de indentação consistente (2 espaços)
# - Verifique caracteres especiais em strings (use aspas)
# Reinstale para obter arquivos de agentes limpos
mv .aiox-core/agents/dev.md .aiox-core/agents/dev.md.backup
npx aiox-core install --full# Verifique status da instalação AIOX
npx aiox-core status
# Liste Squads disponíveis
npx aiox-core install
# Atualize instalação existente
npx aiox-core update
# Mostre logging verboso
npx aiox-core install --verbose# Versões do Node.js e npm
node --version && npm --version
# Configuração npm
npm config list
# Variáveis de ambiente
printenv | grep -i npm
printenv | grep -i node
# Espaço em disco (certifique-se de ter >500MB livres)
df -h .# Verifique estrutura .aiox-core
find .aiox-core -type f | wc -l
# Esperado: 200+ arquivos
# Verifique YAML corrompido
for f in .aiox-core/**/*.yaml; do npx yaml-lint "$f"; done
# Verifique permissões
ls -la .aiox-core/- Execute
npx aiox-core statuse anote a saída - Consulte este guia de solução de problemas
- Pesquise Issues existentes no GitHub
**Ambiente:**
- SO: [Windows 11 / macOS 14 / Ubuntu 22.04]
- Versão Node.js: [saída de `node --version`]
- Versão npm: [saída de `npm --version`]
- IDE: [Claude Code / Cursor / etc.]
**Passos para Reproduzir:**
1. [Primeiro passo]
2. [Segundo passo]
3. [Erro ocorre]
**Comportamento Esperado:**
[O que deveria acontecer]
**Comportamento Atual:**
[O que realmente acontece]
**Saída de Erro:**
[Cole a mensagem de erro completa aqui]
**Contexto Adicional:**
[Qualquer outra informação relevante]
- Issues no GitHub: aiox-core/issues
- Documentação: docs/installation/
- FAQ: faq.md