Onboarding (CLI)

L’onboarding CLI è il percorso di configurazione da terminale consigliato per OpenClaw su macOS, Linux o Windows. Gli utenti desktop Windows possono anche iniziare con Windows Hub. Configura un Gateway locale o una connessione a un Gateway remoto, oltre a canali, Skills e impostazioni predefinite dell’area di lavoro in un unico flusso guidato.

openclaw onboard

L’avvio rapido richiede di solito solo pochi minuti, ma l’onboarding completo può richiedere più tempo quando accesso al provider, associazione dei canali, installazione del demone, download di rete, Skills o plugin opzionali richiedono configurazione aggiuntiva. La procedura guidata mostra questa tempistica in anticipo, e i passaggi opzionali possono essere saltati e ripresi in seguito con openclaw configure.

Impostazioni locali

La procedura guidata CLI localizza i testi fissi dell’onboarding. Risolve le impostazioni locali da OPENCLAW_LOCALE, poi LC_ALL, poi LC_MESSAGES, poi LANG, e usa l’inglese come fallback. Le impostazioni locali supportate dalla procedura guidata sono en, zh-CN e zh-TW.

OPENCLAW_LOCALE=zh-CN openclaw onboard

Nomi e identificatori stabili restano letterali: OpenClaw, Gateway, Tailscale, comandi, chiavi di configurazione, URL, ID provider, ID modello ed etichette di plugin/canale non vengono tradotti.

Per riconfigurare in seguito:

openclaw configureopenclaw agents add <name>

Avvio rapido vs avanzato

L’onboarding inizia con Avvio rapido (impostazioni predefinite) vs Avanzato (controllo completo).

Cosa configura l’onboarding

La modalità locale (predefinita) ti guida attraverso questi passaggi:

1. Modello/Autenticazione — scegli qualsiasi provider/flusso di autenticazione supportato (chiave API, OAuth o autenticazione manuale specifica del provider), incluso Provider personalizzato (compatibile con OpenAI, compatibile con Anthropic o rilevamento automatico sconosciuto). Scegli un modello predefinito. Nota di sicurezza: se questo agente eseguirà strumenti o elaborerà contenuti da webhook/hook, preferisci il modello di ultima generazione più potente disponibile e mantieni rigoroso il criterio degli strumenti. I livelli più deboli/vecchi sono più facili da sottoporre a prompt injection. Per esecuzioni non interattive, --secret-input-mode ref memorizza riferimenti basati su env nei profili di autenticazione invece dei valori in chiaro delle chiavi API. In modalità ref non interattiva, la variabile env del provider deve essere impostata; passare flag con chiave inline senza quella variabile env fallisce subito. Nelle esecuzioni interattive, scegliere la modalità riferimento segreto ti consente di puntare a una variabile d’ambiente o a un riferimento provider configurato (file o exec), con una rapida validazione preliminare prima del salvataggio. Per Anthropic, onboarding/configurazione interattivi offrono Anthropic Claude CLI come percorso locale preferito e chiave API Anthropic come percorso consigliato per la produzione. Anche setup-token di Anthropic resta disponibile come percorso supportato di autenticazione tramite token.
2. Area di lavoro — posizione per i file dell’agente (predefinita ~/.openclaw/workspace). Inizializza i file di bootstrap.
3. Gateway — porta, indirizzo di bind, modalità di autenticazione, esposizione Tailscale. In modalità token interattiva, scegli l’archiviazione token in chiaro predefinita o opta per SecretRef. Percorso SecretRef token non interattivo: --gateway-token-ref-env <ENV_VAR>.
4. Canali — canali chat integrati e di plugin ufficiali come iMessage, Discord, Feishu, Google Chat, Mattermost, Microsoft Teams, QQ Bot, Signal, Slack, Telegram, WhatsApp e altri.
5. Demone — installa un LaunchAgent (macOS), un’unità utente systemd (Linux/WSL2) o un’attività pianificata Windows nativa con fallback alla cartella Avvio per utente. Se l’autenticazione tramite token richiede un token e gateway.auth.token è gestito da SecretRef, l’installazione del demone lo valida ma non persiste il token risolto nei metadati dell’ambiente del servizio supervisore. Se l’autenticazione tramite token richiede un token e il SecretRef token configurato non è risolto, l’installazione del demone viene bloccata con indicazioni operative. Se sia gateway.auth.token sia gateway.auth.password sono configurati e gateway.auth.mode non è impostato, l’installazione del demone viene bloccata finché la modalità non viene impostata esplicitamente.
6. Controllo di integrità — avvia il Gateway e verifica che sia in esecuzione.
7. Skills — installa Skills consigliate e dipendenze opzionali.

La 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 <name> per creare un agente separato con la propria area di lavoro, sessioni e profili di autenticazione. L’esecuzione senza --workspace avvia l’onboarding.

Cosa imposta:

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

Note:

• Le aree di lavoro predefinite seguono ~/.openclaw/workspace-<agentId>.
• Aggiungi bindings per instradare i messaggi in ingresso (l’onboarding può farlo).
• Flag non interattivi: --model, --agent-dir, --bind, --non-interactive.

Riferimento completo

Per descrizioni dettagliate passo per passo e output di configurazione, consulta Riferimento alla configurazione CLI. Per esempi non interattivi, consulta Automazione CLI. Per il riferimento tecnico più approfondito, inclusi i dettagli RPC, consulta Riferimento all’onboarding.

Documentazione correlata

• Riferimento comandi CLI: openclaw onboard
• Panoramica dell’onboarding: Panoramica dell’onboarding
• Onboarding dell’app macOS: Onboarding
• Rituale di primo avvio dell’agente: Bootstrap dell’agente