Installazione di OpenClaw e configurazione di OmniProxy

OpenClaw è un assistente AI installato sul tuo computer. Puoi comunicare direttamente con lui tramite Telegram, Discord, WhatsApp o Feishu, senza dover tenere sempre aperta un’altra finestra di chat; le conversazioni e la cronologia rimangono su questo computer e l’assistente può anche completare localmente i passaggi successivi.

Preparazione all’installazione

OpenClaw richiede Node 24.16 o versioni successive; è possibile usare anche Node 26.1 o versioni successive ed è consigliato Node 26. Node è l’ambiente di base necessario per eseguire OpenClaw.

L’installazione è disponibile per macOS, Linux e Windows. Se sul computer non è presente una versione adatta di Node, lo script di installazione la predisporrà automaticamente: Node 26 su macOS e Node 24 LTS su Linux. pnpm è necessario solo quando si compila OpenClaw dal codice sorgente.

Se sul computer è già installata una versione meno recente di Node, non è necessario disinstallarla subito. Durante il test del 2026-10-09, la versione di sistema di Node su questo computer era la 24.2.0, inferiore alla versione 24.16 richiesta; lo script di installazione non interattivo ha predisposto autonomamente Node 24.21.0.

Vuoi una finestra

Compagno desktop

Pacchetto di installazione Hub su Windows
DMG da GitHub su macOS
La prima volta puoi installare un Gateway locale

Consigliato ufficialmente

Script di installazione

macOS Linux WSL2
Su Windows usa PowerShell
Puoi aggiungere --no-onboard

Node già installato

Gestore di pacchetti

npm pnpm o bun
Poi esegui onboard
La versione di Node è indicata nella pagina di installazione

Scarica l'app complementare desktop se vuoi un'interfaccia grafica. Se vuoi usare solo il terminale, esegui lo script di installazione ufficiale.

Installazione e primo avvio

Puoi installare l’app complementare desktop dotata di interfaccia grafica oppure procedere direttamente dal terminale. Gateway è il servizio locale che riceve i messaggi, chiama il modello e restituisce i risultati; puoi configurarlo durante il primo avvio dell’app complementare desktop.

Se vuoi un’interfaccia grafica

Windows: scarica ed esegui OpenClawCompanion-Setup-x64.exe oppure OpenClawCompanion-Setup-arm64.exe. Il pacchetto di installazione è firmato e include impostazioni, stato nell’area di notifica, chat e modalità node.
macOS: scarica il file .dmg di OpenClaw dalle release GitHub di OpenClaw. Usa preferibilmente il dmg; in alternativa, puoi usare il file .zip. Al termine dell’installazione, apri OpenClaw.app. Se questa versione non include file per macOS, segui le indicazioni nella pagina dell’applicazione macOS.

Al primo avvio puoi consentire a OpenClaw di configurare Gateway su questo computer oppure collegarti a un Gateway remoto già esistente.

Installazione dal terminale

Su macOS, Linux e WSL2 usa:

curl -fsSL https://openclaw.ai/install.sh | bash

In Windows PowerShell usa:

iwr -useb https://openclaw.ai/install.ps1 | iex

Lo script rileva il sistema in uso, installa Node quando necessario, quindi installa OpenClaw e avvia la procedura guidata iniziale. La procedura guidata ti accompagnerà nella prima configurazione.

Se per il momento non vuoi avviare la procedura guidata, su macOS, Linux e WSL2 usa invece:

curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard

Su Windows usa l’opzione ufficiale -NoOnboard:

& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard

Se gestisci Node autonomamente, puoi usare anche npm, pnpm o bun. Con npm 12 oppure npm 11.16 e versioni successive, esegui:

npm install -g openclaw@latest --allow-scripts=openclaw
openclaw onboard --install-daemon

Con npm 11.15 e versioni precedenti devi rimuovere --allow-scripts=openclaw. Se usi pnpm, devi aggiungere --allow-build=openclaw. Per le differenze specifiche, consulta la pagina di installazione.

Al termine dell’installazione, esegui nell’ordine i tre comandi seguenti:

openclaw --version
openclaw doctor
openclaw gateway status

openclaw --version mostra la versione, openclaw doctor verifica i problemi comuni dell’ambiente e openclaw gateway status indica se Gateway è in esecuzione. L’installazione di base può essere considerata completata solo se tutti e tre i comandi producono un output normale.

Se il terminale segnala che non riesce a trovare openclaw, in genere la directory bin globale di npm non è inclusa in PATH. PATH è l’elenco delle posizioni nelle quali il terminale cerca i programmi. Puoi confrontare i risultati di node -v, npm prefix -g ed echo "$PATH", aggiungere a PATH la directory bin corrispondente e quindi riaprire il terminale.

Se ~/.openclaw contiene già una configurazione in uso, lo script di installazione predefinito utilizzerà quella directory. Per effettuare un’installazione separata senza modificare la configurazione esistente, puoi eseguire lo script non interattivo indicando una nuova directory:

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --prefix "$HOME/openclaw-omniproxy" --no-onboard

--no-onboard è il comportamento predefinito di questo script. Il 2026-10-09, questo comando ha installato OpenClaw 2026.9.9. Al termine dell’installazione devi eseguire openclaw dalla directory bin di questa installazione.

Ottenere i parametri di connessione da OmniProxy

Verifica innanzitutto che OmniProxy sia in esecuzione, quindi apri il suo elenco dei modelli e prepara i tre valori seguenti:

baseUrl: https://your-omniproxy-origin.example/v1
apiKey:  <YOUR_OMNIPROXY_API_KEY>
Model ID: copia per intero dall'elenco attuale dei modelli di OmniProxy

baseUrl è l’indirizzo al quale OpenClaw invia le richieste del modello e deve terminare con /v1. Per l’integrazione con OmniProxy, usa openai-completions come valore di api. Passa a openai-responses solo se il modello funziona effettivamente tramite /v1/responses.

Model ID è l’identificatore completo del modello nell’elenco. Copialo esattamente come appare e conserva anche tutte le barre presenti. I due nomi seguenti sono riportati solo come riferimento rispetto alla documentazione dei fornitori disponibile il 2026-10-09; non usarli se non compaiono nell’elenco: claude-sonnet-5-5, gpt-6-luna.

Anche se il gateway non verifica la chiave, apiKey deve comunque contenere un valore; puoi usare una sequenza di caratteri segnaposto impiegata soltanto su questo computer. Non inserire una chiave reale nel repository.

Inserire la configurazione dello strumento

Un Provider può essere considerato un insieme di impostazioni di connessione che OpenClaw utilizza per trovare il servizio del modello. Qui il Provider viene denominato omniproxy.

Esegui nel terminale il comando seguente, sostituendo l’indirizzo, la chiave e i due ID modello con i tuoi valori:

openclaw config set models.providers.omniproxy '{"baseUrl":"https://your-omniproxy-origin.example/v1","apiKey":"<YOUR_OMNIPROXY_API_KEY>","api":"openai-completions","models":[{"id":"claude-sonnet-5-5","name":"Claude Sonnet 5.5"},{"id":"gpt-6-luna","name":"GPT-6 Luna"}]}' --strict-json --merge

Questo comando scrive nella configurazione il Provider e l’elenco dei modelli. Dopo l’esecuzione corretta del comando, non è necessario riavviare Gateway.

Specifica quindi il modello predefinito. Il riferimento al modello è formato da omniproxy/ seguito dal Model ID; conserva tutte le barre già presenti nell’ID. Se l’ID nell’elenco dei modelli è più lungo del nome abbreviato riportato di seguito, usa il valore completo presente nell’elenco:

openclaw config set agents.defaults.model.primary '"omniproxy/claude-sonnet-5-5"' --strict-json

Puoi omettere reasoning, input, cost, contextWindow e maxTokens. Se questi valori non vengono specificati, i modelli testuali vengono gestiti secondo le impostazioni predefinite.

La stessa configurazione può essere inserita direttamente nel file di configurazione. Nella configurazione principale, il Provider si trova in models.providers. Ogni agent può inoltre avere il proprio models.json; un agent è l’istanza dell’assistente che riceve effettivamente le attività e chiama il modello. Il file si trova in ~/.openclaw/agents/, nel percorso agent/models.json all’interno della directory dell’agent corrispondente.

Se questo models.json contiene un valore baseUrl non vuoto, tale valore sostituisce l’indirizzo della configurazione principale.

Controllo dell'installazione

Tre comandi

openclaw --version
openclaw doctor
gateway status

Configurazione

models.providers

baseUrl termina con /v1
api usa completions
Il modello deve contenere almeno id

Selezione

provider/modello

Usa questo riferimento per primary
Preferisci una variabile d'ambiente per la chiave
Fai riferimento all'elenco del gateway

Verifica prima che il comando sia disponibile, quindi inserisci l'indirizzo e il modello. Il riferimento al modello deve includere il nome del Provider.

Verificare un’attività reale

Apri una normale directory di progetto e invia un messaggio molto breve. Sostituisci il riferimento al modello nel comando con il tuo Model ID completo:

openclaw agent --local --model omniproxy/claude-sonnet-5-5 --timeout 300 --message "Rispondi con una parola."

--local indica che questa attività dell’agent viene eseguita localmente, --model specifica il modello da usare e --timeout 300 imposta un’attesa massima di 300 secondi.

Nel terminale deve comparire una risposta effettiva del modello. Il 2026-10-09, OpenClaw 2026.9.9 ha ricevuto una risposta usando questo comando. La prima chiamata potrebbe richiedere uno o due minuti.

Se compare il messaggio di errore originale Request timed out before a response was generated, aumenta prima il valore di --timeout, quindi invia nuovamente il messaggio. In genere significa che il tempo di attesa era insufficiente e non indica necessariamente che l’indirizzo sia errato.

Dopo aver ricevuto correttamente la risposta breve, chiedi all’assistente di leggere un file locale da te specificato. Apri quindi il registro delle chiamate di OmniProxy e verifica l’origine e il Model ID riportati nel registro. La sola visualizzazione del numero di versione o dell’output di doctor non dimostra che la connessione al modello sia stata configurata correttamente.

Installazione

Il comando risponde

Il numero di versione viene visualizzato
doctor non blocca l'esecuzione
Lo stato del Gateway è leggibile

Attività

Ha svolto una piccola attività

Ad esempio, legge un file locale
La risposta non è un errore
Il riferimento al modello è corretto

Registri

Visibile dal gateway

La fonte è OpenClaw
L'ID del modello corrisponde
La chiave non entra nel repository

Dopo aver ottenuto l'output del comando della versione, devi ricevere anche una risposta reale.

Errori comuni

openclaw non viene trovato: aggiungi la directory bin globale di npm a PATH, quindi riapri il terminale. Se hai installato OpenClaw in una directory specifica, esegui il programma dalla directory bin di tale installazione.
node -v restituisce una versione precedente alla 24.16: non è necessario disinstallare prima la vecchia versione. Controlla la versione di Node predisposta dallo script di installazione oppure usa una versione 24.16+ o 26.1+ seguendo la pagina di installazione. È consigliato Node 26.
Il modello non compare: il modello deve essere incluso nell’array models di models.providers e deve contenere almeno lo stesso id. La sola aggiunta del modello a agents.defaults.models non registra separatamente un nuovo modello.
Viene restituito un errore 400 che menziona il ruolo developer: quando l’host dell’indirizzo non è api.openai.com, mantieni il valore predefinito e non impostare supportsDeveloperRole su true. Anche se viene impostato su true, il valore sarà comunque sostituito.
Timeout molto rapido: aumenta --timeout ad almeno 300 secondi e, inizialmente, non modificare l’indirizzo.
Hai selezionato gpt-6-luna, ma la chiamata degli strumenti non riesce: il modello supporta Chat Completions; in Chat Completions, le chiamate di funzione sono supportate solo quando reasoning_effort è impostato su none. Se l’ID nell’elenco è diverso, usa quello riportato nell’elenco.
Impossibile collegarsi all’indirizzo: verifica che OmniProxy sia in esecuzione, che baseUrl termini con /v1 e che l’indirizzo scritto nella configurazione sia raggiungibile. Gli altri indirizzi di rete privata devono essere autorizzati separatamente.
Dopo la configurazione le richieste vengono ancora inviate a un altro indirizzo: controlla se il file models.json dell’agent contiene un valore baseUrl diverso.

Riferimenti ufficiali

Per i passaggi di installazione, consulta OpenClaw install. Per configurare un Provider personalizzato, consulta Custom providers e campi di configurazione. Per confrontare gli ID modello usati negli esempi, consulta panoramica dei modelli Claude e GPT-6 Luna.

Sostituisci ogni segnaposto con valori dalla tua configurazione OmniProxy personale. Non pubblicare mai una chiave reale.

Un risultato salvato o HTTP 200 da soli non provano la piena compatibilità con l'Agente. Controlla l'origine e il modello nel registro delle chiamate di OmniProxy.

Fonti ufficiali · OpenClaw ↗