Setup

Nota: Se stai configurando per la prima volta, parti da Per iniziare. Per i dettagli sul wizard, consulta Wizard di onboarding.

Ultimo aggiornamento: 2026-01-01

TL;DR

• Le personalizzazioni vivono fuori dal repository: ~/.openclaw/workspace (workspace) + ~/.openclaw/openclaw.json (configurazione).
• Workflow stabile: installa l’app macOS; lascia che gestisca il Gateway integrato.
• Workflow bleeding edge: avvia il Gateway manualmente con pnpm gateway:watch, poi collega l’app macOS in modalità Locale.

Prerequisiti (da sorgente)

• Node >=22
• pnpm
• Docker (opzionale; solo per setup containerizzato/e2e — vedi Docker)

Strategia di personalizzazione (per aggiornare senza problemi)

Se vuoi “100% su misura per me” e aggiornamenti semplici, tieni le personalizzazioni in:

• Configurazione: ~/.openclaw/openclaw.json (JSON/JSON5)
• Workspace: ~/.openclaw/workspace (skill, prompt, memorie; rendilo un repository git privato)

Inizializzazione una tantum:

openclaw setup

Dall’interno di questo repository, usa l’entry point CLI locale:

openclaw setup

Se non hai ancora un’installazione globale, lancia pnpm openclaw setup.

Avviare il Gateway da questo repository

Dopo pnpm build, puoi eseguire direttamente la CLI pacchettizzata:

node openclaw.mjs gateway --port 18789 --verbose

Workflow stabile (prima l’app macOS)

1. Installa e avvia OpenClaw.app (barra dei menu).
2. Completa la checklist di onboarding/permessi (prompt TCC).
3. Assicurati che il Gateway sia in modalità Locale e in esecuzione (l’app lo gestisce).
4. Collega le superfici (esempio: WhatsApp):

openclaw channels login

5. Verifica di funzionamento:

openclaw health

Se l’onboarding non è disponibile nella tua build:

• Lancia openclaw setup, poi openclaw channels login, infine avvia il Gateway manualmente (openclaw gateway).

Workflow bleeding edge (Gateway in un terminale)

Obiettivo: lavorare sul Gateway TypeScript, ottenere l’hot reload e mantenere la UI dell’app macOS collegata.

0) (Opzionale) Eseguire anche l’app macOS da sorgente

Se vuoi anche l’app macOS sulla bleeding edge:

./scripts/restart-mac.sh

1) Avvia il Gateway di sviluppo

pnpm install
pnpm gateway:watch

gateway:watch esegue il gateway in modalità watch e ricarica automaticamente quando il TypeScript cambia.

2) Punta l’app macOS al Gateway in esecuzione

In OpenClaw.app:

• Modalità di connessione: Locale L’app si collegherà al gateway in esecuzione sulla porta configurata.

3) Verifica

• Lo stato del Gateway nell’app dovrebbe indicare “Using existing gateway …”
• Oppure tramite CLI:

openclaw health

Errori comuni

• Porta sbagliata: Il WS del Gateway di default è ws://127.0.0.1:18789; tieni app e CLI sulla stessa porta.
• Dove si trova lo stato:
  • Credenziali: ~/.openclaw/credentials/
  • Sessioni: ~/.openclaw/agents/<agentId>/sessions/
  • Log: /tmp/openclaw/

Mappa dello storage delle credenziali

Usa questa mappa per il debug dell’autenticazione o per decidere cosa includere nei backup:

• WhatsApp: ~/.openclaw/credentials/whatsapp/<accountId>/creds.json
• Token bot Telegram: config/env oppure channels.telegram.tokenFile (solo file regolari; i symlink vengono rifiutati)
• Token bot Discord: config/env oppure SecretRef (provider env/file/exec)
• Token Slack: config/env (channels.slack.*)
• Allowlist di pairing:
  • ~/.openclaw/credentials/<channel>-allowFrom.json (account predefinito)
  • ~/.openclaw/credentials/<channel>-<accountId>-allowFrom.json (account non predefiniti)
• Profili di autenticazione dei modelli: ~/.openclaw/agents/<agentId>/agent/auth-profiles.json
• Payload dei secret su file (opzionale): ~/.openclaw/secrets.json
• Import OAuth legacy: ~/.openclaw/credentials/oauth.json Maggiori dettagli: Sicurezza.

Aggiornamento (senza compromettere il tuo setup)

• Tieni ~/.openclaw/workspace e ~/.openclaw/ come “roba tua”; non mettere prompt o configurazioni personali nel repository openclaw.
• Aggiornamento del sorgente: git pull + pnpm install (quando il lockfile cambia) + continua a usare pnpm gateway:watch.

Linux (servizio utente systemd)

Le installazioni Linux usano un servizio utente systemd. Di default, systemd ferma i servizi utente al logout/idle, il che termina il Gateway. L’onboarding tenta di abilitare il lingering automaticamente (potrebbe richiedere sudo). Se risulta ancora disattivato, lancia:

sudo loginctl enable-linger $USER

Per server sempre attivi o multi-utente, considera un servizio di sistema invece di un servizio utente (non richiede lingering). Consulta il Runbook del Gateway per le note su systemd.

Documentazione correlata

• Runbook del Gateway (flag, supervisione, porte)
• Configurazione del Gateway (schema del config ed esempi)
• Discord e Telegram (reply tag e impostazioni replyToMode)
• Setup dell’assistente OpenClaw
• App macOS (ciclo di vita del gateway)