Riferimento alla 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 di modello e autenticazione (OAuth per abbonamento OpenAI Code, CLI o chiave API Anthropic Claude, più opzioni MiniMax, GLM, Ollama, Moonshot, StepFun 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, Mattermost, Signal, iMessage e altri Plugin di canale inclusi)
• Installazione del daemon (LaunchAgent, unità utente systemd o Scheduled Task nativo di Windows con fallback alla cartella Startup)
• Controllo di integrità
• Configurazione di 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

Dettagli della modalità remota

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

Cosa imposti:

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

Opzioni di autenticazione e modello

Comportamento del modello:

• Scegli il modello predefinito dalle opzioni rilevate oppure inserisci provider e modello manualmente.
• L’onboarding del provider personalizzato deduce il supporto immagini per gli ID modello comuni e chiede solo quando il nome del modello è sconosciuto.
• Quando l’onboarding parte da una scelta di autenticazione del provider, il selettore di modello preferisce automaticamente quel provider. Per Volcengine e BytePlus, la stessa preferenza corrisponde anche alle rispettive varianti coding-plan (volcengine-plan/*, byteplus-plan/*).
• Se quel filtro del provider preferito risultasse vuoto, il selettore ripiega sul 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’autenticazione.

Percorsi di credenziali e profili:

• Profili di autenticazione (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 persiste le chiavi API come valori in testo semplice nei profili di autenticazione.
• --secret-input-mode ref abilita la modalità riferimento invece dell’archiviazione della chiave in testo semplice. Nella configurazione interattiva, puoi scegliere:
  • riferimento a variabile d’ambiente (per esempio keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" })
  • riferimento a provider configurato (file o exec) con alias provider + id
• La modalità riferimento interattiva esegue una rapida convalida preflight prima del salvataggio.
  • Riferimenti env: convalida il nome della variabile + valore non vuoto nell’ambiente di onboarding corrente.
  • Riferimenti provider: convalida la configurazione del provider e risolve l’id richiesto.
  • Se il preflight fallisce, l’onboarding mostra l’errore e ti consente di riprovare.
• In modalità non interattiva, --secret-input-mode ref è supportata solo da env.
  • Imposta la variabile env del provider nell’ambiente del processo di onboarding.
  • I flag di chiave inline (per esempio --openai-api-key) richiedono che quella variabile env sia impostata; altrimenti l’onboarding fallisce rapidamente.
  • Per provider personalizzati, la modalità non interattiva ref memorizza models.providers.<id>.apiKey come { source: "env", provider: "default", id: "CUSTOM_API_KEY" }.
  • In quel caso di provider personalizzato, --custom-api-key richiede che CUSTOM_API_KEY sia impostata; altrimenti l’onboarding fallisce rapidamente.
• Le credenziali di autenticazione del Gateway supportano scelte in testo semplice e SecretRef nella configurazione interattiva:
  • Modalità token: Genera/memorizza token in testo semplice (predefinito) o Usa SecretRef.
  • Modalità password: testo semplice o SecretRef.
• Percorso SecretRef token non interattivo: --gateway-token-ref-env <ENV_VAR>.
• Le configurazioni esistenti in testo semplice continuano a funzionare senza modifiche.

Output e componenti 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 conservati)
• gateway.* (modalità, bind, autenticazione, Tailscale)
• session.dmScope (l'onboarding locale lo imposta per impostazione predefinita su per-channel-peer quando non è impostato; i valori espliciti esistenti vengono conservati)
• channels.telegram.botToken, channels.discord.token, channels.matrix.*, channels.signal.*, channels.imessage.*
• Allowlist dei canali (Slack, Discord, Matrix, Microsoft Teams) quando aderisci 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 skills.install.nodeManager: "yarn" in seguito.
• 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/.

RPC della procedura guidata Gateway:

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

I client (app macOS e UI di controllo) possono eseguire il rendering dei passaggi senza reimplementare la logica di onboarding.

Comportamento di configurazione di Signal:

• Scarica l'asset di rilascio appropriato
• Lo archivia 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

• Hub di onboarding: Onboarding (CLI)
• Automazione e script: Automazione CLI
• Riferimento dei comandi: openclaw onboard