Skip to Content
DocumentaçãoTroubleshooting

Guia de Solução de Problemas do Synkra AIOS

🌐 EN | PT | ES

Este guia abrangente ajuda você a diagnosticar e resolver problemas comuns com o Synkra AIOS.

Índice

  1. Diagnóstico Rápido
  2. Problemas de Instalação
  3. Problemas com o Meta-Agent
  4. Problemas com a Camada de Memória
  5. Problemas de Performance
  6. Problemas de API e Integração
  7. Erros de Segurança e Permissão
  8. Problemas Específicos de Plataforma
  9. Solução de Problemas Avançada
  10. Obtendo Ajuda

Diagnóstico Rápido

Executar o Doctor do Sistema

Sempre comece com o diagnóstico integrado:

# Diagnóstico básico
npx @synkra/aios-core doctor
 
# Corrigir automaticamente problemas comuns
npx @synkra/aios-core doctor --fix
 
# Saída detalhada
npx @synkra/aios-core doctor --verbose
 
# Verificar componente específico
npx @synkra/aios-core doctor --component memory-layer

Correções Rápidas Comuns

# Limpar todos os caches
*memory clear-cache
 
# Reconstruir índice de memória
*memory rebuild
 
# Resetar configuração
*config --reset
 
# Atualizar para última versão
npx @synkra/aios-core update

Problemas de Instalação

Problema: Comando NPX não encontrado

Sintomas:

bash: npx: command not found

Solução:

# Verificar versão do npm
npm --version
 
# Se npm < 5.2, instalar npx globalmente
npm install -g npx
 
# Ou usar npm diretamente
npm exec @synkra/aios-core init my-project

Problema: Instalação falha com erros de permissão

Sintomas:

Error: EACCES: permission denied

Soluções:

Opção 1: Corrigir permissões do npm (Recomendado)

# Criar diretório npm
mkdir ~/.npm-global
 
# Configurar npm
npm config set prefix '~/.npm-global'
 
# Adicionar ao PATH (adicionar ao ~/.bashrc ou ~/.zshrc)
export PATH=~/.npm-global/bin:$PATH
 
# Recarregar shell
source ~/.bashrc

Opção 2: Usar diretório diferente

# Instalar no diretório do usuário
cd ~
npx @synkra/aios-core init my-project

Problema: Erro de versão do Node.js

Sintomas:

Error: Node.js version 18.0.0 or higher required

Solução:

# Verificar versão atual
node --version
 
# Atualizar Node.js
# macOS (usando Homebrew)
brew upgrade node
 
# Windows (usando Chocolatey)
choco upgrade nodejs
 
# Linux (usando NodeSource)
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs
 
# Ou usar nvm (Node Version Manager)
nvm install 18
nvm use 18

Problema: Instalação trava ou expira

Sintomas:

  • Instalação travada em “Installing dependencies…”
  • Erros de timeout de rede

Soluções:

# Usar registro diferente
npm config set registry https://registry.npmjs.org/
 
# Limpar cache do npm
npm cache clean --force
 
# Aumentar timeout
npm config set fetch-timeout 60000
 
# Pular instalação de dependências
npx @synkra/aios-core init my-project --skip-install
 
# Então instalar manualmente
cd my-project
npm install --verbose

Problema: Erro de espaço em disco

Sintomas:

Error: ENOSPC: no space left on device

Solução:

# Verificar espaço disponível
df -h
 
# Limpar cache do npm
npm cache clean --force
 
# Remover node_modules antigos
find . -name "node_modules" -type d -prune -exec rm -rf '{}' +
 
# Limpar arquivos temporários
# macOS/Linux
rm -rf /tmp/npm-*
 
# Windows
rmdir /s %TEMP%\npm-*

Problemas com o Meta-Agent

Problema: Meta-agent não inicia

Sintomas:

Error: Failed to initialize meta-agent

Soluções:

  1. Verificar configuração:
# Verificar se config existe
ls -la .aios/config.json
 
# Validar configuração
npx @synkra/aios-core doctor --component config
 
# Resetar se corrompido
rm .aios/config.json
npx @synkra/aios-core doctor --fix
  1. Verificar dependências:
# Reinstalar dependências principais
npm install
 
# Verificar arquivos de agentes
ls -la agents/
  1. Verificar ambiente:
# Verificar variáveis de ambiente
cat .env
 
# Garantir que chaves de API estão definidas
echo "OPENAI_API_KEY=your-key" >> .env

Problema: Comandos não reconhecidos

Sintomas:

Unknown command: *create-agent

Soluções:

  1. Verificar ativação do agente:
# Listar agentes ativos
*list-agents --active
 
# Ativar meta-agent
*activate meta-agent
 
# Verificar disponibilidade de comandos
*help
  1. Verificar sintaxe do comando:
# Sintaxe correta usa asterisco
*create-agent my-agent  # ✓ Correto
create-agent my-agent   # ✗ Errado
  1. Recarregar agentes:
# Recarregar todos os agentes
*reload-agents
 
# Ou reiniciar meta-agent
exit
npx @synkra/aios-core

Problema: Criação de agente falha

Sintomas:

Error: Failed to create agent

Soluções:

  1. Verificar permissões:
# Verificar permissões de escrita
ls -la agents/
 
# Corrigir permissões
chmod 755 agents/
  1. Validar nome do agente:
# Nomes válidos: minúsculas, hífens
*create-agent my-agent      # ✓ Bom
*create-agent MyAgent       # ✗ Ruim (maiúsculas)
*create-agent my_agent      # ✗ Ruim (underscore)
*create-agent my-agent-2    # ✓ Bom
  1. Verificar duplicatas:
# Listar agentes existentes
*list-agents
 
# Remover duplicata se existir
rm agents/duplicate-agent.yaml

Problemas com a Camada de Memória

Problema: Busca de memória não retorna resultados

Sintomas:

  • Busca semântica não encontra nada
  • Reconhecimento de padrões falha

Soluções:

  1. Reconstruir índice de memória:
# Limpar e reconstruir
*memory clear-cache
*memory rebuild --verbose
 
# Aguardar indexação
# Verificar progresso
*memory status
  1. Verificar configuração de memória:
# Verificar config
cat .aios/memory-config.json
 
# Resetar para padrões
*memory reset-config
  1. Verificar integridade do índice:
# Executar diagnóstico de memória
*memory diagnose
 
# Reparar se necessário
*memory repair

Problema: Camada de memória usando muita RAM

Sintomas:

  • Alto uso de memória
  • Lentidão do sistema

Soluções:

  1. Ajustar configurações de memória:
// Editar .aios/memory-config.json
{
  "maxDocuments": 5000,      // Reduzir de 10000
  "chunkSize": 256,          // Reduzir de 512
  "cacheSize": 100,          // Reduzir de 1000
  "enableCompression": true  // Habilitar compressão
}
  1. Limpar dados antigos:
# Remover entradas antigas
*memory prune --older-than "30 days"
 
# Otimizar armazenamento
*memory optimize
  1. Usar limites de memória:
# Definir limite de memória
export NODE_OPTIONS="--max-old-space-size=1024"
 
# Executar com memória limitada
npx @synkra/aios-core

Problema: Erros do LlamaIndex

Sintomas:

Error: LlamaIndex initialization failed

Soluções:

  1. Verificar chaves de API:
# Verificar chave OpenAI para embeddings
echo $OPENAI_API_KEY
 
# Testar acesso à API
curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY"
  1. Usar embeddings locais:
// .aios/memory-config.json
{
  "embedModel": "local",
  "localModelPath": "./models/embeddings"
}
  1. Reinstalar LlamaIndex:
npm uninstall llamaindex
npm install llamaindex@latest

Problemas de Performance

Problema: Execução lenta de comandos

Sintomas:

  • Comandos levam > 5 segundos
  • Interface parece lenta

Soluções:

  1. Perfilar performance:
# Habilitar profiling
*debug enable --profile
 
# Executar comando lento
*analyze-framework
 
# Ver perfil
*debug show-profile
  1. Otimizar configuração:
// .aios/config.json
{
  "performance": {
    "enableCache": true,
    "parallelOperations": 4,
    "lazyLoading": true,
    "indexUpdateFrequency": "hourly"
  }
}
  1. Limpar recursos:
# Limpar caches
*cache clear --all
 
# Remover agentes não utilizados
*cleanup-agents
 
# Otimizar banco de dados
*optimize-db

Problema: Alto uso de CPU

Sintomas:

  • Barulho de ventilador
  • Lentidão do sistema
  • Alta CPU no gerenciador de tarefas

Soluções:

  1. Limitar operações concorrentes:
# Definir limites de operação
*config --set performance.maxConcurrent 2
*config --set performance.cpuThreshold 80
  1. Desabilitar recursos em tempo real:
# Desabilitar indexação em tempo real
*config --set memory.realTimeIndex false
 
# Usar processamento em lote
*config --set performance.batchMode true
  1. Verificar processos descontrolados:
# Listar todos os processos
*debug processes
 
# Matar processo travado
*debug kill-process <pid>

Problemas de API e Integração

Problema: Chave de API não funciona

Sintomas:

Error: Invalid API key
Error: 401 Unauthorized

Soluções:

  1. Verificar formato da chave de API:
# OpenAI
echo $OPENAI_API_KEY
# Deve começar com "sk-"
 
# Anthropic
echo $ANTHROPIC_API_KEY
# Deve começar com "sk-ant-"
  1. Testar API diretamente:
# Testar OpenAI
curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY"
 
# Testar Anthropic
curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01"
  1. Verificar limites de taxa:
# Ver uso atual
*api-status
 
# Mudar para provedor diferente
*config --set ai.provider anthropic

Problema: Erros de conexão de rede

Sintomas:

Error: ECONNREFUSED
Error: getaddrinfo ENOTFOUND

Soluções:

  1. Verificar configurações de proxy:
# Proxy corporativo
export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=http://proxy.company.com:8080
 
# Testar conexão
curl -I https://api.openai.com
  1. Usar modo offline:
# Habilitar modo offline
*config --set offline true
 
# Usar modelos locais
*config --set ai.provider local
  1. Configurar timeouts:
# Aumentar timeouts
*config --set network.timeout 30000
*config --set network.retries 3

Erros de Segurança e Permissão

Problema: Erros de permissão negada

Sintomas:

Error: EACCES: permission denied
Error: Cannot write to file

Soluções:

  1. Corrigir permissões de arquivo:
# Corrigir permissões do projeto
chmod -R 755 .
chmod 600 .env
 
# Corrigir diretórios específicos
chmod 755 agents/ tasks/ workflows/
  1. Verificar propriedade de arquivo:
# Ver propriedade
ls -la
 
# Corrigir propriedade (Linux/macOS)
sudo chown -R $(whoami) .
  1. Executar com usuário correto:
# Não usar sudo para npm
npm install  # ✓ Bom
sudo npm install  # ✗ Ruim

Problema: Dados sensíveis expostos

Sintomas:

  • Chaves de API visíveis em logs
  • Credenciais em mensagens de erro

Soluções:

  1. Proteger variáveis de ambiente:
# Verificar .gitignore
cat .gitignore | grep .env
 
# Adicionar se ausente
echo ".env" >> .gitignore
echo ".aios/logs/" >> .gitignore
  1. Habilitar modo seguro:
# Habilitar recursos de segurança
*config --set security.maskSensitive true
*config --set security.secureLogging true
  1. Rotacionar chaves comprometidas:
# Gerar novas chaves dos provedores
# Atualizar arquivo .env
# Limpar logs
rm -rf .aios/logs/*

Problemas Específicos de Plataforma

Problemas do Windows

Problema: Erros de caminho muito longo

Error: ENAMETOOLONG

Solução:

# Habilitar caminhos longos (Executar como Administrador)
New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" `
  -Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force
 
# Ou usar caminhos mais curtos
cd C:\
npx @synkra/aios-core init myapp

Problema: Scripts desabilitados

Error: Scripts is disabled on this system

Solução:

# Executar como Administrador
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Problemas do macOS

Problema: Command Line Tools ausentes

Error: xcrun: error: invalid active developer path

Solução:

# Instalar Xcode Command Line Tools
xcode-select --install

Problema: Gatekeeper bloqueia execução

Error: "@synkra/aios-core" cannot be opened

Solução:

# Permitir execução
sudo spctl --master-disable
 
# Ou remover quarentena
xattr -d com.apple.quarantine /usr/local/bin/@synkra/aios-core

Problemas do Linux

Problema: Dependências ausentes

Error: libssl.so.1.1: cannot open shared object file

Solução:

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install libssl-dev
 
# RHEL/CentOS
sudo yum install openssl-devel
 
# Arch
sudo pacman -S openssl

Solução de Problemas Avançada

Habilitar Modo Debug

# Saída de debug completa
export DEBUG=aios:*
npx @synkra/aios-core
 
# Componentes específicos
export DEBUG=aios:memory,aios:agent

Analisar Logs

# Ver logs recentes
tail -f .aios/logs/aios.log
 
# Buscar por erros
grep -i error .aios/logs/*.log
 
# Ver logs estruturados
*logs --format json --level error

Criar Relatório de Diagnóstico

# Gerar diagnóstico completo
npx @synkra/aios-core doctor --report diagnostic.json
 
# Incluir informações do sistema
npx @synkra/aios-core info --detailed >> diagnostic.json
 
# Criar pacote de suporte
tar -czf aios-support.tar.gz .aios/logs diagnostic.json

Perfilamento de Performance

// Habilitar profiling na config
{
  "debug": {
    "profiling": true,
    "profileOutput": ".aios/profiles/"
  }
}
# Analisar perfil
*debug analyze-profile .aios/profiles/latest.cpuprofile

Análise de Dump de Memória

# Criar snapshot de heap
*debug heap-snapshot
 
# Analisar uso de memória
*debug memory-report
 
# Encontrar vazamentos de memória
*debug find-leaks

Obtendo Ajuda

Antes de Pedir Ajuda

  1. Execute diagnósticos:

    npx @synkra/aios-core doctor --verbose > diagnostic.log

  2. Colete informações:

    • Versão do Node.js: node --version
    • Versão do NPM: npm --version
    • SO e versão: uname -a ou ver
    • Versão do AIOS: npx @synkra/aios-core version

  3. Verifique issues existentes:

Suporte da Comunidade

  • Discord: Entre no nosso servidor 

    • #help - Ajuda geral
    • #bugs - Relatos de bugs
    • #meta-agent - Específico do meta-agent

  • GitHub Discussions: Perguntas técnicas e solicitações de funcionalidades

  • Stack Overflow: Marque perguntas com @synkra/aios-core

Reportando Bugs

Crie relatórios de bug detalhados:

## Ambiente
- SO: macOS 13.0
- Node: 18.17.0
- AIOS: 1.0.0
 
## Passos para Reproduzir
1. Executar `npx @synkra/aios-core init test`
2. Selecionar template "enterprise"
3. Erro ocorre durante instalação
 
## Comportamento Esperado
Instalação completa com sucesso
 
## Comportamento Real
Error: Cannot find module 'inquirer'
 
## Logs
[Anexar diagnostic.log]
 
## Contexto Adicional
Usando proxy corporativo

Recuperação de Emergência

Se tudo mais falhar:

# Fazer backup do estado atual
cp -r .aios .aios.backup
 
# Reset completo
rm -rf .aios node_modules package-lock.json
npm cache clean --force
 
# Instalação limpa
npm install
npx @synkra/aios-core doctor --fix
 
# Restaurar dados se necessário
cp .aios.backup/memory.db .aios/

Lembre-se: A maioria dos problemas pode ser resolvida com:

  1. npx @synkra/aios-core doctor --fix
  2. Limpando caches
  3. Atualizando para a última versão
  4. Verificando permissões

Em caso de dúvida, a comunidade está aqui para ajudar!

Security Best PracticesUninstallation