Riferimento alla configurazione della CLI

Questa pagina è il riferimento completo per openclaw onboard. Per la guida breve, consulta 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, più opzioni MiniMax, GLM, Ollama, Moonshot, StepFun e AI Gateway)
• Posizione dell'area di lavoro 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 demone (LaunchAgent, unità utente systemd o attività pianificata nativa di Windows con fallback alla cartella Esecuzione automatica)
• 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 manualmente provider e modello.
• L'onboarding del provider personalizzato deduce il supporto per 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 loro varianti di piano coding (volcengine-plan/*, byteplus-plan/*).
• Se quel filtro per provider preferito fosse 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 di onboarding predefinito persiste le chiavi API come valori in testo normale nei profili di autenticazione.
• --secret-input-mode ref abilita la modalità di riferimento invece dell'archiviazione della chiave in testo normale. 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à di riferimento interattiva esegue una rapida validazione preliminare prima del salvataggio.
  • Riferimenti env: valida il nome della variabile + valore non vuoto nell'ambiente di onboarding corrente.
  • Riferimenti provider: valida la configurazione del provider e risolve l'id richiesto.
  • Se la validazione preliminare non riesce, l'onboarding mostra l'errore e ti consente di riprovare.
• In modalità non interattiva, --secret-input-mode ref è supportato solo da env.
  • Imposta la variabile d'ambiente del provider nell'ambiente del processo di onboarding.
  • I flag di chiave inline (ad esempio --openai-api-key) richiedono che quella variabile d'ambiente sia impostata; altrimenti l'onboarding fallisce rapidamente.
  • Per provider personalizzati, la modalità non interattiva ref archivia 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 normale e SecretRef nella configurazione interattiva:
  • Modalità token: Genera/archivia token in testo normale (predefinita) o Usa SecretRef.
  • Modalità password: testo normale o SecretRef.
• Percorso SecretRef token non interattivo: --gateway-token-ref-env <ENV_VAR>.
• Le configurazioni esistenti in testo normale 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 preservati)
• gateway.* (modalità, bind, autenticazione, tailscale)
• session.dmScope (l'onboarding locale imposta questo valore predefinito su per-channel-peer quando non è impostato; i valori espliciti esistenti vengono preservati)
• channels.telegram.botToken, channels.discord.token, channels.matrix.*, channels.signal.*, channels.imessage.*
• Allowlist dei canali (Slack, Discord, Matrix, Microsoft Teams) quando accetti 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
• wizard.securityAcknowledgedAt

openclaw agents add scrive agents.list[] e bindings facoltativi.

Le credenziali WhatsApp vanno in ~/.openclaw/credentials/whatsapp/<accountId>/. Le sessioni sono archiviate in ~/.openclaw/agents/<agentId>/sessions/.

RPC della procedura guidata del Gateway:

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

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

Comportamento di configurazione di Signal:

• Scarica l'asset di release 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 signal-cli Linux dentro WSL

Documentazione correlata

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