Vai al contenuto principale

​
Riferimento per la configurazione della CLI

Questa pagina è il riferimento completo per openclaw onboard. Per la guida breve, vedi Onboarding (CLI).

​
Cosa fa la procedura guidata

La modalità locale (predefinita) ti guida attraverso:
  • Configurazione del modello e dell’autenticazione (OAuth dell’abbonamento OpenAI Code, Anthropic Claude CLI o chiave API, oltre alle opzioni MiniMax, GLM, Ollama, Moonshot, StepFun e AI Gateway)
  • Posizione del workspace e file bootstrap
  • Impostazioni del gateway (porta, bind, auth, tailscale)
  • Canali e provider (Telegram, WhatsApp, Discord, Google Chat, Mattermost, Signal, BlueBubbles e altri plugin di canale inclusi)
  • Installazione del daemon (LaunchAgent, unità utente systemd o attività pianificata nativa di Windows con fallback nella cartella Startup)
  • Controllo di integrità
  • Configurazione delle Skills
La modalità remota configura questa macchina per connettersi a un gateway altrove. Non installa né modifica nulla sull’host remoto.

​
Dettagli del flusso locale

1

Rilevamento della configurazione esistente

  • Se esiste ~/.openclaw/openclaw.json, scegli Mantieni, Modifica o Reimposta.
  • Rieseguire la procedura guidata non cancella nulla a meno che tu non scelga esplicitamente Reimposta (o passi --reset).
  • La CLI --reset usa come impostazione predefinita 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 ti chiede di eseguire openclaw doctor prima di continuare.
  • La reimpostazione usa trash e offre questi ambiti:
    • Solo configurazione
    • Configurazione + credenziali + sessioni
    • Reimpostazione completa (rimuove anche il workspace)
2

Modello e autenticazione

3

Workspace

  • Predefinito ~/.openclaw/workspace (configurabile).
  • Inizializza i file del workspace necessari per il rituale bootstrap della prima esecuzione.
  • Layout del workspace: Workspace dell’agente.
4

Gateway

  • Chiede porta, bind, modalità auth ed esposizione tailscale.
  • Consigliato: lasciare abilitata l’autenticazione tramite token anche per loopback, così i client WS locali devono autenticarsi.
  • In modalità token, la configurazione interattiva offre:
    • Genera/memorizza token in chiaro (predefinito)
    • Usa SecretRef (facoltativo)
  • In modalità password, la configurazione interattiva supporta anche l’archiviazione in chiaro o SecretRef.
  • Percorso SecretRef del 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’auth solo se ti fidi completamente di ogni processo locale.
  • I bind non loopback richiedono comunque l’auth.
5

Canali

  • WhatsApp: login QR facoltativo
  • Telegram: token bot
  • Discord: token bot
  • Google Chat: JSON dell’account di servizio + audience del webhook
  • Mattermost: token bot + URL di base
  • Signal: installazione facoltativa di signal-cli + configurazione dell’account
  • BlueBubbles: consigliato per iMessage; URL del server + password + webhook
  • iMessage: percorso legacy della CLI imsg + accesso al DB
  • Sicurezza dei DM: il valore predefinito è l’associazione. Il primo DM invia un codice; approvalo con openclaw pairing approve <channel> <code> oppure usa allowlist.
6

Installazione del daemon

  • macOS: LaunchAgent
    • Richiede una sessione utente con accesso effettuato; per ambienti headless, usa un LaunchDaemon personalizzato (non fornito).
  • Linux e Windows tramite WSL2: unità utente systemd
    • La procedura guidata prova a eseguire 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.
  • Windows nativo: prima Attività pianificata
    • Se la creazione dell’attività viene negata, OpenClaw usa come fallback un elemento di accesso per utente nella cartella Startup e avvia immediatamente il gateway.
    • Le Attività pianificate restano preferibili perché forniscono uno stato del supervisore migliore.
  • Selezione del runtime: Node (consigliato; richiesto per WhatsApp e Telegram). Bun non è consigliato.
7

Controllo di integrità

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

Skills

  • Legge le Skills disponibili e controlla i requisiti.
  • Ti permette di scegliere il gestore Node: npm, pnpm o bun.
  • Installa dipendenze facoltative (alcune usano Homebrew su macOS).
9

Fine

  • Riepilogo e passaggi successivi, incluse le opzioni per le app iOS, Android e macOS.
Se non viene rilevata alcuna GUI, la procedura guidata stampa le istruzioni per il port forwarding SSH per la Control UI invece di aprire un browser. Se le risorse della Control UI non sono presenti, la procedura guidata prova a compilarle; 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.
La modalità remota non installa né modifica nulla sull’host remoto.
Cosa configuri:
  • URL del gateway remoto (ws://...)
  • Token se è richiesta l’auth del gateway remoto (consigliato)
  • Se il gateway è solo loopback, usa un tunnel SSH o una tailnet.
  • Suggerimenti per il rilevamento:
    • macOS: Bonjour (dns-sd)
    • Linux: Avahi (avahi-browse)

​
Opzioni di autenticazione e modello

Usa ANTHROPIC_API_KEY se presente oppure chiede una chiave, poi la salva per l’uso da parte del daemon.
Riutilizza un login locale di Claude CLI sull’host del gateway e cambia la selezione del modello a un riferimento canonico claude-cli/claude-*.Questo è un percorso di fallback locale disponibile in openclaw onboard e openclaw configure. Per la produzione, preferisci una chiave API Anthropic.
  • macOS: controlla l’elemento del Portachiavi “Claude Code-credentials”
  • Linux e Windows: riutilizza ~/.claude/.credentials.json se presente
Su macOS, scegli “Always Allow” in modo che gli avvii tramite launchd non vengano bloccati.
Se esiste ~/.codex/auth.json, la procedura guidata può riutilizzarlo. Le credenziali di Codex CLI riutilizzate restano gestite da Codex CLI; alla scadenza OpenClaw rilegge prima quella sorgente e, quando il provider può aggiornarla, scrive la credenziale aggiornata di nuovo nell’archiviazione di Codex invece di assumerne direttamente il controllo.
Flusso nel browser; incolla code#state.Imposta agents.defaults.model su openai-codex/gpt-5.4 quando il modello non è impostato oppure è openai/*.
Usa OPENAI_API_KEY se presente oppure chiede una chiave, poi archivia la credenziale nei profili auth.Imposta agents.defaults.model su openai/gpt-5.4 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 configurazione: opencode.ai/auth.
Memorizza la chiave per te.
Chiede AI_GATEWAY_API_KEY. Più dettagli: Vercel AI Gateway.
Chiede ID account, ID gateway e CLOUDFLARE_AI_GATEWAY_API_KEY. Più dettagli: Cloudflare AI Gateway.
La configurazione viene scritta automaticamente. Il valore hosted predefinito è MiniMax-M2.7; la configurazione con chiave API usa minimax/..., mentre la configurazione OAuth usa minimax-portal/.... Più dettagli: MiniMax.
La configurazione viene scritta automaticamente per StepFun standard o Step Plan su endpoint Cina o globali. Standard attualmente include step-3.5-flash, e Step Plan include anche step-3.5-flash-2603. Più dettagli: StepFun.
Chiede SYNTHETIC_API_KEY. Più dettagli: Synthetic.
Chiede l’URL di base (predefinito http://127.0.0.1:11434), poi offre modalità Cloud + Locale o Locale. Rileva i modelli disponibili e suggerisce quelli predefiniti. Più dettagli: Ollama.
Le configurazioni di Moonshot (Kimi K2) e Kimi Coding vengono scritte automaticamente. Più dettagli: Moonshot AI (Kimi + Kimi Coding).
Funziona con endpoint compatibili con OpenAI e compatibili con Anthropic.L’onboarding interattivo supporta le stesse scelte di archiviazione della chiave API degli altri flussi con chiave API del provider:
  • Incolla ora la chiave API (in chiaro)
  • Usa riferimento segreto (riferimento env o provider configurato, con validazione preliminare)
Flag non interattivi:
  • --auth-choice custom-api-key
  • --custom-base-url
  • --custom-model-id
  • --custom-api-key (facoltativo; usa CUSTOM_API_KEY come fallback)
  • --custom-provider-id (facoltativo)
  • --custom-compatibility <openai|anthropic> (facoltativo; predefinito openai)
Lascia l’auth non configurata.
Comportamento del modello:
  • Scegli il modello predefinito tra le opzioni rilevate, oppure inserisci manualmente provider e modello.
  • Quando l’onboarding parte da una scelta di auth del provider, il selettore dei modelli preferisce automaticamente quel provider. Per Volcengine e BytePlus, la stessa preferenza corrisponde anche alle rispettive varianti del piano coding (volcengine-plan/*, byteplus-plan/*).
  • Se quel filtro del provider preferito sarebbe vuoto, il selettore torna al catalogo completo invece di non mostrare alcun modello.
  • La procedura guidata esegue un controllo del modello e avvisa se il modello configurato è sconosciuto o manca l’auth.
Percorsi di credenziali e profili:
  • Profili auth (chiavi API + OAuth): ~/.openclaw/agents/<agentId>/agent/auth-profiles.json
  • Importazione OAuth legacy: ~/.openclaw/credentials/oauth.json
Modalità di archiviazione delle credenziali:
  • Il comportamento predefinito dell’onboarding salva le chiavi API come valori in chiaro nei profili auth.
  • --secret-input-mode ref abilita la modalità riferimento invece dell’archiviazione della chiave in chiaro. Nella configurazione interattiva, puoi scegliere:
    • 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à riferimento interattiva esegue una rapida validazione preliminare prima del salvataggio.
    • Riferimenti env: valida il nome della variabile e il valore non vuoto nell’ambiente corrente di onboarding.
    • Riferimenti provider: valida la configurazione del provider e risolve l’id richiesto.
    • Se la validazione preliminare fallisce, l’onboarding mostra l’errore e ti consente di riprovare.
  • In modalità non interattiva, --secret-input-mode ref è supportato solo con env.
    • Imposta la variabile d’ambiente del provider nell’ambiente del processo di onboarding.
    • I flag con chiavi inline (ad esempio --openai-api-key) richiedono che la variabile env sia impostata; in caso contrario l’onboarding fallisce subito.
    • Per i provider personalizzati, la modalità non interattiva ref memorizza models.providers.<id>.apiKey come { source: "env", provider: "default", id: "CUSTOM_API_KEY" }.
    • In quel caso del provider personalizzato, --custom-api-key richiede che CUSTOM_API_KEY sia impostata; in caso contrario l’onboarding fallisce subito.
  • Le credenziali auth del gateway supportano scelte in chiaro e SecretRef nella configurazione interattiva:
    • Modalità token: Genera/memorizza token in chiaro (predefinito) oppure Usa SecretRef.
    • Modalità password: in chiaro oppure SecretRef.
  • Percorso SecretRef del token non interattivo: --gateway-token-ref-env <ENV_VAR>.
  • Le configurazioni in chiaro esistenti continuano a funzionare senza modifiche.
Suggerimento per ambienti headless e server: completa OAuth su una macchina con browser, poi copia l’auth-profiles.json di quell’agente (ad esempio ~/.openclaw/agents/<agentId>/agent/auth-profiles.json, oppure il corrispondente percorso $OPENCLAW_STATE_DIR/...) sull’host del gateway. credentials/oauth.json è solo una sorgente di importazione legacy.

​
Output e aspetti interni

Campi tipici in ~/.openclaw/openclaw.json:
  • agents.defaults.workspace
  • agents.defaults.model / models.providers (se è stato scelto Minimax)
  • tools.profile (l’onboarding locale usa come predefinito "coding" quando non impostato; i valori espliciti esistenti vengono mantenuti)
  • gateway.* (mode, bind, auth, tailscale)
  • session.dmScope (l’onboarding locale imposta questo valore su per-channel-peer quando non impostato; i valori espliciti esistenti vengono mantenuti)
  • channels.telegram.botToken, channels.discord.token, channels.matrix.*, 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
    • Il flag setup --node-manager accetta npm, pnpm o bun.
    • La configurazione manuale può comunque impostare successivamente skills.install.nodeManager: "yarn".
  • wizard.lastRunAt
  • wizard.lastRunVersion
  • wizard.lastRunCommit
  • wizard.lastRunCommand
  • wizard.lastRunMode
openclaw agents add scrive agents.list[] e bindings facoltativi. Le credenziali WhatsApp vanno in ~/.openclaw/credentials/whatsapp/<accountId>/. Le sessioni sono memorizzate in ~/.openclaw/agents/<agentId>/sessions/.
Alcuni canali sono distribuiti come plugin. Quando vengono selezionati durante la configurazione, la procedura guidata chiede di installare il plugin (npm o percorso locale) prima della configurazione del canale.
RPC della procedura guidata del gateway:
  • wizard.start
  • wizard.next
  • wizard.cancel
  • wizard.status
I client (app macOS e Control UI) possono visualizzare i passaggi senza reimplementare la logica di onboarding. Comportamento della configurazione di Signal:
  • Scarica la release asset appropriata
  • La memorizza in ~/.openclaw/tools/signal-cli/<version>/
  • 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 Linux di signal-cli all’interno di WSL

​
Documentazione correlata