Gateway su macOS

OpenClaw.app non include più Node/Bun o il runtime 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 esistente se è già in esecuzione).

Configurazione automatica

Su un Mac nuovo, scegli Questo Mac durante l’onboarding. L’app esegue il suo installer firmato e incluso prima della procedura guidata 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 o accesso da amministratore.

L’app include lo script di installazione, non il payload Node o Gateway. La configurazione richiede quindi una connessione internet per scaricare il runtime e il pacchetto OpenClaw corrispondente.

Ripristino manuale

Node 24 è consigliato per un’installazione manuale. Funziona anche Node 22 LTS, attualmente 22.19+. Quindi installa openclaw globalmente:

npm install -g openclaw@<version>

Usa Riprova configurazione dopo una configurazione automatica non riuscita. Se anche questo non riesce, installa manualmente la CLI con il comando sopra, quindi scegli Controlla di nuovo nell’onboarding. Node rimane il runtime Gateway consigliato.

Launchd (Gateway come LaunchAgent)

Etichetta:

• ai.openclaw.gateway (o ai.openclaw.<profile>; il legacy com.openclaw.* può rimanere)

Posizione plist (per utente):

• ~/Library/LaunchAgents/ai.openclaw.gateway.plist (o ~/Library/LaunchAgents/ai.openclaw.<profile>.plist)

Gestore:

• L’app macOS gestisce installazione/aggiornamento del LaunchAgent in modalità locale.
• Anche la CLI può installarlo: openclaw gateway install.

Comportamento:

• "OpenClaw attivo" abilita/disabilita il LaunchAgent.
• L’uscita dall’app non arresta il gateway (launchd lo mantiene attivo).
• Se un Gateway è già in esecuzione sulla porta configurata, l’app vi si collega invece di avviarne uno nuovo.

Registrazione:

• stdout launchd: ~/Library/Logs/openclaw/gateway.log (i profili usano gateway-<profile>.log)
• stderr launchd: soppresso

Compatibilità delle versioni

L’app macOS controlla la versione del Gateway rispetto alla propria versione. L’onboarding esegue automaticamente la configurazione gestita quando una CLI esistente manca o è incompatibile. Usa Riprova configurazione per ripetere l’installazione o Controlla di nuovo dopo aver riparato una CLI esterna.

Directory di stato su macOS

Mantieni lo stato di OpenClaw su un disco locale non sincronizzato. Evita iCloud Drive e altre cartelle sincronizzate con il cloud, perché la latenza di sincronizzazione e i blocchi dei file possono influire su sessioni, credenziali e stato del Gateway.

Imposta OPENCLAW_STATE_DIR su un percorso locale solo quando serve un override. openclaw doctor avvisa dei percorsi di stato comuni sincronizzati con il cloud e consiglia di tornare all’archiviazione locale. Vedi variabili d’ambiente e Doctor.

Debug della connettività dell’app

Usa la CLI di debug macOS da un checkout sorgente per esercitare la stessa logica di handshake WebSocket e discovery del Gateway usata dall’app:

cd apps/macosswift run openclaw-mac connect --jsonswift run openclaw-mac discover --timeout 3000 --json

connect accetta --url, --token, --timeout e --json. discover accetta --timeout, --json e --include-local. Confronta l’output di discovery con openclaw gateway discover --json quando devi separare la discovery della CLI dai problemi di connessione lato app.

Controllo smoke

openclaw --version OPENCLAW_SKIP_CHANNELS=1 \OPENCLAW_SKIP_CANVAS_HOST=1 \openclaw gateway --port 18999 --bind loopback

Poi:

openclaw gateway call health --url ws://127.0.0.1:18999 --timeout 3000

Correlati

• app macOS
• runbook Gateway