agent-wiki-ui/docs/INSTALL.md

Installare i motori (Claude Code, Codex, Antigravity)

L'app non installa né autentica i motori: lancia quelli che trova nel PATH, già installati e con l'accesso fatto (ADR-0002). Questa pagina spiega come prepararli. Fonti e data di consultazione in fondo.

Prima di iniziare: un ambiente, un motore

Il motore va installato nello stesso ambiente in cui gira l'app:

Dove avvii l'app	Dove installare il motore
Linux nativo	nel terminale Linux
WSL (anche con dotnet run --project src/agent-wiki-ui)	nel terminale della distribuzione WSL
Windows (.exe)	in Windows (PowerShell), non in WSL

Dentro WSL il PATH di Windows è visibile (compare /mnt/c/…): se in WSL non c'è un claude, codex o agy, il comando può risolvere nella versione Windows. Controllalo con command -v claude, command -v codex e command -v agy.

Claude Code

Requisiti: macOS 13+, Windows 10 1809+ o Server 2019+, Ubuntu 20.04+, Debian 10+, Alpine 3.19+; 4 GB di RAM, x64 o ARM64, connessione a internet. Su Windows nativo Git for Windows è consigliato ma facoltativo.

Installazione (una delle opzioni; la prima è la raccomandata):

Metodo	Comando
Nativo, Linux/macOS/WSL	curl -fsSL https://claude.ai/install.sh | bash
Nativo, Windows PowerShell	irm https://claude.ai/install.ps1 | iex
Nativo, Windows CMD	curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
Homebrew	brew install --cask claude-code
WinGet	winget install Anthropic.ClaudeCode
npm (serve Node.js 22 o successivo)	npm install -g @anthropic-ai/claude-code (mai con sudo)
apt / dnf / apk	repository firmati: vedi la guida ufficiale

L'installazione nativa non mostra avanzamento durante il download. A fine installazione apri un nuovo terminale.

Da zero su Linux, anche ARM64 (per esempio Raspberry Pi 5 con Raspberry Pi OS a 64 bit). Il metodo nativo riconosce da solo l'architettura (uname -m deve dare aarch64 o x86_64):

sudo apt install -y curl                       # se manca
curl -fsSL https://claude.ai/install.sh | bash
# apri un nuovo terminale, poi:
command -v claude                              # atteso: ~/.local/bin/claude
claude --version
claude                                         # primo avvio: accesso nel browser

Su un Raspberry senza schermo l'accesso nel browser si fa da un altro dispositivo, seguendo l'indirizzo che claude stampa nel terminale (per esempio via SSH); in alternativa usa una API key o un provider cloud, vedi "Accesso". Se ~/.local/bin non è nel PATH aggiungi export PATH="$HOME/.local/bin:$PATH" a ~/.bashrc. Con la sola architettura ARM64 e Debian 10+ i requisiti sono soddisfatti; il metodo npm è l'alternativa se lo script nativo non funziona. Non provato su un Raspberry reale: le istruzioni vengono dalla guida ufficiale.

Accesso: esegui claude e segui le istruzioni nel browser. Serve un account Pro, Max, Team, Enterprise o Console (il piano gratuito di claude.ai non include Claude Code). In alternativa Amazon Bedrock, Google Cloud o Microsoft Foundry.

Verifica

claude --version        # stampa la versione, es. 2.1.x (Claude Code)
claude doctor           # diagnostica di installazione e impostazioni
claude auth status      # mostra se hai fatto l'accesso

Aggiornamento: l'installazione nativa si aggiorna da sola; claude update forza l'aggiornamento. Homebrew, WinGet, npm e i gestori di pacchetti vanno aggiornati a mano (npm install -g @anthropic-ai/claude-code@latest, evitando npm update -g).

Codex CLI

Requisiti: macOS (Apple Silicon e Intel), Linux (x86_64 e arm64), Windows tramite lo script PowerShell. Per l'installazione con npm serve Node.js. Serve un piano ChatGPT (Plus, Pro, Business, Edu o Enterprise) oppure una API key.

Installazione (una delle opzioni):

Metodo	Comando
Script, Linux/macOS/WSL	curl -fsSL https://chatgpt.com/codex/install.sh | sh
Script, Windows PowerShell	powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"
npm	npm install -g @openai/codex
Homebrew	brew install --cask codex
Binario	archivio dalla pagina delle release su GitHub (openai/codex), estratto e rinominato codex

Gli script scaricano da releases.openai.com e, se fallisce, da GitHub Releases; per forzare GitHub imposta CODEX_INSTALLER_USE_RELEASES_OPENAI_COM=false.

Su Windows preferisci lo script PowerShell a npm. L'app avvia l'eseguibile direttamente, senza cmd.exe /c; un'installazione con npm potrebbe produrre uno script .cmd che così non parte (rischio indicato nell'ADR-0002, da verificare su Windows).

Accesso: esegui codex e scegli "Sign in with ChatGPT" (consigliato), oppure usa una API key (guida ufficiale: sezione autenticazione).

Verifica

codex --version         # es. codex-cli 0.144.x
codex login status      # "Logged in using ChatGPT" se l'accesso è fatto
codex exec --help       # uso non interattivo, usato dall'app

Stato su questa macchina (WSL, controllato il 2026-10-15): codex 0.144.3 in ~/.local/bin/codex, collegamento a ~/.codex/packages/standalone/current/bin/codex, con accesso ChatGPT già fatto. claude 2.1.252 in ~/.npm-global/bin/claude, con accesso claude.ai già fatto.

Problema noto: "requires a newer version of Codex". Se il modello predefinito del tuo ~/.codex/config.toml richiede un Codex più recente, codex exec fallisce con quell'errore (l'app lo mostra nella chat). Aggiorna con codex update, oppure scegli un altro modello nelle Impostazioni dell'app. Controllato su questa macchina il 2026-10-15 con Codex 0.144.3.

Antigravity CLI (agy)

Requisiti: Linux x64 (binario nativo ELF) o Windows x64 (eseguibile nativo .exe).

Installazione: binario nativo distribuito ufficialmente (su Linux collocato in ~/.gemini/bin/agy o in una cartella inclusa nel PATH; su Windows agy.exe).

Accesso: autenticazione tramite account Google/Antigravity (agy o configurazione di ambiente).

Verifica

agy --version             # stampa la versione, es. 1.4.2
agy models                # catalogo modelli disponibili
agy update                # controlla e aggiorna alla versione più recente

Permessi per la sola lettura non interattiva: per usare agy in modalità non interattiva (-p) in sola lettura, nel file ~/.gemini/antigravity-cli/settings.json deve essere presente la regola 'read_file(*)' sotto 'permissions.allow' (altrimenti headless mode nega read_file con errore jetski: a tool required the read_file permission that headless mode cannot prompt for), mentre scritture e comandi restano negati di default:

{
  "permissions": {
    "allow": [
      "read_file(*)"
    ]
  }
}

Aggiornare un CLI dall'app

Nel riquadro Impostazioni, sezione Aggiornamenti, l'app controlla da sola, all'avvio e all'apertura del riquadro, se c'è una versione più recente (Claude Code: downloads.claude.ai; Codex: release di GitHub; Antigravity: endpoint ufficiale di auto-update): se c'è, la riga dice "Aggiornamento disponibile", il pulsante Aggiorna si evidenzia e compare un puntino sul pulsante Impostazioni. Il pulsante esegue claude update, codex update o agy update (controllano e installano solo se c'è una versione nuova). Nulla si aggiorna senza un clic. Se non va a buon fine l'app mostra l'errore e il comando manuale, che dipende da come hai installato il CLI:

Installazione	Claude Code	Codex	Antigravity
npm	npm install -g @anthropic-ai/claude-code@latest	npm install -g @openai/codex@latest	agy update
Homebrew	brew upgrade claude-code	brew upgrade --cask codex	brew upgrade agy
WinGet	winget upgrade Anthropic.ClaudeCode	reinstalla con lo script PowerShell	agy update
Nativo / script	claude update	codex update (o rilancia lo script di installazione)	agy update

Dettagli e decisioni: ADR-0004.

Controllo finale per l'app

Dallo stesso terminale da cui avvii l'app:

command -v claude codex agy      # Linux/WSL; in PowerShell: Get-Command claude, codex, agy
claude -p "rispondi solo: ok"
codex exec "rispondi solo: ok"
agy -p "rispondi solo: ok"

Se i comandi rispondono, l'app li trova. Se l'app dice che un motore non è trovato nel PATH:

• apri un nuovo terminale (il PATH si aggiorna solo ai nuovi);
• controlla che la cartella d'installazione sia nel PATH (~/.local/bin, ~/.gemini/bin, o %USERPROFILE%\.local\bin su Windows);
• verifica di non aver installato in un ambiente diverso da quello dell'app (tabella iniziale).

Fonti

• Claude Code: documentazione ufficiale "Advanced setup", consultata il 2026-10-15 (code.claude.com/docs/en/setup).
• Codex: README del repository github.com/openai/codex, consultato il 2026-10-15.
• Antigravity CLI: binario agy verificato in ambiente reale il 2026-10-18.
• Comandi --version, agy models, agy update: provati sulla macchina descritta sopra.