Riferimento CLI onboarding

Questa pagina contiene il riferimento completo per openclaw onboard. Per la guida rapida, consulta Wizard di onboarding (CLI).

Cosa fa il wizard

La modalità locale (predefinita) ti guida attraverso:

• Setup di modello e autenticazione (sottoscrizione OpenAI Code OAuth, API key Anthropic o setup token, più opzioni MiniMax, GLM, Ollama, Moonshot e AI Gateway)
• Posizione del workspace e file di bootstrap
• Impostazioni del Gateway (porta, bind, autenticazione, tailscale)
• Canali e provider (Telegram, WhatsApp, Discord, Google Chat, plugin Mattermost, Signal)
• Installazione daemon (LaunchAgent o unità utente systemd)
• Verifica di salute
• Setup delle skill

La modalità remota configura questa macchina per connettersi a un gateway altrove. Non installa né modifica nulla sull’host remoto.

Dettagli del flusso locale

Passo 1: Rilevamento configurazione esistente

- Se `~/.openclaw/openclaw.json` esiste, scegli Mantieni, Modifica o Reimposta.
- Rieseguire il wizard non cancella nulla a meno che tu non scelga esplicitamente Reimposta (o passi `--reset`).
- Il CLI `--reset` di default reimposta `config+creds+sessions`; usa `--reset-scope full` per rimuovere anche il workspace.
- Se la configurazione non è valida o contiene chiavi legacy, il wizard si ferma e ti chiede di lanciare `openclaw doctor` prima di proseguire.
- Il reset usa `trash` e offre diversi ambiti:
  - Solo configurazione
  - Configurazione + credenziali + sessioni
  - Reset completo (rimuove anche il workspace)

Passo 2: Modello e autenticazione

- La matrice completa delle opzioni si trova in [Opzioni di autenticazione e modello](#opzioni-di-autenticazione-e-modello).

Passo 3: Workspace

- Predefinito `~/.openclaw/workspace` (configurabile).
- Genera i file del workspace necessari per il rituale di bootstrap al primo avvio.
- Layout del workspace: [Workspace dell'agente](/docs/concepts/agent-workspace).

Passo 4: Gateway

- Chiede porta, bind, modalità di autenticazione ed esposizione tailscale.
- Consigliato: mantieni l'autenticazione con token attiva anche su loopback, così i client WS locali devono autenticarsi.
- In modalità token, l'onboarding interattivo offre:
  - **Genera/salva token in chiaro** (predefinito)
  - **Usa SecretRef** (opt-in)
- In modalità password, l'onboarding interattivo supporta anche lo storage in chiaro o SecretRef.
- Percorso SecretRef per token non interattivo: `--gateway-token-ref-env <ENV_VAR>`.
  - Richiede una variabile d'ambiente non vuota nell'ambiente del processo di onboarding.
  - Non può essere combinato con `--gateway-token`.
- Disabilita l'autenticazione solo se ti fidi completamente di ogni processo locale.
- I bind non-loopback richiedono comunque l'autenticazione.

Passo 5: Canali

- [WhatsApp](/docs/channels/whatsapp): login QR opzionale
- [Telegram](/docs/channels/telegram): token del bot
- [Discord](/docs/channels/discord): token del bot
- [Google Chat](/docs/channels/googlechat): JSON del service account + audience del webhook
- Plugin [Mattermost](/docs/channels/mattermost): token del bot + URL base
- [Signal](/docs/channels/signal): installazione opzionale di `signal-cli` + configurazione account
- [BlueBubbles](/docs/channels/bluebubbles): consigliato per iMessage; URL del server + password + webhook
- [iMessage](/docs/channels/imessage): percorso CLI `imsg` legacy + accesso al DB
- Sicurezza DM: l'impostazione predefinita è il pairing. Il primo DM invia un codice; approvalo con
  `openclaw pairing approve <canale> <codice>` oppure usa le allowlist.

Passo 6: Installazione daemon

- macOS: LaunchAgent
  - Richiede una sessione utente attiva; per headless, usa un LaunchDaemon personalizzato (non fornito).
- Linux e Windows tramite WSL2: unità utente systemd
  - Il wizard tenta `loginctl enable-linger <utente>` perché il gateway resti attivo dopo il logout.
  - Potrebbe richiedere sudo (scrive in `/var/lib/systemd/linger`); tenta prima senza sudo.
- Selezione del runtime: Node (consigliato; necessario per WhatsApp e Telegram). Bun non è raccomandato.

Passo 7: Verifica di salute

- Avvia il gateway (se necessario) ed esegue `openclaw health`.
- `openclaw status --deep` aggiunge probe di salute del gateway all'output dello stato.

Passo 8: Skill

- Legge le skill disponibili e verifica i requisiti.
- Ti permette di scegliere il gestore dei pacchetti node: npm o pnpm (bun non raccomandato).
- Installa le dipendenze opzionali (alcune usano Homebrew su macOS).

Passo 9: Fine

- Riepilogo e passi successivi, incluse le opzioni per le app iOS, Android e macOS.

Nota: Se non viene rilevata una GUI, il wizard stampa le istruzioni per il port-forward SSH per la Control UI invece di aprire un browser. Se gli asset della Control UI non sono presenti, il wizard tenta di compilarli; il fallback è pnpm ui:build (installa automaticamente le dipendenze della UI).

Dettagli della modalità remota

La modalità remota configura questa macchina per connettersi a un gateway altrove.

Info: La modalità remota non installa né modifica nulla sull’host remoto.

Cosa imposti:

• URL del gateway remoto (ws://...)
• Token se l’autenticazione del gateway remoto è richiesta (consigliato)

Nota:

• Se il gateway è solo loopback, usa il tunneling SSH o una tailnet.
• Suggerimenti per il discovery:
  • macOS: Bonjour (dns-sd)
  • Linux: Avahi (avahi-browse)

Opzioni di autenticazione e modello

Usa `ANTHROPIC_API_KEY` se presente oppure chiede una key, poi la salva per l'uso del daemon.

- macOS: controlla l'elemento Keychain "Claude Code-credentials"
- Linux e Windows: riutilizza `~/.claude/.credentials.json` se presente

Su macOS, scegli "Consenti sempre" in modo che gli avvii launchd non si blocchino.

Lancia `claude setup-token` su qualsiasi macchina, poi incolla il token.
Puoi dargli un nome; lascia vuoto per il predefinito.

Se `~/.codex/auth.json` esiste, il wizard può riutilizzarlo.

Flusso via browser; incolla `code#state`.

Imposta `agents.defaults.model` su `openai-codex/gpt-5.4` quando il modello non è impostato o è `openai/*`.

Usa `OPENAI_API_KEY` se presente oppure chiede una key, poi salva le credenziali nei profili di autenticazione.

Imposta `agents.defaults.model` su `openai/gpt-5.1-codex` quando il modello non è impostato, è `openai/*` o `openai-codex/*`.

Chiede `XAI_API_KEY` e configura xAI come provider di modelli.

Chiede `OPENCODE_API_KEY` (o `OPENCODE_ZEN_API_KEY`) e ti permette di scegliere il catalogo Zen o Go.
URL di setup: [opencode.ai/auth](https://opencode.ai/auth).

Salva la key per te.

Chiede `AI_GATEWAY_API_KEY`.
Maggiori dettagli: [Vercel AI Gateway](/docs/providers/vercel-ai-gateway).

Chiede account ID, gateway ID e `CLOUDFLARE_AI_GATEWAY_API_KEY`.
Maggiori dettagli: [Cloudflare AI Gateway](/docs/providers/cloudflare-ai-gateway).

La configurazione viene scritta automaticamente.
Maggiori dettagli: [MiniMax](/docs/providers/minimax).

Chiede `SYNTHETIC_API_KEY`.
Maggiori dettagli: [Synthetic](/docs/providers/synthetic).

Chiede l'URL base (predefinito `http://127.0.0.1:11434`), poi offre la modalità Cloud + Locale o solo Locale.
Rileva i modelli disponibili e suggerisce le impostazioni predefinite.
Maggiori dettagli: [Ollama](/docs/providers/ollama).

Le configurazioni di Moonshot (Kimi K2) e Kimi Coding vengono scritte automaticamente.
Maggiori dettagli: [Moonshot AI (Kimi + Kimi Coding)](/docs/providers/moonshot).

Funziona con endpoint compatibili con OpenAI e Anthropic.

L'onboarding interattivo supporta le stesse opzioni di storage delle API key degli altri flussi di autenticazione:
- **Incolla la API key ora** (chiaro)
- **Usa riferimento al secret** (ref a variabile d'ambiente o ref a provider configurato, con validazione preventiva)

Flag non interattivi:
- `--auth-choice custom-api-key`
- `--custom-base-url`
- `--custom-model-id`
- `--custom-api-key` (opzionale; fallback su `CUSTOM_API_KEY`)
- `--custom-provider-id` (opzionale)
- `--custom-compatibility <openai|anthropic>` (opzionale; predefinito `openai`)

Lascia l'autenticazione non configurata.

Comportamento del modello:

• Scegli il modello predefinito dalle opzioni rilevate, oppure inserisci provider e modello manualmente.
• Il wizard esegue un controllo del modello e avverte se il modello configurato è sconosciuto o manca l’autenticazione.

Percorsi di credenziali e profili:

• Credenziali OAuth: ~/.openclaw/credentials/oauth.json
• Profili di autenticazione (API key + OAuth): ~/.openclaw/agents/<agentId>/agent/auth-profiles.json

Modalità di storage delle credenziali:

• Il comportamento predefinito dell’onboarding persiste le API key come valori in chiaro nei profili di autenticazione.
• --secret-input-mode ref abilita la modalità a riferimento invece dello storage in chiaro. Nell’onboarding interattivo puoi scegliere tra:
  • riferimento a variabile d’ambiente (ad esempio keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" })
  • riferimento a provider configurato (file o exec) con alias del provider + id
• La modalità a riferimento interattiva esegue una validazione preventiva rapida prima del salvataggio.
  • Riferimenti env: valida il nome della variabile e il valore non vuoto nell’ambiente di onboarding corrente.
  • Riferimenti provider: valida la configurazione del provider e risolve l’id richiesto.
  • Se la validazione preventiva fallisce, l’onboarding mostra l’errore e ti permette di riprovare.
• In modalità non interattiva, --secret-input-mode ref funziona solo con variabili d’ambiente.
  • Imposta la variabile d’ambiente del provider nell’ambiente del processo di onboarding.
  • I flag inline delle key (ad esempio --openai-api-key) richiedono che la variabile d’ambiente sia impostata; altrimenti l’onboarding fallisce immediatamente.
  • Per i provider personalizzati, la modalità non interattiva ref salva models.providers.<id>.apiKey come { source: "env", provider: "default", id: "CUSTOM_API_KEY" }.
  • In quel caso con provider personalizzato, --custom-api-key richiede che CUSTOM_API_KEY sia impostata; altrimenti l’onboarding fallisce immediatamente.
• Le credenziali di autenticazione del Gateway supportano scelte in chiaro e SecretRef nell’onboarding interattivo:
  • Modalità token: Genera/salva token in chiaro (predefinito) o Usa SecretRef.
  • Modalità password: in chiaro o SecretRef.
• Percorso SecretRef per token non interattivo: --gateway-token-ref-env <ENV_VAR>.
• I setup in chiaro esistenti continuano a funzionare senza modifiche.

Nota: Suggerimento per headless e server: completa l’OAuth su una macchina con un browser, poi copia ~/.openclaw/credentials/oauth.json (o $OPENCLAW_STATE_DIR/credentials/oauth.json) sull’host del gateway.

Output e meccanismi interni

Campi tipici in ~/.openclaw/openclaw.json:

• agents.defaults.workspace
• agents.defaults.model / models.providers (se scelto Minimax)
• tools.profile (l’onboarding locale lo imposta a "coding" quando non impostato; i valori espliciti esistenti vengono preservati)
• gateway.* (mode, bind, auth, tailscale)
• session.dmScope (l’onboarding locale lo imposta a per-channel-peer quando non impostato; i valori espliciti esistenti vengono preservati)
• channels.telegram.botToken, channels.discord.token, channels.signal.*, channels.imessage.*
• Allowlist dei canali (Slack, Discord, Matrix, Microsoft Teams) quando scegli di attivarle durante i prompt (i nomi vengono risolti in ID quando possibile)
• skills.install.nodeManager
• wizard.lastRunAt
• wizard.lastRunVersion
• wizard.lastRunCommit
• wizard.lastRunCommand
• wizard.lastRunMode

openclaw agents add scrive agents.list[] e opzionalmente bindings.

Le credenziali WhatsApp vanno sotto ~/.openclaw/credentials/whatsapp/<accountId>/. Le sessioni sono salvate sotto ~/.openclaw/agents/<agentId>/sessions/.

Nota: Alcuni canali vengono forniti come plugin. Quando selezionati durante l’onboarding, il wizard chiede di installare il plugin (npm o percorso locale) prima della configurazione del canale.

RPC del wizard del Gateway:

• wizard.start
• wizard.next
• wizard.cancel
• wizard.status

I client (app macOS e Control UI) possono renderizzare i passaggi senza reimplementare la logica di onboarding.

Comportamento del setup di Signal:

• Scarica l’asset della release appropriato
• Lo salva sotto ~/.openclaw/tools/signal-cli/<versione>/
• Scrive channels.signal.cliPath nella configurazione
• Le build JVM richiedono Java 21
• Le build native vengono usate quando disponibili
• Windows usa WSL2 e segue il flusso signal-cli di Linux all’interno di WSL

Documentazione correlata

• Hub dell’onboarding: Wizard di onboarding (CLI)
• Automazione e script: Automazione CLI
• Riferimento comandi: openclaw onboard