Guia de Instalação Windows para Synkra AIOS

🌐 EN | PT | ES

Versões Suportadas

Pré-requisitos

1. Node.js (v20 ou superior)

Opção A: Usando o Instalador Oficial (Recomendado)

1. Baixe de nodejs.org 
2. Escolha a versão LTS (20.x ou superior)
3. Execute o instalador com opções padrão
4. Verifique a instalação no PowerShell:

node --version  # Deve mostrar v20.x.x
npm --version

Opção B: Usando winget

# Instalar via Windows Package Manager
winget install OpenJS.NodeJS.LTS
 
# Reinicie o PowerShell, depois verifique
node --version

Opção C: Usando Chocolatey

# Instale o Chocolatey primeiro (se não instalado)
Set-ExecutionPolicy Bypass -Scope Process -Force
[System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072
iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))
 
# Instalar Node.js
choco install nodejs-lts -y
 
# Reinicie o PowerShell
node --version

2. Git para Windows

Usando Instalador Oficial (Recomendado)

1. Baixe de git-scm.com 
2. Execute o instalador com estas opções recomendadas:
   • ✅ Git from the command line and also from 3rd-party software
   • ✅ Use bundled OpenSSH
   • ✅ Checkout Windows-style, commit Unix-style line endings
   • ✅ Use Windows’ default console window

Usando winget

winget install Git.Git

Verifique a instalação:

git --version

3. GitHub CLI

Usando winget (Recomendado)

winget install GitHub.cli

Usando Chocolatey

choco install gh -y

Autentique:

gh auth login
# Siga os prompts, escolha "Login with a web browser"

4. Windows Terminal (Recomendado)

Para a melhor experiência, use o Windows Terminal:

winget install Microsoft.WindowsTerminal

Instalação

Instalação Rápida

1. Abra PowerShell ou Windows Terminal

2. Navegue até o diretório do seu projeto:

   cd C:\Users\SeuNome\projetos\meu-projeto

3. Execute o instalador:

   npx github:SynkraAI/aios-core install

O Que o Instalador Faz

O instalador automaticamente:

• ✅ Detecta Windows e aplica configurações específicas da plataforma
• ✅ Cria diretórios necessários com permissões apropriadas
• ✅ Configura caminhos de IDE para localizações Windows:
  • Cursor: %APPDATA%\Cursor\
  • Claude: %USERPROFILE%\.claude\
• ✅ Lida com separadores de caminho Windows (barras invertidas)
• ✅ Configura terminações de linha corretamente (CRLF para batch, LF para scripts)
• ✅ Configura scripts npm compatíveis com cmd.exe e PowerShell

Configuração Específica por IDE

Cursor

1. Baixe de cursor.sh 
2. Execute o instalador
3. Regras da IDE são instaladas em .cursor\rules\
4. Atalho de teclado: Ctrl+L para abrir chat
5. Use @nome-do-agente para ativar agentes

Claude Code (CLI)

1. Instale o Claude Code:

   npm install -g @anthropic-ai/claude-code

2. Comandos são instalados em .claude\commands\AIOS\

3. Use /nome-do-agente para ativar agentes

4. Execute o instalador

5. Use @nome-do-agente para ativar agentes

Solução de Problemas

Erro de Política de Execução

Se você ver running scripts is disabled:

# Verificar política atual
Get-ExecutionPolicy
 
# Definir para permitir scripts locais (recomendado)
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
 
# Ou bypass temporário para sessão atual
Set-ExecutionPolicy -ExecutionPolicy Bypass -Scope Process

Erros de Permissão npm EACCES

# Limpar cache do npm
npm cache clean --force
 
# Definir prefixo npm para diretório do usuário
npm config set prefix "$env:APPDATA\npm"
 
# Adicionar ao PATH (permanente)
[Environment]::SetEnvironmentVariable(
    "Path",
    [Environment]::GetEnvironmentVariable("Path", "User") + ";$env:APPDATA\npm",
    "User"
)

Problemas de Caminho Longo

Windows tem limite de 260 caracteres por padrão. Para habilitar caminhos longos:

1. Abra Editor de Política de Grupo (gpedit.msc)
2. Navegue para: Configuração do Computador → Modelos Administrativos → Sistema → Sistema de Arquivos
3. Habilite “Habilitar caminhos longos Win32”

Ou via PowerShell (requer admin):

# Executar como Administrador
New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" -Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force

Node.js Não Encontrado Após Instalação

# Atualizar variáveis de ambiente
$env:Path = [System.Environment]::GetEnvironmentVariable("Path","Machine") + ";" + [System.Environment]::GetEnvironmentVariable("Path","User")
 
# Ou reinicie PowerShell/Terminal

Antivírus Bloqueando npm

Alguns antivírus bloqueiam operações npm:

1. Adicione exceções para:

   • %APPDATA%\npm
   • %APPDATA%\npm-cache
   • %USERPROFILE%\node_modules
   • Seu diretório de projeto

2. Temporariamente desabilite varredura em tempo real durante instalação (não recomendado para produção)

Problemas de Autenticação GitHub CLI

# Verificar status
gh auth status
 
# Re-autenticar
gh auth login --web
 
# Se atrás de proxy corporativo
$env:HTTPS_PROXY = "http://proxy.empresa.com:8080"
gh auth login

Integração WSL (Opcional)

Para usuários que preferem ferramentas Linux dentro do Windows:

Instalar WSL2

# Executar como Administrador
wsl --install
 
# Instalar Ubuntu (padrão)
wsl --install -d Ubuntu
 
# Reinicie o computador quando solicitado

Configurar AIOS com WSL

# Dentro do WSL, siga o guia de instalação Linux
# Veja: docs/installation/linux.md
 
# Acessar arquivos Windows do WSL
cd /mnt/c/Users/SeuNome/projetos/meu-projeto
 
# Para melhor performance, mantenha projetos no sistema de arquivos Linux
# Use: ~/projetos/ ao invés de /mnt/c/

Atualização

Para atualizar uma instalação existente:

# Usando npx (recomendado)
npx github:SynkraAI/aios-core install
 
# O atualizador irá:
# - Detectar instalação existente
# - Fazer backup de customizações em .aios-backup\
# - Atualizar apenas arquivos modificados
# - Preservar configurações

Requisitos do Sistema

Próximos Passos

1. Configure sua IDE (veja configuração específica por IDE acima)
2. Execute *help no seu agente AI para ver comandos disponíveis
3. Comece com o Guia do Usuário
4. Junte-se à nossa Comunidade no Discord  para ajuda

Recursos Adicionais

• README Principal
• Guia do Usuário
• Guia de Solução de Problemas
• FAQ
• Comunidade Discord 
• GitHub Issues