Un comando di installazione e un token bot: configurare OpenClaw 2.0 quando non hai mai usato un agente

I numeri ufficiali sull'installazione di OpenClaw sono poco spettacolari, nel senso migliore. Lo script di installazione richiede 2-5 minuti. L'onboarding QuickStart richiede «qualche minuto». Poi digiti openclaw dashboard, si apre una scheda del browser, mandi un messaggio e qualcosa risponde.

Quindi la parte difficile non è l'installazione. La parte difficile è la settimana dopo: decidere cosa può toccare questa cosa, cosa chiederle e cosa fare quando resta muta senza che tu capisca il perché.

Questa guida è il compagno pratico della nostra lettura su cosa ha davvero cambiato la versione 2.0. Qui niente analisi, solo procedura: cosa preparare, i comandi esatti, cosa chiede il nuovo onboarding guidato e in che ordine, come collegarlo a Telegram, tre prime attività della misura giusta, i permessi da fissare il primo giorno e i cinque errori in cui incappano davvero le nuove installazioni. Ogni comando qui sotto viene dalla documentazione ufficiale di OpenClaw, consultata il 1° settembre 2026. Dove la documentazione tace, questa guida lo dice invece di tirare a indovinare.

In sintesi:

• Ti servono Node.js 22.22.3+, 24.15+ o 25.9+ (consigliato Node 26) e una fonte di IA: un accesso Claude o ChatGPT che già possiedi, una chiave API o un modello locale.
• Il percorso per principianti è una riga — curl -fsSL https://openclaw.ai/install.sh | bash — che installa Node se manca e avvia l'onboarding al posto tuo.
• L'onboarding guidato della 2.0 prova prima a riutilizzare l'accesso IA che hai già e non salva alcuna rotta di modello finché una completion reale non riesce. Questo singolo cambiamento elimina il modo più comune in cui le vecchie installazioni fallivano in silenzio.

I passi da 1 a 4 sono l'avvio rapido documentato. Fonte: OpenClaw «Getting started» e «Install», consultati il 1° settembre 2026.

Cosa serve prima di digitare qualsiasi cosa

Tre prerequisiti, e uno solo richiede una decisione.

Un Node.js supportato. La pagina di installazione indica Node 22.22.3+, 24.15+ o 25.9+, con Node 26 consigliato. Controlla il tuo con node --version. Se Node manca del tutto, l'installer lo predispone: Node 26 su macOS, Node 24 LTS su Linux.

Una macchina che resti sveglia. macOS, Linux e Windows funzionano tutti. La documentazione espone il compromesso senza giri di parole: un portatile è l'opzione con meno attrito e dà all'agente accesso diretto ai file locali e a una finestra di browser visibile, ma sospensione, cadute di rete e aggiornamenti di sistema lo interrompono. Un piccolo server è sempre acceso ma senza schermo. Il minimo documentato per un VPS è 1 vCPU, 1 GB di RAM e circa 500 MB di disco, con 2 GB o più consigliati per margine. Un Raspberry Pi 4 da 4 GB va benissimo, perché il Pi esegue solo il gateway mentre il modello viene invocato in rete.

Comincia dal portatile che hai già. Più avanti potrai spostare tutto copiando due cartelle, e quella migrazione è documentata.

Una fonte di IA. Qui sta la decisione. OpenClaw non include un modello: si collega a un modello.

La configurazione guidata rileva la rotta 1 automaticamente. Prezzi di listino dei fornitori, consultati il 1° settembre 2026.

Mettiamo un numero vero sulla riga della chiave API, perché «pagamento a token» non aiuta a decidere. Prendiamo trenta scambi al giorno, ciascuno con circa 8.000 token di contesto in ingresso e 700 in risposta. Fanno 240.000 token in ingresso e 21.000 in uscita al giorno. Ai listini di Claude Sonnet 5 sono circa 0,69 dollari al giorno, vicino a 21 al mese. Con gpt-5.6-luna sono circa 0,07 dollari al giorno, vicino a 2,20 al mese. È aritmetica su prezzi pubblicati, non una bolletta misurata — il tuo contesto sarà più grande di quanto pensi e la cache ne recupererà una parte — ma l'ordine di grandezza è fissato: dollari, non centinaia di dollari.

Il nostro consiglio per una prima installazione: usa l'abbonamento che già paghi, perché la configurazione guidata lo trova senza che tu incolli nulla. Altrimenti prendi una chiave API da un fornitore qualsiasi e imposta un tetto di spesa rigido nella sua console prima di lanciare l'onboarding. I modelli locali lasciali a dopo: sono una destinazione legittima ma una pessima linea di partenza.

Installazione: un comando e due alternative da conoscere

Il percorso documentato per principianti è lo script di installazione. Rileva il sistema operativo, installa Node se serve, installa OpenClaw e avvia l'onboarding: un comando al posto di quattro decisioni.

Su macOS, Linux o WSL2:

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

Su Windows PowerShell:

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

Questa è tutta l'installazione. Due alternative vale la pena conoscerle anche se oggi non le usi.

Le app desktop, se il terminale non è il tuo ambiente. Windows ha un installer Hub firmato che si esegue come qualsiasi programma Windows; macOS ha un'app nella barra dei menu distribuita come .dmg nelle release GitHub del progetto. Entrambe possono predisporre un gateway locale al primo avvio.

npm, se gestisci già Node per conto tuo. Su npm 12 o npm 11.16+:

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

L'opzione --allow-scripts=openclaw conta: npm 12 blocca per impostazione predefinita gli script di ciclo di vita non approvati e, senza di essa, npm segnala i passi preinstall e postinstall di OpenClaw come «blocked because they are not covered by allowScripts». Su npm 11.15 e precedenti esegui lo stesso comando senza l'opzione. Docker, Podman, Nix e una build da sorgente con pnpm sono altrettanto documentati, e sono tutti la scelta sbagliata per la tua prima ora.

Cosa ti chiede l'onboarding guidato della 2.0, in ordine

È qui che v2026.8.1 ha cambiato di più l'esperienza di chi comincia, perciò conviene sapere cosa arriva. Il semplice openclaw onboard — che l'installer avvia per te — segue ora un percorso guidato in sei passi:

1. Accetta l'avviso di sicurezza. Leggilo. Enuncia il modello di fiducia che stai accettando, e l'ultima sezione di questa guida lo traduce in parole semplici.
2. Parte un rilevamento in sola lettura. OpenClaw cerca modelli già configurati, chiavi API nelle variabili d'ambiente, CLI di IA locali supportate e modelli con supporto agli strumenti già installati su un server Ollama o LM Studio raggiungibile. Questa passata non scarica mai un modello. Due esclusioni documentate: Gemini CLI e Antigravity non vengono offerti come rotte rilevate, e le installazioni di Pi e OpenCode possono comparire a titolo informativo senza essere utilizzabili come rotta di inferenza.
3. Il primo candidato viene testato con una completion reale. Se fallisce, l'onboarding mostra il motivo e passa al candidato successivo invece di salvare una rotta guasta.
4. Se il rilevamento non trova nulla, scegli un fornitore. Il primo menu propone OpenAI, Anthropic, xAI (Grok), Google e OpenRouter, con More… per il resto e Custom Provider per un endpoint non elencato. Un secondo menu mostra regioni, piani e metodi di autenticazione supportati: browser, dispositivo, chiave API o token. Ogni rotta passa lo stesso test di completion reale. Skip for now esce senza proseguire.
5. Viene salvata solo la rotta verificata, insieme alle credenziali o allo stato di plugin che richiede. Spazio di lavoro e impostazioni del gateway restano intatti in questa fase.
6. Parte l'assistente di configurazione con quel modello verificato e configura il resto conversando: spazio di lavoro, gateway, canali, agenti, plugin.

Poi verifica tu stesso:

openclaw gateway status     # deve mostrare il gateway in ascolto sulla porta 18789
openclaw dashboard          # apre la Control UI nel browser

Scrivi un messaggio nella chat della Control UI. Una risposta significa che ogni strato funziona.

Ed ecco il punto, la cosa più utile da capire sulla 2.0: il flusso guidato si rifiuta di salvare una rotta di modello di cui non ha dimostrato il funzionamento. Rilanciare openclaw onboard su un'installazione già configurata funziona quindi anche come passata di riparazione: testa prima il modello predefinito corrente e, se il controllo fallisce, non sostituisce mai il modello in silenzio ma si ferma e chiede.

Due cose che l'onboarding guidato non fa di proposito. Non gestisce la configurazione di gateway remoti, le procedure di abbinamento canali, il controllo del demone, le skill o le importazioni: tutto questo vive nella procedura classica, openclaw onboard --classic. E per cambiare fornitore o autenticazione in seguito si esce dall'assistente e si rilancia openclaw onboard; l'assistente conversazionale non apre i flussi dei fornitori.

Collegare Telegram: quattro passi e un numero da trovare

La documentazione indica Telegram come il canale più veloce da attivare, perché non serve altro che un token bot. La sua politica per i messaggi diretti è impostata di default su pairing, che è l'impostazione sicura e la ragione per cui esiste il passo 3.

1. Crea il bot. Su Telegram scrivi a @BotFather — verifica che il nome sia esattamente quello — ed esegui /newbot. Segui le richieste e conserva il token. C'è anche un percorso web tramite la web app di BotFather, se preferisci un'interfaccia.

2. Metti il token nella configurazione, in ~/.openclaw/openclaw.json:

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "pairing",
      groups: { "*": { requireMention: true } },
    },
  },
}

La variabile d'ambiente TELEGRAM_BOT_TOKEN funziona come ripiego, ma solo per l'account predefinito. Telegram non usa openclaw channels login telegram: metti il token nella configurazione o nell'ambiente, poi avvia il gateway.

3. Avvia il gateway, scrivi al bot e approva te stesso:

openclaw gateway
openclaw pairing list telegram
openclaw pairing approve telegram <CODE>

I codici di abbinamento scadono dopo 1 ora. Se il tuo è scaduto, riscrivi al bot per averne uno nuovo.

4. Trova il tuo ID utente numerico di Telegram e fissalo. L'approvazione dell'abbinamento concede solo l'accesso ai messaggi diretti, non è un'autorizzazione generale. Il metodo rispettoso della privacy indicato dalla documentazione: scrivi al bot, esegui openclaw logs --follow e leggi from.id nella riga di log. La via ufficiale della Bot API è curl "https://api.telegram.org/bot<bot_token>/getUpdates" e leggere message.from.id. Esistono bot di terze parti per lo stesso scopo, meno riservati. Ottenuto il numero, per un bot con un solo proprietario la documentazione consiglia dmPolicy: "allowlist" con il tuo ID numerico in channels.telegram.allowFrom, invece di affidarsi a un'approvazione passata.

I gruppi sono una decisione a parte con una trappola a parte. I bot Telegram sono di default in Privacy Mode, che limita quali messaggi di gruppo ricevono. Per vedere tutto, disattiva quella modalità con /setprivacy in BotFather oppure rendi il bot amministratore del gruppo — e dopo il cambio devi rimuovere e riaggiungere il bot in ogni gruppo perché Telegram applichi la modifica. Il primo giorno salta del tutto i gruppi.

Discord, Signal, WhatsApp, Slack, iMessage, Matrix, Microsoft Teams e una ventina di altri canali sono supportati, ognuno con la sua pagina. Nessuno si attiva in fretta quanto un token bot.

Le tue prime tre attività, dimensionate per una settimana

Gli agenti sono bravi a recuperare, riassumere, sorvegliare e ricordare. Sono inaffidabili in tutto ciò in cui sbagliare costa caro e nessuno controlla. Scegli come prime attività quelle in cui una risposta sbagliata costa cinque secondi di fastidio.

Attività uno: un promemoria una tantum. Dimostra che scheduler, modello e percorso di consegna funzionano insieme, e si cancella da solo alla fine.

openclaw automations create "2026-09-08T09:00:00Z" \
  --name "Reminder" \
  --session main \
  --system-event "Reminder: review the OpenClaw permissions I set on day one" \
  --wake now \
  --delete-after-run

Attività due: un riepilogo mattutino ricorrente. Il campo di pianificazione accetta un'espressione cron standard e il prompt è il secondo argomento posizionale.

openclaw automations create "0 7 * * *" \
  "Summarize what changed in my workspace notes since yesterday." \
  --name "Morning brief"

Poi ispeziona quello che hai costruito, perché leggere la cronologia delle esecuzioni è il modo per capire cosa ha fatto davvero l'agente:

openclaw automations list
openclaw automations runs --id <job-id>

Due proprietà delle automazioni vanno interiorizzate subito. Girano dentro il processo del gateway, il che significa che le pianificazioni scattano solo mentre il gateway è attivo: un portatile chiuso è uno scheduler fermo. E ogni esecuzione crea un record di attività in background, così openclaw tasks list e openclaw tasks audit ti danno una traccia verificabile invece di un mistero.

Attività tre: qualcosa in sola lettura sul tuo materiale. Punta l'agente sul suo spazio di lavoro e chiedigli di riassumere, cercare, confrontare. Nessuna scrittura, niente email, niente calendario, niente shell. Quello che stai facendo è tarare: dopo una settimana saprai in concreto quali richieste centra e quali sbaglia con sicurezza. Quella taratura è il vero risultato della prima settimana, non le automazioni.

Cosa rimandare: il percorso email documentato, il trigger IMAP, è un pattern davvero utile, ma la sua stessa documentazione lo configura dietro un agente lettore ristretto dedicato, con tools.profile: "minimal", una sandbox con workspaceAccess: "none", una lista di mittenti consentiti e autenticazione del mittente basata su DMARC. È la dose giusta di paranoia per lasciare che testo scritto da estranei raggiunga un modello, e non è un progetto del primo giorno.

Il perimetro del primo giorno: decidi fin dove può arrivare prima di decidere cosa può fare

La pagina sulla sicurezza di OpenClaw apre affermando che il prodotto esce con impostazioni conservative: il gateway ascolta in loopback, la maggior parte dei canali risponde a un messaggio diretto sconosciuto con un codice di abbinamento invece di elaborarlo, e l'accesso ai gruppi passa da una lista di consenso dietro una barriera di menzione. Il tuo compito il primo giorno è soprattutto non disfare tutto questo.

Il modello di fiducia, in parole semplici. Un gateway equivale a un confine di fiducia. Chiunque possa scrivere a un agente dotato di strumenti condivide l'autorità di quegli strumenti. Per te va bene, per colleghi che già si fidano va bene, e per utenti reciprocamente ostili che condividono un agente è esplicitamente non supportato. Chi può modificare i file sotto ~/.openclaw è, per definizione, un operatore fidato. Se devi servire persone che non si fidano tra loro, la risposta documentata è separare i gateway, idealmente anche gli utenti di sistema o le macchine, non una configurazione ingegnosa.

Un comando ti dice se sei andato alla deriva:

openclaw security audit
openclaw security audit --fix    # applica solo correzioni strette e sicure

L'ordine di triage dell'audit è una buona lista di priorità per chi comincia: prima tutto ciò che è «aperto» combinato con strumenti attivi, poi l'esposizione pubblica in rete, poi l'esposizione del controllo browser, poi i permessi dei file, poi i plugin e infine la scelta del modello.

Cosa non collegare nella prima settimana. Non impostare nessuna dmPolicy su "open": qualsiasi account Telegram che trovi o indovini il nome del tuo bot potrebbe comandarlo. Non esporre il gateway oltre il loopback e non attivare Tailscale Funnel. Non attivare tools.elevated, la via di fuga che esegue comandi shell fuori dalla sandbox. Non installare plugin che non hai letto. E usa il modello di generazione attuale più forte che riesci a ottenere, perché la documentazione è esplicita: i modelli più deboli o troppo quantizzati sono più facili da dirottare con prompt injection, cosa che conta nel momento in cui un agente con strumenti legge testo scritto da qualcun altro.

Parti in sola lettura dove puoi. Un profilo documentato combina una sandbox con workspaceAccess: "ro" e una lista di strumenti negati:

{
  agents: {
    entries: {
      family: {
        default: true,
        workspace: "~/.openclaw/workspace-family",
        sandbox: { mode: "all", scope: "agent", workspaceAccess: "ro" },
        tools: {
          allow: ["read"],
          deny: ["write", "edit", "apply_patch", "exec", "process", "browser"],
        },
      },
    },
  },
}

Come fermarlo. Impara questi comandi prima di averne bisogno, non dopo.

openclaw gateway stop        # ferma il servizio gestito
openclaw gateway restart     # riavvia (non concatenare stop e start come sostituto)
openclaw backup create       # istantanea prima di qualsiasi operazione distruttiva
openclaw uninstall --dry-run # vedere esattamente cosa cancellerebbe una rimozione

openclaw gateway stop richiede --force in una shell non interattiva. Su macOS rimuove il LaunchAgent dalla sessione di avvio corrente; aggiungi --disable se vuoi che l'arresto sopravviva a un riavvio. E l'ordine di contenimento, se qualcosa va davvero storto: fermare il processo, impostare gateway.bind: "loopback", poi portare i messaggi diretti a rischio su dmPolicy: "disabled" ed eliminare ogni voce "*".

I cinque errori in cui i principianti incappano davvero

openclaw: command not found dopo un'installazione riuscita. Quasi sempre è il PATH: la cartella bin globale di npm non è nel PATH della shell. Diagnostica con node -v, npm prefix -g e echo "$PATH". Su Windows controlla npm config get prefix, aggiungi quella cartella al PATH utente e riapri PowerShell.

L'installer sembra bloccato. Rilancialo con --verbose per ottenere un riscontro reale: curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --verbose. L'installer PowerShell non ha un'opzione verbose; racchiudilo invece tra Set-PSDebug -Trace 1 e -Trace 0.

L'onboarding mostra la riga di risveglio, non risponde nulla e il contatore dei token resta a 0. L'agente non è mai partito. Riavvia il gateway, poi controlla autenticazione e log in quest'ordine:

openclaw gateway restart
openclaw status
openclaw models status
openclaw logs --follow
openclaw doctor

Se hai saltato la configurazione del modello, l'onboarding te lo segnala con la nota «Model auth missing»: risolvi con openclaw configure --section model.

Telegram segnala getMe returned 401 all'avvio. È un errore di autenticazione del token bot, punto. Ricopia o rigenera il token in BotFather e aggiorna channels.telegram.botToken. Un deleteWebhook 401 Unauthorized durante l'avvio è lo stesso token errato che riemerge altrove.

Il bot ignora i messaggi di gruppo. Controlla tre cose in quest'ordine: se la modalità privacy è ancora attiva (BotFather /setprivacy, poi rimuovere e riaggiungere il bot), se il gruppo è davvero elencato in channels.telegram.groups, e quale motivo di esclusione dà openclaw logs --follow. Gli ID negativi dei supergruppi che iniziano con -100 vanno sotto groups, non sotto groupAllowFrom: una confusione davvero frequente.

Quando niente di tutto ciò aiuta, un comando trasforma lo stato della tua installazione in una diagnosi: openclaw triage esegue controlli in sola lettura, scrive un prompt ripulito con quanto ha trovato e propone di consegnarlo a un agente di codice presente sulla tua macchina. Nulla lascia la macchina finché non ne scegli uno, e segreti, token, payload di chat grezzi e log grezzi restano esclusi dal prompt.

Dove andare dopo

La destinazione è la documentazione, ed è insolitamente comoda da percorrere: aggiungi .md a qualsiasi URL di pagina per ottenere Markdown pulito, e docs.openclaw.ai/llms.txt è un indice completo di tutte le pagine con una riga di descrizione. Da mettere nei preferiti il primo giorno: Getting started, Channels, Security e Automations. openclaw docs cerca in quell'indice dal terminale.

Un limite onesto prima di chiudere. Gli agenti sbagliano, e un agente con strumenti commette errori che toccano qualcosa. La documentazione di OpenClaw lo dice apertamente: il testo restituito da ricerca, fetch, MCP, plugin e browser viene limitato, normalizzato e marcato esplicitamente come non affidabile prima che il modello lo veda — e anche così «il modello può comunque essere influenzato dal materiale ostile che legge». Prendi l'abitudine di concedere il permesso più stretto che renda possibile un compito, e allarga il perimetro solo quando un compito preciso lo impone.

In conclusione: la configurazione dura otto minuti, il discernimento tutta la settimana

L'installazione è davvero un comando. L'onboarding trova davvero l'abbonamento che già paghi. Ciò che nessun installer può fare al posto tuo è decidere fin dove può arrivare un processo autonomo che agisce a tuo nome — ed è quella decisione, non la configurazione, a separare chi ottiene lavoro vero da un agente da chi smette silenziosamente di aprirlo dopo due settimane.

Comincia con un agente in sola lettura che al massimo può infastidirti. Allarga il perimetro un permesso alla volta, ogni volta perché un compito preciso lo ha richiesto. È una prima settimana più lenta e un secondo mese molto migliore.

Che cosa affideresti davvero a un programma mentre non stai guardando?

---

Dove si inserisce Telli.sh: un agente gestisce i compiti che gli affidi; Telli.sh conserva il resoconto delle conversazioni che hai con le persone. Applica trascrizione in tempo reale, separazione dei parlanti e riassunti con IA alle tue riunioni, con traduzione in 44 lingue di destinazione e un'interfaccia in 15, così le decisioni prese durante una chiamata finiscono in una nota consultabile e non in un ricordo. Se il tuo agente deve agire in base a ciò che il team ha concordato, qualcosa deve aver messo per iscritto quell'accordo con precisione.

Avvia una nota IA dal vivo

Fonti

• OpenClaw — Getting started — requisito Node 22.22.3+/24.15+/25.9+, comandi di installazione, openclaw gateway status sulla porta 18789, openclaw dashboard e openclaw triage; consultato il 1° settembre 2026
• OpenClaw — Install — requisiti di sistema, download delle app desktop, percorsi npm/pnpm/bun e la regola --allow-scripts=openclaw di npm 12, risoluzione dei problemi di PATH; consultato il 1° settembre 2026
• OpenClaw — Onboarding (CLI) — percorso guidato in sei passi, verifica tramite completion reale, menu dei fornitori, esclusione di Gemini CLI e Antigravity, ambito di --classic; consultato il 1° settembre 2026
• OpenClaw — Note di rilascio v2026.8.1 (OpenClaw 2.0) — onboarding guidato come flusso custodian locale, passaggio al browser dopo la configurazione e marcatura dei contenuti esterni non affidabili; consultato il 1° settembre 2026
• OpenClaw — Telegram — /newbot in BotFather, blocco di configurazione, openclaw pairing list/approve, scadenza di un'ora, modalità privacy e obbligo di riaggiungere il bot, regola degli ID -100, firma getMe returned 401; consultato il 1° settembre 2026
• OpenClaw — Security — impostazioni conservative, modello di un confine di fiducia per gateway, openclaw security audit e il suo ordine di triage, profilo di agente in sola lettura e sequenza di contenimento; consultato il 1° settembre 2026
• OpenClaw — FAQ: first-run setup — stima di 2-5 minuti, riuso di Claude CLI e relativa avvertenza sulla fatturazione, supporto OAuth di Codex, sequenza di ripristino quando non arriva risposta, requisiti minimi VPS e confronto portatile/server; consultato il 1° settembre 2026
• OpenClaw — FAQ: models and auth — raccomandazione del modello più forte per agenti con strumenti e percorso di configurazione di Ollama; consultato il 1° settembre 2026
• OpenClaw — Automations e openclaw automations — sintassi create una tantum e cron, esecuzione dentro il gateway, cronologia; consultato il 1° settembre 2026
• OpenClaw — Local models — il limite della singola GPU da 24 GB e l'avvertenza sui checkpoint quantizzati; consultato il 1° settembre 2026
• OpenClaw — openclaw gateway e openclaw uninstall — semantica di arresto e riavvio, obbligo di --force nelle shell non interattive e rimozione con --dry-run; consultato il 1° settembre 2026
• Anthropic — Prezzi dei modelli — Claude Sonnet 5 a 2/10 dollari per milione di token e Claude Opus 5 a 5/25; consultato il 1° settembre 2026
• OpenAI — Prezzi API — gpt-5.6-luna a 0,20 dollari in ingresso e 1,20 in uscita per milione di token; consultato il 1° settembre 2026
• Il nostro articolo gemello su cosa ha davvero cambiato il rilascio di OpenClaw 2.0