OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Guides

Riferimento per la configurazione della CLI

Questa pagina descrive dettagliatamente il comportamento, gli output e il funzionamento interno dell'onboarding. Per una procedura guidata, vedere Onboarding (CLI). Per il riferimento completo ai flag della CLI (ogni --flag, esempi non interattivi, comandi specifici dei provider), vedere openclaw onboard.

Funzioni della procedura guidata

La modalità locale (predefinita) guida attraverso:

  • Configurazione del modello e dell'autenticazione (Anthropic, OAuth dell'abbonamento OpenAI Code, xAI, OpenCode, endpoint personalizzati e altri flussi di autenticazione gestiti dai provider)
  • Posizione dello spazio di lavoro e file di bootstrap
  • Impostazioni del Gateway (porta, binding, autenticazione, Tailscale)
  • Canali e provider (Discord, Feishu, Google Chat, iMessage, Mattermost, Microsoft Teams, QQ Bot, Signal, Slack, Telegram, WhatsApp e altri canali inclusi o forniti tramite plugin)
  • Provider di ricerca web (facoltativo)
  • Installazione del daemon (LaunchAgent, unità utente systemd oppure attività pianificata nativa di Windows con ripiego sulla cartella Startup)
  • Controllo di integrità
  • Configurazione delle Skills

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

Dettagli del flusso locale

  • Rilevamento della configurazione esistente

    • Se esiste ~/.openclaw/openclaw.json, scegliere Mantieni i valori correnti, Rivedi e aggiorna oppure Reimposta prima della configurazione.
    • Eseguire nuovamente la procedura guidata non elimina nulla, a meno che non si scelga esplicitamente Reimposta (o si passi --reset).
    • Il valore predefinito di --reset della CLI è config+creds+sessions; usare --reset-scope full per rimuovere anche lo spazio di lavoro.
    • Se la configurazione non è valida o contiene chiavi obsolete, la procedura guidata si interrompe e richiede di eseguire openclaw doctor prima di continuare.
    • La reimpostazione sposta lo stato nel Cestino (senza mai eliminarlo direttamente) e offre i seguenti ambiti:
      • Solo configurazione
      • Configurazione + credenziali + sessioni
      • Reimpostazione completa (rimuove anche lo spazio di lavoro)

  • Modello e autenticazione

  • Spazio di lavoro

    • Valore predefinito ~/.openclaw/workspace (configurabile).
    • Crea i file dello spazio di lavoro necessari per il bootstrap della prima esecuzione.
    • Struttura dello spazio di lavoro: Spazio di lavoro dell'agente.

  • Gateway

    • Richiede porta, binding, modalità di autenticazione ed esposizione tramite Tailscale.
    • Consigliato: mantenere abilitata l'autenticazione tramite token anche per il loopback, affinché i client WS locali debbano autenticarsi.
    • In modalità token, la configurazione interattiva offre:
      • Genera/memorizza token in testo normale (impostazione predefinita)
      • Usa SecretRef (facoltativo)
    • In modalità password, la configurazione interattiva supporta anche la memorizzazione in testo normale o tramite SecretRef.
    • Percorso SecretRef del token non interattivo: --gateway-token-ref-env <ENV_VAR>.
      • Richiede una variabile di ambiente non vuota nell'ambiente del processo di onboarding.
      • Non può essere combinato con --gateway-token.
    • Disabilitare l'autenticazione solo se ogni processo locale è considerato completamente attendibile.
    • I binding non loopback richiedono comunque l'autenticazione.

  • Canali

    • WhatsApp: accesso facoltativo tramite codice QR
    • Telegram: token del bot
    • Discord: token del bot
    • Google Chat: JSON dell'account di servizio + destinatario del Webhook
    • Mattermost: token del bot + URL di base
    • Signal: installazione facoltativa di signal-cli + configurazione dell'account
    • iMessage: percorso della CLI imsg + accesso al database Messages; usare un wrapper SSH quando il Gateway viene eseguito al di fuori del Mac
    • Sicurezza dei messaggi diretti: l'impostazione predefinita è l'associazione. Il primo messaggio diretto invia un codice; approvarlo tramite openclaw pairing approve <channel> <code> oppure usare elenchi di elementi consentiti.

  • Ricerca web

    • Scegliere un provider (Brave, DuckDuckGo, Exa, Firecrawl, Gemini, Grok, Kimi, MiniMax Search, Ollama Web Search, Perplexity, SearXNG, Tavily) oppure saltare il passaggio.
    • Saltare questo passaggio con --skip-search; riconfigurarlo successivamente con openclaw configure --section web.

  • Installazione del daemon

    • macOS: LaunchAgent
      • Richiede una sessione utente con accesso effettuato; per un sistema headless, usare un LaunchDaemon personalizzato (non incluso).
    • Linux e Windows tramite WSL2: unità utente systemd
      • La procedura guidata tenta di eseguire loginctl enable-linger <user>, affinché il Gateway rimanga attivo dopo la disconnessione.
      • Potrebbe richiedere sudo (scrive /var/lib/systemd/linger); viene prima effettuato un tentativo senza sudo.
    • Windows nativo: prima l'attività pianificata
      • Se la creazione dell'attività viene negata, OpenClaw ripiega su un elemento di accesso nella cartella Startup per utente e avvia immediatamente il Gateway.
      • Le attività pianificate rimangono l'opzione preferita perché forniscono uno stato migliore del supervisore.
    • Selezione del runtime: Node è obbligatorio perché l'archivio canonico dello stato di runtime di OpenClaw usa node:sqlite.

  • Controllo di integrità

    • Avvia il Gateway (se necessario) ed esegue openclaw health.
    • openclaw status --deep aggiunge all'output di stato il controllo di integrità del Gateway attivo, inclusi i controlli dei canali quando supportati.

  • Skills

    • Legge le Skills disponibili e ne verifica i requisiti.
    • Consente di scegliere il gestore Node: npm, pnpm o bun.
    • Installa le dipendenze facoltative per le Skills incluse e attendibili quando il programma di installazione richiesto è disponibile.
    • Salta i programmi di installazione non disponibili di Homebrew, uv e Go, quindi raggruppa le Skills interessate fornendo istruzioni per la configurazione manuale. Eseguire openclaw doctor dopo aver installato i prerequisiti mancanti.

  • Completamento

    • Riepilogo e passaggi successivi, incluse le opzioni per le app iOS, Android e macOS.

    • Dettagli della modalità remota

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

    Impostazioni configurate:

    • URL del Gateway remoto (ws://... o wss://...)
    • Token, password o nessuna autenticazione, in conformità con la configurazione del Gateway remoto

  • Rilevamento (facoltativo)

    Se dns-sd (macOS) o avahi-browse (Linux) è disponibile, l'onboarding propone di cercare beacon del Gateway tramite Bonjour/mDNS prima di passare all'inserimento manuale dell'URL. Quando configurato, viene tentato anche il rilevamento DNS-SD su rete geografica. Documentazione: Rilevamento del Gateway, Bonjour.

  • Metodo di connessione

    Quando viene selezionato un beacon, scegliere WebSocket diretto o un tunnel SSH:

    • Diretto: si connette tramite wss:// e richiede di considerare attendibile l'impronta digitale TLS rilevata (associazione basata sulla fiducia al primo utilizzo; viene associata solo se accettata).
    • Tunnel SSH: mostra un comando ssh -N -L 18789:127.0.0.1:18789 <user>@<host> da eseguire prima, quindi si connette all'endpoint del tunnel locale.

  • Autenticazione

    Scegliere token (consigliato), password o nessuna autenticazione, quindi eventualmente memorizzare la credenziale come SecretRef anziché in testo normale.

    • Opzioni di autenticazione e modello

    Se un passaggio di configurazione del provider non riesce durante l'onboarding interattivo (ad esempio, un'opzione di riutilizzo della CLI senza un accesso locale), la procedura guidata mostra l'errore e torna alla selezione del provider anziché terminare. Le esecuzioni esplicite di --auth-choice continuano a interrompersi immediatamente per l'automazione.

    Chiave API Anthropic

    Usa ANTHROPIC_API_KEY se presente oppure richiede una chiave, quindi la salva per l'uso da parte del daemon.

    CLI Anthropic Claude

    Percorso locale preferito durante l'onboarding o la configurazione interattiva; riutilizza un accesso esistente della CLI Claude quando disponibile.

    Abbonamento OpenAI Code (OAuth)

    Flusso tramite browser; incollare code#state.

    In una nuova configurazione priva di un modello principale, imposta agents.defaults.model su openai/gpt-5.6-sol tramite il runtime Codex.

    Abbonamento OpenAI Code (associazione dispositivo)

    Flusso di associazione tramite browser con un codice dispositivo di breve durata.

    In una nuova configurazione priva di un modello principale, imposta agents.defaults.model su openai/gpt-5.6-sol tramite il runtime Codex.

    Chiave API OpenAI

    Usa OPENAI_API_KEY se presente oppure richiede una chiave, quindi memorizza la credenziale nei profili di autenticazione.

    In una nuova configurazione priva di un modello principale, imposta agents.defaults.model su openai/gpt-5.6; l'ID semplice del modello per l'API diretta viene risolto al livello Sol.

    L'aggiunta o la nuova autenticazione di OpenAI conserva l'eventuale modello principale esplicito esistente, incluso openai/gpt-5.5. Se l'account non espone GPT-5.6, selezionare esplicitamente openai/gpt-5.5; OpenClaw non effettua automaticamente il downgrade.

    OAuth xAI (Grok)

    Accesso tramite browser per gli account SuperGrok o X Premium idonei. Questo è il percorso xAI consigliato per la maggior parte degli utenti. OpenClaw memorizza il profilo di autenticazione risultante per i modelli Grok, Grok web_search, x_search e code_execution.

    Codice dispositivo xAI (Grok)

    Accesso tramite browser adatto agli ambienti remoti, con un breve codice anziché un callback localhost. Utilizzarlo da host SSH, Docker o VPS.

    Chiave API xAI (Grok)

    Richiede XAI_API_KEY e configura xAI come provider di modelli. Utilizzare questa opzione quando si desidera una chiave API di xAI Console anziché l'OAuth dell'abbonamento.

    OpenCode

    Richiede OPENCODE_API_KEY (o OPENCODE_ZEN_API_KEY) e consente di scegliere il catalogo Zen o Go (una chiave API copre entrambi). URL di configurazione: opencode.ai/auth.

    Chiave API (generica)

    Memorizza la chiave.

    Vercel AI Gateway

    Richiede AI_GATEWAY_API_KEY. Ulteriori dettagli: Vercel AI Gateway.

    Cloudflare AI Gateway

    Richiede l'ID account, l'ID del gateway e CLOUDFLARE_AI_GATEWAY_API_KEY. Ulteriori dettagli: Cloudflare AI Gateway.

    MiniMax

    La configurazione viene scritta automaticamente. Il valore predefinito per il servizio in hosting è MiniMax-M3; la configurazione con chiave API utilizza minimax/..., mentre quella OAuth utilizza minimax-portal/.... Ulteriori dettagli: MiniMax.

    StepFun

    La configurazione viene scritta automaticamente per StepFun standard o Step Plan sugli endpoint cinesi o globali. Attualmente la versione standard include step-3.5-flash, mentre Step Plan include anche step-3.5-flash-2603. Ulteriori dettagli: StepFun.

    Synthetic (compatibile con Anthropic)

    Richiede SYNTHETIC_API_KEY. Ulteriori dettagli: Synthetic.

    Ollama (modelli aperti cloud e locali)

    Richiede prima Cloud + Local, Cloud only o Local only. Cloud only utilizza OLLAMA_API_KEY con https://ollama.com. Le modalità basate su host richiedono l'URL di base (valore predefinito http://127.0.0.1:11434), rilevano i modelli disponibili e suggeriscono i valori predefiniti. Cloud + Local verifica inoltre se l'host Ollama ha effettuato l'accesso per l'accesso al cloud. Ulteriori dettagli: Ollama.

    Moonshot e Kimi Coding

    Le configurazioni di Moonshot (Kimi K2) e Kimi Coding vengono scritte automaticamente. Ulteriori dettagli: Moonshot AI (Kimi + Kimi Coding).

    Provider personalizzato

    Funziona con endpoint compatibili con OpenAI, OpenAI Responses e Anthropic.

    L'onboarding interattivo supporta le stesse opzioni di memorizzazione della chiave API degli altri flussi di chiavi API dei provider:

    • Incolla subito la chiave API (testo non crittografato)
    • Usa un riferimento al segreto (riferimento a variabile d'ambiente o a un provider configurato, con convalida preliminare)

    L'onboarding deduce il supporto delle immagini per gli ID comuni dei modelli di visione (GPT-4o/4.1/5.x, Claude 3/4, Gemini, Qwen-VL, LLaVA, Pixtral e simili) e pone la domanda solo quando il nome del modello è sconosciuto.

    Flag non interattivi:

    • --auth-choice custom-api-key
    • --custom-base-url
    • --custom-model-id
    • --custom-api-key (facoltativo; ripiega su CUSTOM_API_KEY)
    • --custom-provider-id (facoltativo)
    • --custom-compatibility <openai|openai-responses|anthropic> (facoltativo; valore predefinito openai)
    • --custom-image-input / --custom-text-input (facoltativo; sostituisce la capacità di input del modello dedotta)
    Salta

    Lascia l'autenticazione non configurata.

    Comportamento del modello:

    • Selezionare il modello predefinito tra le opzioni rilevate oppure inserire manualmente provider e modello.
    • Quando l'onboarding inizia dalla scelta dell'autenticazione di un provider, il selettore dei modelli preferisce automaticamente tale provider. Per Volcengine e BytePlus, la stessa preferenza corrisponde anche alle rispettive varianti del piano di coding (volcengine-plan/*, byteplus-plan/*).
    • Se il filtro per il provider preferito non producesse risultati, il selettore ripiega sull'intero catalogo anziché non mostrare alcun modello.
    • La procedura guidata esegue un controllo del modello e avvisa se il modello configurato è sconosciuto o privo di autenticazione.

    Percorsi delle credenziali e dei profili:

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

    Modalità di memorizzazione delle credenziali:

    • Il comportamento predefinito dell'onboarding salva le chiavi API come valori in testo non crittografato nei profili di autenticazione.
    • --secret-input-mode ref abilita la modalità di riferimento anziché la memorizzazione della chiave in testo non crittografato. Nella configurazione interattiva è possibile scegliere:
      • un riferimento a una variabile d'ambiente (ad esempio keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" })
      • un riferimento a un provider configurato (file o exec) con alias + ID del provider
    • La modalità di riferimento interattiva esegue una rapida convalida preliminare prima del salvataggio.
      • Riferimenti a variabili d'ambiente: convalida il nome della variabile e la presenza di un valore non vuoto nell'ambiente di onboarding corrente.
      • Riferimenti ai provider: convalida la configurazione del provider e risolve l'ID richiesto.
      • Se la convalida preliminare non riesce, l'onboarding mostra l'errore e consente di riprovare.
    • In modalità non interattiva, --secret-input-mode ref è supportato solo da una variabile d'ambiente.
      • Impostare la variabile d'ambiente del provider nell'ambiente del processo di onboarding.
      • I flag con chiave incorporata (ad esempio --openai-api-key) richiedono che tale variabile d'ambiente sia impostata; in caso contrario, l'onboarding non riesce immediatamente.
      • Per i provider personalizzati, la modalità non interattiva ref memorizza models.providers.<id>.apiKey come { source: "env", provider: "default", id: "CUSTOM_API_KEY" }.
      • In questo caso di provider personalizzato, --custom-api-key richiede che CUSTOM_API_KEY sia impostato; in caso contrario, l'onboarding non riesce immediatamente.
    • Le credenziali di autenticazione del Gateway supportano le opzioni testo non crittografato e SecretRef nella configurazione interattiva:
      • Modalità token: Genera/memorizza token in testo non crittografato (valore predefinito) oppure Usa SecretRef.
      • Modalità password: testo non crittografato o SecretRef.
    • Percorso SecretRef del token non interattivo: --gateway-token-ref-env &lt;ENV_VAR&gt;.
    • Le configurazioni esistenti in testo non crittografato continuano a funzionare senza modifiche.

    Output e dettagli interni

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

    • agents.defaults.workspace
    • agents.defaults.skipBootstrap quando viene passato --skip-bootstrap
    • 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à, binding, autenticazione, Tailscale)
    • session.dmScope (l'onboarding locale usa per impostazione predefinita per-channel-peer quando non è impostato; i valori espliciti esistenti vengono mantenuti)
    • channels.telegram.botToken, channels.discord.token, channels.matrix.*, channels.signal.*, channels.imessage.*
    • Elenchi di elementi consentiti dei canali (Discord, iMessage, Signal, Slack, Telegram, WhatsApp) quando si acconsente durante le richieste; Discord e Slack risolvono inoltre i nomi inseriti nei rispettivi ID
    • skills.install.nodeManager
      • Il flag setup --node-manager accetta npm, pnpm o bun.
      • La configurazione manuale può comunque impostare skills.install.nodeManager: "yarn" in seguito.
    • wizard.lastRunAt
    • wizard.lastRunVersion
    • wizard.lastRunCommit
    • wizard.lastRunCommand
    • wizard.lastRunMode
    • wizard.securityAcknowledgedAt

    openclaw agents add scrive agents.list[] e, facoltativamente, bindings.

    Le credenziali di WhatsApp vengono salvate in ~/.openclaw/credentials/whatsapp/<accountId>/. Le sessioni attive e le trascrizioni vengono memorizzate in ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite. La directory ~/.openclaw/agents/<agentId>/sessions/ viene utilizzata per gli input delle migrazioni precedenti e per gli artefatti di archivio/assistenza.

    Configurazione non interattiva

    --non-interactive richiede --accept-risk (conferma che gli agenti sono potenti e che l'accesso completo al sistema comporta rischi):

    bash
    openclaw onboard --non-interactive --accept-risk \  --auth-choice apiKey \  --anthropic-api-key "$ANTHROPIC_API_KEY"

    Riferimento completo dei flag ed esempi specifici per provider: openclaw onboard, Automazione CLI.

    RPC della procedura guidata del Gateway

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

    I client (app macOS e interfaccia di controllo) possono visualizzare i passaggi senza reimplementare la logica di onboarding.

    Comportamento della configurazione di Signal

    • Scarica l'artefatto di rilascio appropriato dalle release GitHub ufficiali di signal-cli (build nativa, solo Linux x86-64)
    • Sulle altre piattaforme (macOS, Linux non x64), esegue invece l'installazione tramite Homebrew
    • Memorizza l'installazione dell'artefatto di rilascio in ~/.openclaw/tools/signal-cli/<version>/
    • Scrive channels.signal.cliPath nella configurazione
    • Windows nativo non è ancora supportato; eseguire l'onboarding in WSL2 per ottenere il percorso di installazione Linux

    Documentazione correlata

    Was this useful?
    On this page

    On this page