agent-wiki-ui/docs/INSTALL.md

Installare i motori (Claude Code e Codex)

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)	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 o un codex, il comando può risolvere nella versione Windows. Controllalo con command -v claude e command -v codex.

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.

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.

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): se c'è, la riga dice "Aggiornamento disponibile", il pulsante Aggiorna si evidenzia e compare un puntino sul pulsante Impostazioni. Il pulsante esegue claude update o codex 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
npm	npm install -g @anthropic-ai/claude-code@latest	npm install -g @openai/codex@latest
Homebrew	brew upgrade claude-code	brew upgrade --cask codex
WinGet	winget upgrade Anthropic.ClaudeCode	reinstalla con lo script PowerShell
Nativo / script	claude update	codex update (o rilancia lo script di installazione)

Dettagli e decisioni: ADR-0004.

Controllo finale per l'app

Dallo stesso terminale da cui avvii l'app:

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

Se i comandi rispondono, l'app li trova. Se l'app dice "'claude' non trovato nel PATH":

• apri un nuovo terminale (il PATH si aggiorna solo ai nuovi);
• controlla che la cartella d'installazione sia nel PATH: per Claude Code nativo e per Codex con script è ~/.local/bin su Linux/macOS/WSL, %USERPROFILE%\.local\bin su Windows (per Claude Code);
• 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. La pagina openai.com/it-IT/codex/ non era raggiungibile (HTTP 403).
• Comandi --version, login status, auth status e exec --help: provati sulla macchina descritta sopra.
• Antigravity CLI (agy): non ancora trattato, da aggiungere quando verrà integrato.