Vai al contenuto principale
Se stai configurando per la prima volta, inizia da Per iniziare. Per i dettagli sull’onboarding, consulta Onboarding (CLI).

​
TL;DR

Scegli un flusso di configurazione in base alla frequenza con cui vuoi ricevere aggiornamenti e al fatto che tu voglia eseguire personalmente il Gateway:
  • La personalizzazione vive fuori dal repo: tieni la configurazione e l’area di lavoro in ~/.openclaw/openclaw.json e ~/.openclaw/workspace/ in modo che gli aggiornamenti del repo non le tocchino.
  • Flusso stabile (consigliato per la maggior parte degli utenti): installa l’app macOS e lascia che esegua il Gateway incluso.
  • Flusso bleeding edge (dev): esegui personalmente il Gateway tramite pnpm gateway:watch, poi lascia che l’app macOS si colleghi in modalità Local.

​
Prerequisiti (da sorgente)

  • Node 24 consigliato (Node 22 LTS, attualmente 22.19+, ancora supportato)
  • pnpm è richiesto per i checkout da sorgente. OpenClaw carica i plugin inclusi dai pacchetti workspace pnpm extensions/* in modalità dev, quindi npm install nella root non prepara l’intero albero sorgente.
  • Docker (opzionale; solo per configurazione/e2e containerizzata - vedi Docker)

​
Strategia di personalizzazione (così gli aggiornamenti non fanno danni)

Se vuoi un’esperienza “100% su misura per me” e aggiornamenti facili, tieni la tua personalizzazione in:
  • Configurazione: ~/.openclaw/openclaw.json (simile a JSON/JSON5)
  • Area di lavoro: ~/.openclaw/workspace (skills, prompt, memorie; rendila un repo git privato)
Esegui il bootstrap una sola volta: 
openclaw setup
Dall’interno di questo repo, usa l’entrypoint CLI locale: 
openclaw setup
Se non hai ancora un’installazione globale, eseguilo tramite pnpm openclaw setup.

​
Eseguire il Gateway da questo repo

Dopo pnpm build, puoi eseguire direttamente la CLI pacchettizzata: 
node openclaw.mjs gateway --port 18789 --verbose

​
Flusso 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 Local e in esecuzione (l’app lo gestisce).
  4. Collega le superfici (esempio: WhatsApp):
openclaw channels login
  1. Controllo rapido:
openclaw health
Se l’onboarding non è disponibile nella tua build:
  • Esegui openclaw setup, poi openclaw channels login, quindi avvia manualmente il Gateway (openclaw gateway).

​
Flusso bleeding edge (Gateway in un terminale)

Obiettivo: lavorare sul Gateway TypeScript, ottenere il ricaricamento a caldo, mantenere collegata l’interfaccia dell’app macOS.

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

Se vuoi anche l’app macOS sulla bleeding edge: 
./scripts/restart-mac.sh

​
1) Avviare il Gateway di sviluppo

pnpm install
# Solo alla prima esecuzione (o dopo aver reimpostato la configurazione/area di lavoro locale di OpenClaw)
pnpm openclaw setup
pnpm gateway:watch
gateway:watch avvia o riavvia il processo watch del Gateway in una sessione tmux con nome e si collega automaticamente dai terminali interattivi. Le shell non interattive restano scollegate e stampano tmux attach -t openclaw-gateway-watch-main; usa OPENCLAW_GATEWAY_WATCH_ATTACH=0 pnpm gateway:watch per mantenere scollegata un’esecuzione interattiva, oppure pnpm gateway:watch:raw per la modalità watch in primo piano. Il watcher ricarica in caso di modifiche rilevanti a sorgenti, configurazione e metadati dei plugin inclusi. Se il Gateway osservato esce durante l’avvio, gateway:watch esegue openclaw doctor --fix --non-interactive una volta e riprova; imposta OPENCLAW_GATEWAY_WATCH_AUTO_DOCTOR=0 per disabilitare questo passaggio di riparazione solo dev. pnpm openclaw setup è il passaggio una tantum di inizializzazione di configurazione/area di lavoro locale per un checkout nuovo. pnpm gateway:watch non ricostruisce dist/control-ui, quindi riesegui pnpm ui:build dopo modifiche in ui/ oppure usa pnpm ui:dev mentre sviluppi la Control UI.

​
2) Puntare l’app macOS al Gateway in esecuzione

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

​
3) Verificare

  • Lo stato del Gateway nell’app dovrebbe mostrare “Utilizzo del gateway esistente …”
  • Oppure tramite CLI:
openclaw health

​
Errori comuni

  • Porta sbagliata: il WS del Gateway usa come predefinito ws://127.0.0.1:18789; mantieni app e CLI sulla stessa porta.
  • Dove vive lo stato:
    • Stato canale/provider: ~/.openclaw/credentials/
    • Profili di autenticazione modello: ~/.openclaw/agents/<agentId>/agent/auth-profiles.json
    • Sessioni: ~/.openclaw/agents/<agentId>/sessions/
    • Log: /tmp/openclaw/

​
Mappa dell’archiviazione delle credenziali

Usala quando esegui il debug dell’autenticazione o decidi cosa salvare in backup:
  • WhatsApp: ~/.openclaw/credentials/whatsapp/<accountId>/creds.json
  • Token bot Telegram: configurazione/env o channels.telegram.tokenFile (solo file normale; symlink rifiutati)
  • Token bot Discord: configurazione/env o SecretRef (provider env/file/exec)
  • Token Slack: configurazione/env (channels.slack.*)
  • Allowlist di abbinamento:
    • ~/.openclaw/credentials/<channel>-allowFrom.json (account predefinito)
    • ~/.openclaw/credentials/<channel>-<accountId>-allowFrom.json (account non predefiniti)
  • Profili di autenticazione modello: ~/.openclaw/agents/<agentId>/agent/auth-profiles.json
  • Payload dei segreti basato su file (opzionale): ~/.openclaw/secrets.json
  • Importazione OAuth legacy: ~/.openclaw/credentials/oauth.json Maggiori dettagli: Sicurezza.

​
Aggiornare (senza rovinare la configurazione)

  • Mantieni ~/.openclaw/workspace e ~/.openclaw/ come “le tue cose”; non inserire prompt/config personali nel repo openclaw.
  • Aggiornare il sorgente: git pull + pnpm install + continua a usare pnpm gateway:watch.

​
Linux (servizio utente systemd)

Le installazioni Linux usano un servizio utente systemd. Per impostazione predefinita, systemd arresta i servizi utente al logout/in inattività, il che termina il Gateway. L’onboarding tenta di abilitare il lingering per te (potrebbe chiedere sudo). Se è ancora disattivato, esegui: 
sudo loginctl enable-linger $USER
Per server sempre attivi o multiutente, considera un servizio di sistema invece di un servizio utente (lingering non necessario). Consulta il Runbook del Gateway per le note su systemd.

​
Documenti correlati