English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiفارسیไทย
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this pageOpen in PerplexityAsk questions about this page

Technical reference

Riferimento per l'onboarding

Questa è la reference completa per openclaw onboard. Per una panoramica di alto livello, consulta Onboarding (CLI).

Dettagli del flusso (modalità locale)

  • Rilevamento della configurazione esistente

    • Se ~/.openclaw/openclaw.json esiste, scegli Mantieni i valori correnti, Rivedi e aggiorna oppure Reimposta prima della configurazione.
    • Rieseguire l'onboarding non cancella nulla a meno che tu non scelga esplicitamente Reset (o passi --reset).
    • --reset della CLI usa come default 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 arresta e ti chiede di eseguire openclaw doctor prima di continuare.
    • Reset usa trash (mai rm) e offre questi ambiti:
      • Solo configurazione
      • Configurazione + credenziali + sessioni
      • Reset completo (rimuove anche il workspace)

  • Modello/Auth

    • Chiave API Anthropic: usa ANTHROPIC_API_KEY se presente oppure richiede una chiave, quindi la salva per l'uso del daemon.
    • Chiave API Anthropic: scelta preferita dell'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 il 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, quindi la archivia nei profili auth.
      • Imposta agents.defaults.model su openai/gpt-5.5 quando il modello non è impostato, è openai/* o openai-codex/*.
    • Chiave API xAI (Grok): richiede XAI_API_KEY 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 + Local, 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 Account ID, Gateway ID e CLOUDFLARE_AI_GATEWAY_API_KEY.
    • Maggiori dettagli: Cloudflare AI Gateway
    • MiniMax: la configurazione viene scritta automaticamente; il default hosted è MiniMax-M2.7. 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 sugli endpoint Cina 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 configurata per ora.
    • 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 più potente di ultima generazione 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 default valori auth-profile in chiaro. Usa --secret-input-mode ref per archiviare invece riferimenti basati su env (per 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

  • Workspace

    • Default ~/.openclaw/workspace (configurabile).
    • Prepara i file del workspace necessari per il rituale di bootstrap dell'agente.
    • Layout completo del workspace + guida al backup: Workspace agente

  • 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 chiaro (default)
      • Usa SecretRef (opt-in)
      • Quickstart riutilizza 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 in anticipo con un messaggio di correzione chiaro invece di degradare silenziosamente l'auth di runtime.
    • In modalità password, la configurazione interattiva supporta anche l'archiviazione in chiaro o SecretRef.
    • Percorso SecretRef token non interattivo: --gateway-token-ref-env &lt;ENV_VAR&gt;.
      • Richiede una variabile env non vuota nell'ambiente del processo di onboarding.
      • Non può essere combinato con --gateway-token.
    • Disabilita l'auth solo se ti fidi completamente di ogni processo locale.
    • I bind non-loopback richiedono comunque auth.

  • 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 default è l'associazione. Il primo DM invia un codice; approva tramite openclaw pairing approve <channel> <code> oppure usa allowlist.

  • 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.

  • Installazione daemon

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

  • Controllo di integrità

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

  • Skills (consigliato)

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

  • Fine

    • Riepilogo + prossimi passaggi, incluso il prompt Come vuoi far schiudere il tuo agente? per Terminale, Browser o in seguito.

    • Modalità non interattiva

    Usa --non-interactive per automatizzare o creare script per l'onboarding:

    bash
    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 token Gateway in modalità non interattiva:

    bash
    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.

    Gli esempi di comandi specifici per provider si trovano in Automazione CLI. Usa questa pagina di reference per la semantica dei flag e l'ordine dei passaggi.

    Aggiungere agente (non interattivo)

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

    RPC della procedura guidata 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 renderizzare i passaggi senza reimplementare la logica di onboarding.

    Configurazione Signal (signal-cli)

    L'onboarding può installare signal-cli dalle release GitHub:

    • Scarica l'asset della 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 preservati)
    • gateway.* (mode, bind, auth, tailscale)
    • session.dmScope (dettagli sul comportamento: Riferimento alla configurazione della CLI)
    • channels.telegram.botToken, channels.discord.token, channels.matrix.*, channels.signal.*, channels.imessage.*
    • Elenchi consentiti dei canali (Slack/Discord/Matrix/Microsoft Teams) quando aderisci 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 la configurazione, l’onboarding chiederà di installarlo (npm o un percorso locale) prima che possa essere configurato.

    Documentazione correlata

    Was this useful?