Skip to main content
OpenClaw.app non include Node né il runtime del Gateway. L’app macOS richiede un’installazione esterna della CLI openclaw, non avvia il Gateway come processo figlio e gestisce un servizio launchd per utente per mantenere il Gateway in esecuzione (oppure si collega a un Gateway locale già in esecuzione).

​
Configurazione automatica

Su un Mac nuovo, selezionare This Mac durante la configurazione iniziale. L’app esegue il proprio script di installazione firmato e incluso prima della procedura guidata del Gateway: installa un runtime Node nello spazio utente e la CLI openclaw corrispondente in ~/.openclaw, quindi installa e avvia il servizio launchd per utente. Questo percorso non richiede Terminale, Homebrew né accesso amministrativo. L’app include solo lo script di installazione, non il payload di Node o del Gateway; la configurazione richiede una connessione Internet per scaricare il runtime e il pacchetto OpenClaw corrispondente.

​
Ripristino manuale

Per un’installazione manuale è consigliato Node 24.15+; funziona anche Node 22.22.3+. Installare openclaw globalmente:
Usare Retry setup dopo una configurazione automatica non riuscita. Se continua a non riuscire, installare manualmente la CLI con il comando precedente, quindi selezionare Check again durante la configurazione iniziale.

​
Launchd (Gateway come LaunchAgent)

Etichetta: ai.openclaw.gateway (profilo predefinito) oppure ai.openclaw.<profile> per un profilo denominato. Posizione del plist (per utente): ~/Library/LaunchAgents/ai.openclaw.gateway.plist (oppure ai.openclaw.<profile>.plist). L’app macOS gestisce l’installazione e l’aggiornamento del LaunchAgent per il profilo predefinito in modalità locale. Anche la CLI può installarlo direttamente: openclaw gateway install (i profili denominati vengono selezionati tramite la variabile di ambiente OPENCLAW_PROFILE). Comportamento:
  • “OpenClaw Active” abilita/disabilita il LaunchAgent.
  • La chiusura dell’app non arresta il Gateway (launchd lo mantiene in esecuzione).
  • Se un Gateway è già in esecuzione sulla porta configurata, l’app si collega a esso invece di avviarne uno nuovo.
Registrazione:
  • stdout di launchd: ~/Library/Logs/openclaw/gateway.log (i profili usano gateway-<profile>.log)
  • stderr di launchd: soppresso
  • Se l’host entra in un ciclo con ripetuti EADDRINUSE o riavvii rapidi, verificare la presenza di LaunchAgent ai.openclaw.gateway / ai.openclaw.node duplicati e la soluzione alternativa basata sul marcatore launchd in Risoluzione dei problemi del Gateway.

​
Compatibilità delle versioni

L’app macOS verifica la versione del Gateway rispetto alla propria versione. La configurazione iniziale esegue automaticamente la configurazione gestita quando una CLI esistente è assente o incompatibile. Usare Retry setup per ripetere l’installazione oppure Check again dopo aver ripristinato una CLI esterna.

​
Directory di stato su macOS

Conservare lo stato di OpenClaw su un disco locale non sincronizzato. Evitare iCloud Drive e altre cartelle sincronizzate con il cloud; la latenza di sincronizzazione e i blocchi dei file possono influire su sessioni, credenziali e stato del Gateway. Impostare OPENCLAW_STATE_DIR su un percorso locale solo quando è necessaria una sostituzione. openclaw doctor segnala i comuni percorsi di stato sincronizzati con il cloud e consiglia di tornare all’archiviazione locale. Vedere variabili di ambiente e Doctor.

​
Debug della connettività dell’app

Usare la CLI di debug per macOS da un checkout del codice sorgente per verificare lo stesso handshake WebSocket del Gateway e la stessa logica di rilevamento usati dall’app:
connect accetta --url, --token, --timeout, --probe e --json (oltre alle sostituzioni dell’identità del client; eseguire con --help per l’elenco completo). discover accetta --timeout, --json e --include-local. Confrontare l’output del rilevamento con openclaw gateway discover --json quando occorre distinguere il rilevamento della CLI dai problemi di connessione lato app.

​
Controllo rapido

Quindi:

​
Contenuti correlati