Skip to main content

​
Configurazione per sviluppatori macOS

Compilare ed eseguire l’applicazione OpenClaw per macOS dal codice sorgente.

​
Prerequisiti

  • Xcode 26.2+ (toolchain Swift 6.2), sull’ultima versione di macOS disponibile in Software Update.
  • Node.js 24.15+ e pnpm per il Gateway, la CLI e gli script di pacchettizzazione. È supportato anche Node 22.22.3+.

​
1. Installare le dipendenze

​
2. Compilare e pacchettizzare l’app

Genera dist/OpenClaw.app. Senza un certificato Apple Developer ID, lo script ricorre alla firma ad hoc. Per le modalità di esecuzione per lo sviluppo, i flag di firma e la risoluzione dei problemi relativi al Team ID, consultare apps/macos/README.md. Ciclo di sviluppo rapido dalla radice del repository: scripts/restart-mac.sh (aggiungere --no-sign per la firma ad hoc; le autorizzazioni TCC non persistono con --no-sign).
Le app con firma ad hoc possono attivare richieste di sicurezza. Se l’app si arresta immediatamente con “Abort trap 6”, consultare Risoluzione dei problemi.

​
3. Installare la CLI e il Gateway

L’app pacchettizzata incorpora il programma di installazione canonico scripts/install-cli.sh. In un profilo nuovo, scegliere This Mac durante la configurazione iniziale; l’app installa la CLI in spazio utente e il runtime corrispondenti prima di avviare la procedura guidata del Gateway. Per il ripristino manuale dell’ambiente di sviluppo, installare autonomamente la CLI corrispondente:
Sono supportati anche pnpm add -g openclaw@<version> e bun add -g openclaw@<version>. Node rimane il runtime consigliato per il Gateway stesso.

​
Risoluzione dei problemi

​
Compilazione non riuscita: toolchain o SDK non corrispondente

La compilazione dell’app per macOS richiede l’SDK macOS più recente e la toolchain Swift 6.2 (Xcode 26.2+).
Se le versioni non corrispondono, aggiornare macOS/Xcode ed eseguire nuovamente la compilazione.

​
Arresto anomalo dell’app durante la concessione delle autorizzazioni

Se l’app si arresta in modo anomalo quando si tenta di consentire l’accesso a Speech Recognition o Microphone, la causa potrebbe essere una cache TCC danneggiata o una firma non corrispondente.
  1. Reimpostare le autorizzazioni TCC per l’ID bundle di debug:
  2. Se l’operazione non riesce, modificare temporaneamente BUNDLE_ID in scripts/package-mac-app.sh per forzare una configurazione pulita in macOS.

​
Gateway bloccato indefinitamente su “Starting…”

Verificare se un processo zombie occupa la porta:
Se la porta è occupata da un’esecuzione manuale, arrestarla (Ctrl+C) oppure, come ultima risorsa, terminare il PID individuato sopra.

​
Risorse correlate