Vai al contenuto principale
Questo è il riferimento completo per openclaw onboard. Per una panoramica generale, consulta Onboarding (CLI).

​
Dettagli del flusso (modalità locale)

1

Rilevamento configurazione esistente

  • Se ~/.openclaw/openclaw.json esiste, scegli Mantieni i valori attuali, Rivedi e aggiorna oppure Reimposta prima della configurazione.
  • Rieseguire l’onboarding non cancella nulla, a meno che tu non scelga esplicitamente Reimposta (o passi --reset).
  • CLI --reset usa come valore predefinito config+creds+sessions; usa --reset-scope full per rimuovere anche il workspace.
  • Se la configurazione non è valida o contiene chiavi legacy, la procedura guidata si interrompe e chiede di eseguire openclaw doctor prima di continuare.
  • La reimpostazione usa trash (mai rm) e offre questi ambiti:
    • Solo configurazione
    • Configurazione + credenziali + sessioni
    • Reimpostazione completa (rimuove anche il workspace)
2

Modello/Auth

  • Chiave API Anthropic: usa ANTHROPIC_API_KEY se presente oppure richiede una chiave, poi la salva per l’uso del daemon.
  • Chiave API Anthropic: scelta preferita per l’assistente Anthropic in onboarding/configure.
  • Setup-token Anthropic: ancora disponibile in onboarding/configure, anche se OpenClaw ora preferisce riutilizzare Claude CLI quando disponibile.
  • Abbonamento OpenAI Code (Codex) (OAuth): flusso browser; incolla code#state.
    • Imposta agents.defaults.model su openai/gpt-5.5 tramite il runtime Codex quando il modello non è impostato o appartiene già alla famiglia OpenAI.
  • Abbonamento OpenAI Code (Codex) (associazione dispositivo): flusso di associazione browser con un codice dispositivo di breve durata.
    • Imposta agents.defaults.model su openai/gpt-5.5 tramite il runtime Codex quando il modello non è impostato o appartiene già alla famiglia OpenAI.
  • Chiave API OpenAI: usa OPENAI_API_KEY se presente oppure richiede una chiave, poi la archivia nei profili auth.
    • Imposta agents.defaults.model su openai/gpt-5.5 quando il modello non è impostato, è openai/* o usa riferimenti legacy a modelli Codex.
  • xAI (Grok) OAuth / chiave API: accede con xAI OAuth quando selezionato, oppure richiede XAI_API_KEY nel percorso con chiave API, e configura xAI come provider di modelli.
  • OpenCode: richiede OPENCODE_API_KEY (o OPENCODE_ZEN_API_KEY, ottienila su https://opencode.ai/auth) e ti consente di scegliere il catalogo Zen o Go.
  • Ollama: offre prima Cloud + Locale, Solo cloud o Solo locale. Cloud only richiede OLLAMA_API_KEY e usa https://ollama.com; le modalità basate su host richiedono l’URL base di Ollama, rilevano i modelli disponibili ed eseguono automaticamente il pull del modello locale selezionato quando necessario; Cloud + Local verifica anche se quell’host Ollama ha effettuato l’accesso per l’accesso cloud.
  • Maggiori dettagli: Ollama
  • Chiave API: archivia la chiave per te.
  • Vercel AI Gateway (proxy multi-modello): richiede AI_GATEWAY_API_KEY.
  • Maggiori dettagli: Vercel AI Gateway
  • Cloudflare AI Gateway: richiede ID account, ID Gateway e CLOUDFLARE_AI_GATEWAY_API_KEY.
  • Maggiori dettagli: Cloudflare AI Gateway
  • MiniMax: la configurazione viene scritta automaticamente; il valore predefinito hosted è MiniMax-M3. La configurazione con chiave API usa minimax/..., mentre la configurazione OAuth usa minimax-portal/....
  • Maggiori dettagli: MiniMax
  • StepFun: la configurazione viene scritta automaticamente per StepFun standard o Step Plan su endpoint cinesi o globali.
  • Standard attualmente include step-3.5-flash, e Step Plan include anche step-3.5-flash-2603.
  • Maggiori dettagli: StepFun
  • Synthetic (compatibile con Anthropic): richiede SYNTHETIC_API_KEY.
  • Maggiori dettagli: Synthetic
  • Moonshot (Kimi K2): la configurazione viene scritta automaticamente.
  • Kimi Coding: la configurazione viene scritta automaticamente.
  • Maggiori dettagli: Moonshot AI (Kimi + Kimi Coding)
  • Salta: nessuna auth ancora configurata.
  • Scegli un modello predefinito tra le opzioni rilevate (oppure inserisci manualmente provider/modello). Per la migliore qualità e un rischio inferiore di prompt injection, scegli il modello di ultima generazione più potente disponibile nel tuo stack di provider.
  • L’onboarding esegue un controllo del modello e avvisa se il modello configurato è sconosciuto o manca l’auth.
  • La modalità di archiviazione della chiave API usa come impostazione predefinita valori auth-profile in testo normale. Usa --secret-input-mode ref per archiviare invece riferimenti basati su env (ad esempio keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" }).
  • I profili auth si trovano in ~/.openclaw/agents/<agentId>/agent/auth-profiles.json (chiavi API + OAuth). ~/.openclaw/credentials/oauth.json è solo import legacy.
  • Maggiori dettagli: /concepts/oauth
Suggerimento per headless/server: completa OAuth su una macchina con browser, poi copia auth-profiles.json di quell’agente (ad esempio ~/.openclaw/agents/<agentId>/agent/auth-profiles.json, oppure il percorso corrispondente $OPENCLAW_STATE_DIR/...) sull’host del Gateway. credentials/oauth.json è solo una sorgente di import legacy.
3

Workspace

  • Valore predefinito ~/.openclaw/workspace (configurabile).
  • Popola i file del workspace necessari per il rituale di bootstrap dell’agente.
  • Layout completo del workspace + guida al backup: Workspace dell’agente
4

Gateway

  • Porta, bind, modalità auth, esposizione tailscale.
  • Raccomandazione auth: mantieni Token anche per loopback, così i client WS locali devono autenticarsi.
  • In modalità token, la configurazione interattiva offre:
    • Genera/archivia token in testo normale (predefinito)
    • Usa SecretRef (opt-in)
    • Quickstart riutilizza i SecretRef gateway.auth.token esistenti tra provider env, file ed exec per il probe di onboarding/bootstrap della dashboard.
    • Se quel SecretRef è configurato ma non può essere risolto, l’onboarding fallisce subito con un messaggio di correzione chiaro invece di degradare silenziosamente l’auth runtime.
  • In modalità password, la configurazione interattiva supporta anche l’archiviazione in testo normale o SecretRef.
  • Percorso SecretRef token non interattivo: --gateway-token-ref-env <ENV_VAR>.
    • Richiede una variabile env non vuota nell’ambiente del processo di onboarding.
    • Non può essere combinato con --gateway-token.
  • Disabilita auth solo se ti fidi completamente di ogni processo locale.
  • I bind non-loopback richiedono comunque auth.
5

Canali

  • WhatsApp: login QR opzionale.
  • Telegram: token bot.
  • Discord: token bot.
  • Google Chat: JSON account di servizio + audience webhook.
  • Mattermost (plugin): token bot + URL base.
  • Signal: installazione opzionale di signal-cli + configurazione account.
  • iMessage: percorso CLI imsg + accesso al DB Messaggi; usa un wrapper SSH quando il Gateway gira fuori dal Mac.
  • Sicurezza DM: il valore predefinito è l’associazione. Il primo DM invia un codice; approva con openclaw pairing approve <channel> <code> oppure usa allowlist.
6

Ricerca web

  • Scegli un provider supportato come Brave, DuckDuckGo, Exa, Firecrawl, Gemini, Grok, Kimi, MiniMax Search, Ollama Web Search, Perplexity, SearXNG o Tavily (oppure salta).
  • I provider basati su API possono usare variabili env o la configurazione esistente per una configurazione rapida; i provider senza chiave usano invece i prerequisiti specifici del provider.
  • Salta con --skip-search.
  • Configura in seguito: openclaw configure --section web.
7

Installazione daemon

  • macOS: LaunchAgent
    • Richiede una sessione utente con accesso effettuato; per headless, usa un LaunchDaemon personalizzato (non distribuito).
  • Linux (e Windows tramite WSL2): unità utente systemd
    • L’onboarding prova ad abilitare lingering tramite loginctl enable-linger <user> così il Gateway resta attivo dopo il logout.
    • Potrebbe richiedere sudo (scrive in /var/lib/systemd/linger); prova prima senza sudo.
  • Selezione runtime: Node (consigliato; richiesto per WhatsApp/Telegram). Bun è sconsigliato.
  • Se l’auth token richiede un token e gateway.auth.token è gestito da SecretRef, l’installazione del daemon lo valida ma non persiste i valori del token in testo normale risolti nei metadati dell’ambiente del servizio supervisor.
  • Se l’auth token richiede un token e il SecretRef token configurato non è risolto, l’installazione del daemon 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 daemon viene bloccata finché la modalità non viene impostata esplicitamente.
8

Controllo di integrità

  • Avvia il Gateway (se necessario) ed esegue openclaw health.
  • Suggerimento: openclaw status --deep aggiunge il probe di integrità live del gateway all’output di stato, inclusi i probe dei canali quando supportati (richiede un gateway raggiungibile).
9

Skills (consigliato)

  • Legge le skill disponibili e verifica i requisiti.
  • Ti consente di scegliere un gestore node: npm / pnpm (bun sconsigliato).
  • Installa dipendenze opzionali (alcune usano Homebrew su macOS).
10

Fine

  • Riepilogo + passaggi successivi, incluso il prompt Come vuoi far schiudere il tuo agente? per Terminale, Browser o più tardi.
Se non viene rilevata alcuna GUI, l’onboarding stampa istruzioni di port-forward SSH per la Control UI invece di aprire un browser. Se gli asset della Control UI mancano, l’onboarding prova a crearli; il fallback è pnpm ui:build (installa automaticamente le dipendenze UI).

​
Modalità non interattiva

Usa --non-interactive per automatizzare o scriptare l’onboarding: 
openclaw onboard --non-interactive \
  --mode local \
  --auth-choice apiKey \
  --anthropic-api-key "$ANTHROPIC_API_KEY" \
  --gateway-port 18789 \
  --gateway-bind loopback \
  --install-daemon \
  --daemon-runtime node \
  --skip-skills
Aggiungi --json per un riepilogo leggibile da macchina. SecretRef del token Gateway in modalità non interattiva: 
export OPENCLAW_GATEWAY_TOKEN="your-token"
openclaw onboard --non-interactive \
  --mode local \
  --auth-choice skip \
  --gateway-auth token \
  --gateway-token-ref-env OPENCLAW_GATEWAY_TOKEN
--gateway-token e --gateway-token-ref-env si escludono a vicenda.
--json non implica la modalità non interattiva. Usa --non-interactive (e --workspace) per gli script.
Esempi di comandi specifici per provider si trovano in Automazione CLI. Usa questa pagina di riferimento per la semantica dei flag e l’ordine dei passaggi.

​
Aggiungere agente (non interattivo)

openclaw agents add work \
  --workspace ~/.openclaw/workspace-work \
  --model openai/gpt-5.5 \
  --bind whatsapp:biz \
  --non-interactive \
  --json

​
RPC della procedura guidata del Gateway

Il Gateway espone il flusso di onboarding tramite RPC (wizard.start, wizard.next, wizard.cancel, wizard.status). I client (app macOS, Control UI) possono visualizzare i passaggi senza reimplementare la logica di onboarding.

​
Configurazione Signal (signal-cli)

L’onboarding può installare signal-cli dalle release GitHub:
  • Scarica l’asset di release appropriato.
  • Lo archivia in ~/.openclaw/tools/signal-cli/<version>/.
  • Scrive channels.signal.cliPath nella tua configurazione.
Note:
  • Le build JVM richiedono Java 21.
  • Le build native vengono usate quando disponibili.
  • Windows usa WSL2; l’installazione di signal-cli segue il flusso Linux dentro WSL.

​
Cosa scrive la procedura guidata

Campi tipici in ~/.openclaw/openclaw.json:
  • agents.defaults.workspace
  • agents.defaults.model / models.providers (se viene scelto Minimax)
  • tools.profile (l’onboarding locale usa per impostazione predefinita "coding" quando non è impostato; i valori espliciti esistenti vengono mantenuti)
  • gateway.* (modalità, bind, auth, tailscale)
  • session.dmScope (dettagli del comportamento: Riferimento setup CLI)
  • channels.telegram.botToken, channels.discord.token, channels.matrix.*, channels.signal.*, channels.imessage.*
  • Allowlist dei canali (Slack/Discord/Matrix/Microsoft Teams) quando le abiliti durante i prompt (i nomi vengono risolti in ID quando possibile).
  • skills.install.nodeManager
    • setup --node-manager accetta npm, pnpm o bun.
    • La configurazione manuale può ancora usare yarn impostando direttamente skills.install.nodeManager.
  • wizard.lastRunAt
  • wizard.lastRunVersion
  • wizard.lastRunCommit
  • wizard.lastRunCommand
  • wizard.lastRunMode
openclaw agents add scrive agents.list[] e bindings opzionali. Le credenziali WhatsApp vanno in ~/.openclaw/credentials/whatsapp/<accountId>/. Le sessioni sono archiviate in ~/.openclaw/agents/<agentId>/sessions/. Alcuni canali vengono distribuiti come Plugin. Quando ne scegli uno durante il setup, l’onboarding chiederà di installarlo (npm o un percorso locale) prima che possa essere configurato.

​
Documentazione correlata