Wizard di onboarding (CLI)

Il wizard di onboarding è il modo consigliato per configurare OpenClaw su macOS, Linux o Windows (tramite WSL2; fortemente raccomandato). Configura un Gateway locale o una connessione a un Gateway remoto, oltre a canali, skill e impostazioni predefinite del workspace in un unico flusso guidato.

openclaw onboard

Info: Il modo più veloce per chattare: apri la Control UI (nessuna configurazione di canale necessaria). Lancia openclaw dashboard e chatta dal browser. Documentazione: Dashboard.

Per riconfigurare in seguito:

openclaw configure
openclaw agents add <nome>

Nota: --json non implica la modalità non interattiva. Per gli script, usa --non-interactive.

Suggerimento: Il wizard di onboarding include un passaggio di ricerca web dove puoi scegliere un provider (Perplexity, Brave, Gemini, Grok o Kimi) e incollare la tua API key in modo che l’agente possa usare web_search. Puoi anche configurarlo in seguito con openclaw configure --section web. Documentazione: Web tools.

QuickStart vs Avanzato

Il wizard inizia con QuickStart (impostazioni predefinite) vs Avanzato (controllo completo).

QuickStart (impostazioni predefinite)

- Gateway locale (loopback)
- Workspace predefinito (o workspace esistente)
- Porta del Gateway **18789**
- Autenticazione del Gateway con **Token** (generato automaticamente, anche su loopback)
- Policy dei tool predefinita per nuovi setup locali: `tools.profile: "coding"` (un profilo esplicito esistente viene preservato)
- Isolamento DM predefinito: l'onboarding locale scrive `session.dmScope: "per-channel-peer"` quando non impostato. Dettagli: [Riferimento CLI onboarding](/docs/start/wizard-cli-reference#outputs-and-internals)
- Esposizione Tailscale **Off**
- DM Telegram + WhatsApp predefiniti con **allowlist** (ti verrà chiesto il numero di telefono)

Avanzato (controllo completo)

- Espone ogni passaggio (modalità, workspace, gateway, canali, daemon, skill).

Cosa configura il wizard

Modalità locale (predefinita) ti guida attraverso questi passaggi:

  1. Modello/Autenticazione — scegli qualsiasi provider/flusso di autenticazione supportato (API key, OAuth o setup-token), incluso il Custom Provider (compatibile con OpenAI, compatibile con Anthropic, o Unknown con auto-detect). Scegli un modello predefinito. Nota sulla sicurezza: se questo agente eseguirà tool o processerà contenuti da webhook/hook, preferisci il modello più potente di ultima generazione disponibile e mantieni rigorosa la policy sui tool. I modelli più deboli/datati sono più facili da prompt-injectare. Per le esecuzioni non interattive, --secret-input-mode ref salva riferimenti basati su variabili d’ambiente nei profili di autenticazione invece dei valori API key in chiaro. In modalità non interattiva ref, la variabile d’ambiente del provider deve essere impostata; passare flag inline della key senza quella variabile d’ambiente produce un errore immediato. Nelle esecuzioni interattive, scegliendo la modalità con riferimento al secret puoi puntare a una variabile d’ambiente o a un riferimento di provider configurato (file o exec), con una validazione rapida prima del salvataggio.
  2. Workspace — Posizione per i file dell’agente (predefinito ~/.openclaw/workspace). Genera i file di bootstrap.
  3. Gateway — Porta, indirizzo di bind, modalità di autenticazione, esposizione Tailscale. In modalità token interattiva, scegli se salvare il token in chiaro o tramite SecretRef. Percorso SecretRef per token non interattivo: --gateway-token-ref-env <ENV_VAR>.
  4. Canali — WhatsApp, Telegram, Discord, Google Chat, Mattermost, Signal, BlueBubbles o iMessage.
  5. Daemon — Installa un LaunchAgent (macOS) o un’unità utente systemd (Linux/WSL2). Se l’autenticazione con token richiede un token e gateway.auth.token è gestito da SecretRef, l’installazione del daemon lo valida ma non persiste il token risolto nei metadati dell’ambiente del servizio supervisor. Se l’autenticazione con token richiede un token e il SecretRef del token configurato non è risolto, l’installazione del daemon viene bloccata con indicazioni operative. Se sia gateway.auth.token che gateway.auth.password sono configurati e gateway.auth.mode non è impostato, l’installazione del daemon viene bloccata finché la modalità non è impostata esplicitamente.
  6. Verifica di salute — Avvia il Gateway e verifica che sia in esecuzione.
  7. Skill — Installa le skill consigliate e le dipendenze opzionali.

Nota: Rieseguire il wizard non cancella nulla a meno che tu non scelga esplicitamente Reset (o passi --reset). Il CLI --reset di default reimposta configurazione, credenziali e sessioni; usa --reset-scope full per includere il workspace. Se la configurazione non è valida o contiene chiavi legacy, il wizard ti chiede di lanciare openclaw doctor prima.

Modalità remota configura solo il client locale per connettersi a un Gateway altrove. Non installa né modifica nulla sull’host remoto.

Aggiungere un altro agente

Usa openclaw agents add <nome> per creare un agente separato con il proprio workspace, sessioni e profili di autenticazione. Lanciandolo senza --workspace si avvia il wizard.

Cosa imposta:

  • agents.list[].name
  • agents.list[].workspace
  • agents.list[].agentDir

Note:

  • I workspace predefiniti seguono ~/.openclaw/workspace-<agentId>.
  • Aggiungi bindings per instradare i messaggi in ingresso (il wizard può farlo).
  • Flag non interattivi: --model, --agent-dir, --bind, --non-interactive.

Riferimento completo

Per breakdown dettagliati passo-passo e output della configurazione, consulta Riferimento CLI onboarding. Per esempi non interattivi, consulta Automazione CLI. Per il riferimento tecnico approfondito, inclusi i dettagli RPC, consulta Riferimento del wizard.

Documentazione correlata

arrow_back
Precedente
Onboarding Overview
Successivo
Onboarding
arrow_forward